MusicBrainz Picard/Internationalization

This page is intended for translators of the tagger Picard, its website and user guide, and people interested in the state of MusicBrainz Picard’s internationalization.

Getting started

For a general introduction about translation platform, projects, and languages, please refer to the more general page about translation.

Questions or problems

To discuss about:

• MusicBrainz Picard (or website or user guide) translation: Use the “translation” tag in the “MusicBrainz Picard” forum category.
• MusicBrainz Picard (or website or user guide) internationalization: Use the “internationalization” tag in the “MusicBrainz Picard” forum category.
• General translation/internationalization: Use the “Internationalization” forum category with the appropriate tags.

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

To report problems about:

• Picard: Search for PICARD internationalization/localization tickets and create a new ticket if not found.
• Picard Website: PW tickets with “internationalization” label and create a new ticket if not found.
• Picard User Guide: Search for PICARD internationalization/localization tickets in the “Documentation” component and create a new ticket if not found.

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

Versions

As development on Picard 3.x has started but Picard 2.x is still being maintained there are separate translation components for the app specific texts. This affects the components App, AppStream, Constants and Installer. For the most part the translatable strings are identical. Please focus on translating for Picard 3.x, as this is the current focus on development. The translations for identical strings will propagate to the translations of Picard 2.x. Update the translations for Picard 2.x for strings that are unavailable in 3.x.

Translation components

The following components are available for translation:

Under Picard project

App

This contains the user interface texts for the Picard application itself. Translations made here will be automatically included in future Picard releases. All translations are shipped, but only those that are reasonable complete will be made available for selection in the Picard options.

There is a special string translator-credits which is supposed to be set to the list of translators of the current language. If you have contributed to this translation and you want to be credited as a translator in Picard's about dialog, add your name to this list in the translation of this string in your language. It is your choice if and how you want to be credited. Both your real name or a nickname (e.g. your MusicBrainz username) are ok.

AppStream

The appstream metadata is used automatically by various software / app management tools on Linux, e.g. by GNOME Software or KDE Discover. An online example is the Picard page on Flathub.org. Translations made here will be automatically included in future Picard releases. The translated texts are also used for the Picard entry on the Windows Store. This needs to be updated manually. Changes made to these translations are checked from time to time and updated in the stores. Usually this is done on new Picard releases. The English text is also used for the Picard entry on Snapcraft, but translations are not supported there.

This resource also contains the translations for the XDG desktop file, which is used on compliant desktops (i.e. essentially all Linux / BSD desktops) to create the (localized) menu entry.

Constants

This contains additional texts that are used in Picard. Mainly this includes the list of languages and scripts for the artist name translation feature and some additional constant value like default script and profile names. Due to the long language list, this component contains a large number of strings to translate, but as it is used only in a very few places it has overall a lower impact on the localization of Picard. It is recommended that translators focus on translating the App component first.

Installer

These are translations for the Windows installer. Translations of the installer must be complete before they can be used. Only texts specific to Picard need to be translated. Other texts and their translations are part of the NSIS installer itself. The translations need to be explicitly enabled in the Picard source repository. Usually before a new Picard release is made new translations of the installer are checked and enabled if they have been 100% completed.

Only languages that are supported by the NSIS installer are acceptable. Before starting a new translations check the NSIS list of available languages.

Website

New languages for the Picard website must be explicitly enabled before they become visible. We will only enable languages that provide complete translation of the start, download and plugins pages.

New and updated translations will become visible online after a fresh deployment of the website. This usually happens as part of Picard releases.

Attributes and Countries

These components are taken from the MusicBrainz Server project, please see MusicBrainz Server/Internationalization for details. Country names are used for preferred country selection and for the suggestions when editing the release country tag. From the attributes component only a few parts are being used, namely the release types, release status, cover art types and medium formats.

Under Picard Docs project

Translations for the Picard User Guide. The translations are structured into separate components, one per chapter.

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; See the hard-coded list. 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.

Accelerator keys

Some labels for menus and buttons have characters prefixed by an ampersand, e.g. "&Save" or "E&xit". The key associated with the character following the ampersand can be used as an accelerator key, that means when navigating the e.g. File menu with keyboard the user can press the "s" key to save or "x" to exist. Inside the menu the accelerator key is shown underlined, e.g. "Save" or "Exit".

When translating a string with an accelerator key you should also mark one key in the translation as accelerator. Some guideline to choose a proper key:

• The character is not required to be the same as in the original string. Instead choose a character that the user can typically associate with the action.
• Labels in the same menu should use different accelerator keys. If two labels should have the same accelerator key, choose a different one for the less important action.
• Make sure the character is actually available as a key on the keyboard (with a typical keyboard layout for your language). Do not use characters that can only be typed with additional modifier keys (like Shift, Alt, Ctrl).
• If the text contains only characters that are not directly available on the keyboard you can choose to additionally add an accelerator key. For example the Chinese translations chose this approach and add the accelerators with Latin characters in parentheses, like "保存（&S）" for "&Save".

User Guide specific item

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.

Tips to get started

General

• Make yourself familiar with the above descriptions. Especially the sections about template variables, keyboard shortcuts and accelerator keys will be useful while translating Picard.
• Start slow with easy to translate strings.
• If you are unsure whether your translation is correct, check the "Needs editing" checkbox before saving. This way the translation will not yet be used and someone else can verify it.
• Try to be consistent with existing translations. Weblate provides access to a glossary on the right. Also look at the sections "Other occurrences" and "Automatic translations" below the translation editor. Automatic translations will show suggestions for similar strings from the translation memory (which is filled with translations from all the strings already translated).
• Consider the context. The section "Nearby strings" can help with that. Many strings also have an associated screenshot that shows the usage. When translating Picard itself it is also helpful to have Picard running while translating and look at how some string is actually used inside the app. When translating the website, look at the actual website etc.

Translating an existing language

If your language is already available good ways to start are:

• Look at "Strings marked for edit". Those strings have existing translation, but it needs to be checked before it can be used. Sometimes this is because the source string got small changes, sometimes the previous translator might have been unsure if the translation is correct. Check if the translation is correct and matches the source string. Correct it if necessary. If it is correct already, untick the "Needs editing" checkbox and save the string.
• Look at "Strings with any failing checks". Weblate performs a lot of quality checks, which include both checking correct use of technical variables but also issues like mismatched punctuation, leading / trailing whitespace or duplicate words. Either correct the translation or dismiss the check, if the translation is correct regardless. If unsure, just keep the check in place. Someone else can verify.

Translating into a new language

• If your language is not yet available, you can start a new translation of a translation component via Tools > "Start new translation" in the Weblate component view. For most components the language will be available directly for translation afterwards. For some components a request will be sent to the Picard maintainers.
• Please only start a new language if you really intent to work on it! Empty components without any content or only one or two strings translated are not helpful and will eventually get removed again.

• Start with one of the smaller components. The AppStream or Installer components are a good starting point. Both only have a small number of strings to translate without many special cases.

Development

The Picard code, its website code and user guide code, all use 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, website and documentation.