MusicBrainz Picard/Internationalization: Difference between revisions

From MusicBrainz Wiki
Jump to navigationJump to search
(Hide pending url.)
(Add note about formatting with asterisks.)
(One intermediate revision by the same user not shown)
Line 25: Line 25:
The language displayed can be selected from the currently available translations for the [https://picard.musicbrainz.org/ Picard website], the Picard program itself and the [https://picard-docs.musicbrainz.org/ 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.
The language displayed can be selected from the currently available translations for the [https://picard.musicbrainz.org/ Picard website], the Picard program itself and the [https://picard-docs.musicbrainz.org/ 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 ==
== User Guide Translation Specifics ==

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

=== Tags and Variables ===


<span style="color: red;"><b>NOTE:</b> This section is a placeholder and needs to be revised.</span>
<span style="color: red;"><b>NOTE:</b> This section is a placeholder and needs to be revised.</span>
Line 44: Line 40:
** <code>{instrument:%|instruments}</code> will be replaced by ''piano'' (or its translation) if the related instrument is “piano”, otherwise it will be replaced by ''instruments''.
** <code>{instrument:%|instruments}</code> will be replaced by ''piano'' (or its translation) if the related instrument is “piano”, otherwise it will be replaced by ''instruments''.


== User Guide Translation Specific Items ==
=== Special Formatting ===


The User Guide contains a number of items that must be retained as-is and not be translated. These types of items include:
<span style="color: red;"><b>NOTE:</b> This section is a placeholder and needs to be revised.</span>

=== 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:
** <code>**album** - Title of the release.</code> 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.
** <span style="color: red;">(add other examples)</span>

* 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:
** <code>**_multiartist** - Set to 1 if not all of the tracks on the album have the same primary artist, otherwise empty.</code> 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.
** <span style="color: red;">(add other examples)</span>

* Function names begin with a dollar sign ($), and should never be translated. Some examples include:
** <code>$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.</code> 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).
** <span style="color: red;">(add other examples)</span>

=== 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:
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 (`). Some examples include:
* 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:
** <code>:doc:`/about/acknowledgements`</code> 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.
** :doc:`/about/acknowledgements`
** <code>:index:`Acknowledgements <acknowledgements>`</code> 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.
** (add other examples)
** <span style="color: red;">(add other examples)</span>
* Directives are typically shown with the directive immediately proceeded by two periods (..) and may be immediately followed by one or two colons (:). Some examples include:

** (add examples)
* 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:
* Links are shown as
** <code>.. note::</code> 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.
** (add examples)
** <span style="color: red;">(add other examples)</span>

* 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. Some examples include:
** <code>`MusicBrainz website <https://musicbrainz.org/>`_</code> 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).
** <span style="color: red;">(add other examples)</span>

* 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:
** <code>Adds ``y`` to ``x``.</code> In this case all of the text should be updated, but the backtick pairs should remain intact.
** <code>This sentence includes **bold** and *italic* text.</code> In this case all of the text should be updated, but the asterisks and asterisk pairs should remain intact.
** <span style="color: red;">(add other examples)</span>


[[Category:To Be Reviewed]] [[Category:Internationalization]]
[[Category:To Be Reviewed]] [[Category:Internationalization]]

Revision as of 23:32, 26 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.

Communication

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

For instant 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

NOTE: This section is a placeholder and needs to be revised.

Translatable messages not only contain plain text or HTML markup, they can also contain replaceable variables. For example:

  • In {entity1} has a BookBrainz page at {entity0}, which is a URL-Work relationship link phrase, there are two entity variables whose name should not be translated, since variable {entity1} will be replaced by a work title and {entity0} by a URL.
  • In link phrases, variables are often used for (optional) attributes, in order to avoid inflating the number of messages. Below are examples with the “additional” attribute:
    • {additional} will be replaced by additional if the “additional” attribute is set, otherwise it will be removed from the text.
    • {additional:additionally} will be replaced by additionally if the “additional” attribute is set, otherwise it will be removed from the text.
    • {additional:an|a} will be replaced by an if the “additional” attribute is set, otherwise it will be replaced by a.
    • {additional:%|regular} will be replaced by additional if the “additional” attribute is set, otherwise it will be replaced by regular.
    • Hence, {additional} can be translated as {additional:aldona} in Esperanto.
  • Note that {instrument} and {vocals} variables are replaced by the specific instrument/vocals name:
    • {instrument:%|instruments} will be replaced by piano (or its translation) if the related instrument is “piano”, otherwise it will be replaced by instruments.

User Guide Translation 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.
    • (add other examples)
  • 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.
    • (add other examples)
  • 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).
    • (add other examples)

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.
    • (add other examples)
  • 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.
    • (add other examples)
  • 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. Some examples include:
    • `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).
    • (add other examples)
  • 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.
    • (add other examples)