MusicBrainz Picard/Internationalization: Difference between revisions

From MusicBrainz Wiki
Jump to navigationJump to search
No edit summary
(2 intermediate revisions by the same user not shown)
Line 47: Line 47:
* <code>Learn about the new features in Picard {version}</code> indicates that the variable "version" is to be replaced when the page is generated. In this case, "version" should not be translated while the rest of the phrase should be translated.
* <code>Learn about the new features in Picard {version}</code> indicates that the variable "version" is to be replaced when the page is generated. In this case, "version" should not be translated while the rest of the phrase should be translated.
* <code>Found an Issue? {url|Report Here}</code> indicates that the variable "url" is to be replaced when the page is generated. In this case, "url" should not be translated while the rest of the phrase should be translated, including the description "Report Here".
* <code>Found an Issue? {url|Report Here}</code> indicates that the variable "url" is to be replaced when the page is generated. In this case, "url" should not be translated while the rest of the phrase should be translated, including the description "Report Here".

== Keyboard shortcuts ==

=== Picard application ===

Several translation strings for Picard contain keyboard shortcuts like <code>Ctrl+Shift+S</code>. The key names '''must not''' be translated as those will get automatically localized in the application itself. In general the keyboard shortcuts ''should'' stay unchanged, unless a specific shortcut is not easily accessible on keyboards typically used for the translated locale. In this case the shortcut ''can'' be replaced with a better fitting one, but the modifier keys must remain English (<code>Ctrl</code>, <code>Alt</code>, <code>Shift</code>).

=== User Guide ===

Keyboard shortcuts mentioned in the User Guide ''should'' be translated, if this is common for the target language. E.g. in the German translation <code>Ctrl</code> can be replaced with <code>Strg</code>.


== User Guide specific items ==
== User Guide specific items ==

Revision as of 17:32, 31 May 2023

Picard, Picard Website and Picard User Guide Internationalization

The code for Picard, the User Guide and the website uses gettext to provide the automatic translation of messages and texts used. One or more .pot files, in English, are provided with all the strings used in the application.

Getting started

If you want to help translate the text displayed in MusicBrainz Picard, the Picard website or the documentation in the Picard User Guide, go to the [TBD Weblate page] and create an account. The Picard translations are under the [TBD Picard] project and the User Guide translations are under the [TBD Picard Docs] project. If there is already a team for your language, you can join it, if not, you can ask for the creation of a new team.

NOTE: The Weblate page is currently under development and testing, and is NOT currently available for production use.

Questions or problems

The MetaBrainz community forums can be used (with categories and tags) for discussion beyond Weblate comments:

For more real-time interactive conversation with developers, you’re welcome to ask in the #metabrainz IRC channel.

If you find a mistake in the translations, or want to suggest changes, you can enter an issue in our bug tracker for the applicable project:

Viewing the translations

The language displayed can be selected from the currently available translations for the Picard website, the Picard program itself and the Picard User Guide. Note that the available languages only include those languages that have their translations substantially complete. You are welcome (and encouraged) to provide translations for additional languages.

Template variables

Translatable messages not only contain plain text or HTML markup, they can also contain replaceable variables. In Picard and the Sphinx template for the User Guide replaceable variables are indicated by enclosing the variable name within brackets with a percent sign (%) immediately preceeding the opening bracket and a single character indicating the type of variable immediately following the closing bracket (e,g, 's', 'r' or 'i'). For example:

  • Some examples from Picard include:
    • Looking up the metadata for cluster %(album)s... indicates that the variable "album" is to be replaced when the page is generated. In this case, "%(album)s" should not be translated while the rest of the phrase should be translated.
    • Removed %(count)i releases from collection "%(name)s" indicates that the variables "count" and "name" are to be replaced when the page is generated. In this case, "%(count)i" and "%(name)s" should not be translated while the rest of the phrase should be translated.
  • Some examples from the User Guide include:
    • Last updated on %(last_updated)s. indicates that the variable "last_updated" is to be replaced when the page is generated. In this case, "%(last_updated)s" should not be translated while the rest of the phrase should be translated.
    • Built with %(sphinx_web)s using a indicates that the variable "sphinx_web" is to be replaced when the page is generated. In this case, "%(sphinx_web)s" should not be translated while the rest of the phrase should be translated.
    • provided by %(readthedocs_web)s indicates that the variable "readthedocs_web" is to be replaced when the page is generated. In this case, "%(readthedocs_web)s" should not be translated while the rest of the phrase should be translated.

In some cases, a replacement is shown without specifying the replacement variable name. These should be handled similarly when providing the translation. Some examples from Picard include:

  • [could not load album %s] indicates that the variable "%s" is to be replaced with a string when the page is generated. In this case, "%s" should not be translated while the rest of the phrase should be translated.
  • List of %i items indicates that the variable "%i" is to be replaced with an integer when the page is generated. In this case, "%i" should not be translated while the rest of the phrase should be translated.
  • Plugin %r has an invalid API version string : %s indicates that the variables "%r" and "%s" are to be replaced when the page is generated. In this case, "%r" and "%s" should not be translated while the rest of the phrase should be translated.

In addition, a variable could be enclosed in braces ({}), with an optional description separated by a vertical bar (|) if the variable is a link. Some examples from the Picard website include:

  • Brought to you by {metabrainz} indicates that the variable "metabrainz" is to be replaced when the page is generated. In this case, "metabrainz" should not be translated while the rest of the phrase should be translated.
  • Learn about the new features in Picard {version} indicates that the variable "version" is to be replaced when the page is generated. In this case, "version" should not be translated while the rest of the phrase should be translated.
  • Found an Issue? {url|Report Here} indicates that the variable "url" is to be replaced when the page is generated. In this case, "url" should not be translated while the rest of the phrase should be translated, including the description "Report Here".

Keyboard shortcuts

Picard application

Several translation strings for Picard contain keyboard shortcuts like Ctrl+Shift+S. The key names must not be translated as those will get automatically localized in the application itself. In general the keyboard shortcuts should stay unchanged, unless a specific shortcut is not easily accessible on keyboards typically used for the translated locale. In this case the shortcut can be replaced with a better fitting one, but the modifier keys must remain English (Ctrl, Alt, Shift).

User Guide

Keyboard shortcuts mentioned in the User Guide should be translated, if this is common for the target language. E.g. in the German translation Ctrl can be replaced with Strg.

User Guide specific items

The User Guide contains a number of items that must be retained as-is and not be translated. These types of items include:

Tags, variables and functions

Some items in the documentation are hard coded and should not be translated. These include tag, variable and function names. The descriptions for these items can (and should) be translated, but the names themselves should not. For example:

  • Tag names when shown in use are surrounded by percent signs (%), but the percent signs are not shown when the tags are defined. Some examples include:
    • **album** - Title of the release. provides the definition of the tag "album" (which has been formatted as bold by surrounding it with double asterisks). In this case the tag name "album" should not be translated because it remains as "album" regardless of the language used, but the description "Title of the release." should be translated.
    • **conductor** - Conductor Relationship Type (releases, recordings), Chorus Master Relationship Type (releases, recordings) provides the definition of the tag "conductor" (which has been formatted as bold by surrounding it with double asterisks). In this case the tag name "conductor" should not be translated because it remains as "conductor" regardless of the language used, but the description should be translated.
  • Variable names begin with an underscore, and when they are shown in use are surrounded by percent signs (%), but the percent signs are not shown when the variables are defined. Some examples include:
    • **_multiartist** - Set to 1 if not all of the tracks on the album have the same primary artist, otherwise empty. provides the definition of the variable "_multiartist" (which has been formatted as bold by surrounding it with double asterisks). In this case the variable name "_multiartist" should not be translated because it remains as "_multiartist" regardless of the language used, but the description "Set to 1 if not all of the tracks on the album have the same primary artist, otherwise empty." should be translated.
    • **_dirname** - The name of the directory containing the file at the point of being loaded into Picard provides the definition of the variable "_dirname" (which has been formatted as bold by surrounding it with double asterisks). In this case the variable name "_dirname" should not be translated because it remains as "_dirname" regardless of the language used, but the description should be translated.
  • Function names begin with a dollar sign ($), and should never be translated. Some examples include:
    • $add(x,y,*args) - Adds ``y`` to ``x``. Can be used with an arbitrary number of arguments (i.e.: ``$add(x,y,z)`` = (x + y) + z). Returns an empty string if an argument is missing or not an integer. provides the definition of the "$add" scripting function. In this case the function name "$add" should not be translated, but the description of the function should be translated with special attention given to the formatting codes (see below).
    • $find(haystack,needle) - Returns the zero-based index of the first occurrence of ``needle`` in ``haystack``, or an empty string if ``needle`` was not found. The comparisons are case-sensitive. If ``needle`` is blank, it will match the beginning of ``haystack`` and return "0". The function does not support wildcards. provides the definition of the "$find" scripting function. In this case the function name "$find" should not be translated, but the description of the function (including the argument names "needle" and "haystack") should be translated with special attention given to the formatting codes (see below).

Special formatting

The Picard User Guide has been developed using Sphinx to convert the ReStructued Text (rst) files into the various output formats (i.e. html, epub and pdf). The translatable messages not only contain plain text or HTML markup, they can also contain Sphinx roles, directves and formatting information that must be retained (and not translated). For example:

  • Roles are typically shown as the role between colons (:) followed immediately by the role information surrounded by backticks (`). For roles, it is important not to add spaces between the directive and the surrounding colons, or around the backticks. Some examples include:
    • :doc:`/about/acknowledgements` indicates that a link to the "/about/acknowledgements" page should be inserted into the document, using the title from the "/about/acknowledgements" page as the link text. In this case both "doc" and "/about/acknowledgements" should not be translated.
    • :index:`Acknowledgements <acknowledgements>` indicates that a link to the word "Acknowledgements" should appear in the document index as "acknowledgements". In this case both "Acknowledgements" and "acknowledgements" should be translated, but "index" should not.
  • Directives are typically shown with the directive immediately proceeded by two periods (..) and a space, and may be immediately followed by one or two colons (:). For directives, it is important not to add or remove spaces between the periods and the directive, or between the directive and any following colons. Some examples include:
    • .. note:: indicates that the text that follows should be displayed in a "Note:" box. In each case, the directive (in this case "note") should not be translated.
    • .. warning:: indicates that the text that follows should be displayed in a "Warning:" box. In each case, the directive "warning" should not be translated.
  • Links are shown as the link text followed by the url enclosed in angle brackets (<>) all enclosed in backticks (`) immediately followed by an underscore (_). For links, it is important not to add or remove spaces around the backticks, the angle brackets or the underscore. For example:
    • `MusicBrainz website <https://musicbrainz.org/>`_ inserts a link to "https://musicbrainz.org/" with the link text "MusicBrainz website". In each case, the link text should be translated, but the link url should not (unless there is a different url for the translated language).
  • Sometimes text is formatted by surrounding it with a pair of backticks or one or more asterisks (*). In these cases, it is important that the backticks are not translated into apostrophes or single (or double) quotes, and there are no spaces added between the backticks or asterisks. Some examples include:
    • Adds ``y`` to ``x``. In this case all of the text should be updated, but the backtick pairs should remain intact.
    • This sentence includes **bold** and *italic* text. In this case all of the text should be updated, but the asterisks and asterisk pairs should remain intact.