Skip to content

Translation Guidelines

Jump to bottom
NexaKnight edited this page May 13, 2026 · 3 revisions

Welcome, and thanks for helping translate Better Tray Icons. Every translation makes the extension more accessible to people who don't use English as their first language. This page explains how to add a new language, how to improve an existing one, and what kinds of contributions are and aren't accepted.

Before you start

  1. Check the po/ directory in the repository to see which languages already have a translation file.
  2. Open the issues tab and look for ongoing translation efforts. Someone may already be working on the language you have in mind.
  3. If you plan to add a new language, open an issue first with the title Translation: <language>. This keeps two people from doing the same work in parallel.
  4. If you want to improve an existing translation, you can open a pull request directly. A linked issue isn't required.
  5. Read the rest of this page before opening the pull request. The review goes faster if your translation already follows the conventions described here.

What you need

  • A GitHub account.
  • A text editor. For comfort, a dedicated PO editor like Poedit or Lokalize is recommended, but any plain text editor works.
  • Optionally gettext installed locally, so you can validate the file before submitting.

Anatomy of a .po entry

Every translatable string in the source code is mirrored in a .po file as a pair of lines:

msgid "Sync File"
msgstr "Synchronisations-Datei"
  • msgid is the original English text. It's taken from the source code and must never be changed.
  • msgstr is the translation in your target language. This is the value you fill in.

An empty msgstr "" means the entry has not been translated yet. A file may also contain a header block at the top with metadata about the language, the translator and the project. Adjust those fields when you add a new language, leave them alone otherwise.

Adding a new language

  1. Fork the repository on GitHub.
  2. In your fork, navigate to the po/ directory.
  3. Pick an existing .po file as your starting template. Copy it to a new file named after the locale code of the target language. Use the standard ISO 639 (Set 1) code, optionally with a country variant. For example, fr.po, es.po, pt_BR.po or zh_CN.po.
  4. Open the new file in your editor. Update the header block with your name, the year, the language name and the locale code. Leave fields like Project-Id-Version as they are.
  5. Translate each msgstr line below the matching msgid. The msgid line stays untouched.
  6. Save the file.
  7. Validate the syntax with the following command: 
    msgfmt -c -o /dev/null po/<lang>.po
    This catches missing quotes, unbalanced placeholders and similar typos. If it prints nothing, the file is valid.
  8. Compile the locales with the project script and verify the translation locally before opening the pull request.
  9. Commit the file and open a pull request against main.

Updating an existing translation

  1. Fork the repository.
  2. Open po/<lang>.po in your editor.
  3. Find the entries you want to improve and edit only the msgstr values.
  4. Validate the file with msgfmt -c -o /dev/null po/<lang>.po.
  5. Commit, push and open a pull request.

What to translate

Translate everything that the end user sees. Leave technical strings, identifiers and brand names alone.

Translate Leave as-is
User-facing labels, descriptions and tooltips Code identifiers in backticks like sync-file-path
Setting names and section titles File paths, shell commands and DBus names
Dialog text, confirmations and toasts Brand and product names like Better Tray Icons, GNOME, Nextcloud
Button and switch labels The msgid line itself

If a string contains placeholders like %s, %d or {name}, keep them exactly as they appear in the source. You can move them around inside the sentence if your target language needs a different word order, but you must not remove or rename them.

Best practices

  • Match GNOME conventions. Many languages already have an established GNOME translation style. When in doubt, look at how the system settings of your distro are translated and follow the same tone, formality and vocabulary.
  • Stay consistent within the file. If you translate a recurring term one way at the top of the file, use the same translation everywhere else. Mixed terminology confuses users.
  • Translate meaning, not words. A word-for-word translation often reads awkwardly. Rewrite the sentence so it feels natural in the target language, as long as the meaning stays intact.
  • Mind the length. UI elements have limited space. A translation that is twice as long as the original may wrap or get truncated. If a literal version is too long, rephrase rather than cut.
  • Punctuation and capitalization. Follow the rules of your target language, not English. German nouns are capitalized, French uses non-breaking spaces before some punctuation marks, Spanish uses inverted question marks at the start of questions, and so on.
  • Quotation marks. Use the marks that are standard in your language. German typically uses „..." while French uses « ... ».
  • Numbers and dates. Keep the source format unless the target language strictly requires another one.
  • Proofread. Read your translation out loud, or have a native speaker review it, before opening the pull request.

What is not accepted

The following contributions will be closed without merging.

  • Translations that introduce offensive, insulting, defamatory, harassing or otherwise harmful language.
  • Translations containing hate speech, slurs or discriminatory content of any kind.
  • Translations that promote or contain content which violates applicable laws, including but not limited to copyright infringement, incitement, harassment or illegal commercial activity.
  • Translations produced by machine translation without any human review. An automated draft is fine as a starting point, but a fluent or native speaker must verify and correct it before submission.
  • Translations that intentionally distort the meaning of the source string, for example as a joke or a protest.
  • Contributions submitted under a license incompatible with GPL v3 or later.

By opening a pull request you confirm that your contribution complies with these rules and that you hold the right to submit it under the project license.

Opening the pull request

  • One language per pull request. If you want to contribute to multiple languages, open a separate pull request for each one.
  • Use a clear title. Good examples are Add French translation or Improve German translation of the Sync dialog.
  • Mention any related issue in the description, so reviewers can find the context.
  • Be patient. Reviews can take a few days, especially when a native speaker reviewer for the target language has to be found.

Compiling locales

You don't need to compile the .mo files yourself. Maintainers run npm run compile-locales before publishing a release, which generates locale/<lang>/LC_MESSAGES/bettertrayicons.mo from every po/<lang>.po.

If you want to preview your translation locally before opening the pull request, run the same command on your machine and reload the extension. On X11, press Alt+F2 and type r. On Wayland, log out and back in.

Questions

If anything on this page is unclear, or you're unsure how to translate a specific string, open an issue with the translation label. A clarification in writing is always better than a guess.

Thanks again for helping translate Better Tray Icons.

Welcome, and thanks for helping translate Better Tray Icons. Every translation makes the extension more accessible to people who don't use English as their first language. This page explains how to add a new language, how to improve an existing one, and what kinds of contributions are and aren't accepted.

Before you start

  1. Check the po/ directory in the repository to see which languages already have a translation file.
  2. Open the issues tab and look for ongoing translation efforts. Someone may already be working on the language you have in mind.
  3. If you plan to add a new language, open an issue first with the title Translation: <language>. This keeps two people from doing the same work in parallel.
  4. If you want to improve an existing translation, you can open a pull request directly. A linked issue isn't required.
  5. Read the rest of this page before opening the pull request. The review goes faster if your translation already follows the conventions described here.

What you need

Anatomy of a .po entry

Every translatable string in the source code is mirrored in a .po file as a pair of lines:

msgid "Sync File"
msgstr "Synchronisations-Datei"
  • msgid is the original English text. It's taken from the source code and must never be changed.
  • msgstr is the translation in your target language. This is the value you fill in.

An empty msgstr "" means the entry has not been translated yet. A file may also contain a header block at the top with metadata about the language, the translator and the project. Adjust those fields when you add a new language, leave them alone otherwise.

Adding a new language

  1. Fork the repository on GitHub.
  2. In your fork, navigate to the po/ directory.
  3. Pick an existing .po file as your starting template. Copy it to a new file named after the locale code of the target language. Use the standard [ISO 639 (Set 1) code](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes), optionally with a country variant. For example, fr.po, es.po, pt_BR.po or zh_CN.po.
  4. Open the new file in your editor. Update the header block with your name, the year, the language name and the locale code. Leave fields like Project-Id-Version as they are.
  5. Translate each msgstr line below the matching msgid. The msgid line stays untouched.
  6. Save the file.
  7. Validate the syntax with the following command: 
    msgfmt -c -o /dev/null po/<lang>.po
    This catches missing quotes, unbalanced placeholders and similar typos. If it prints nothing, the file is valid.
  8. [Compile the locales](https://github.com/nexaknight/better-tray-icons/wiki/_new#compiling-locales) with the project script and verify the translation locally before opening the pull request.
  9. Commit the file and open a pull request against main.

Updating an existing translation

  1. Fork the repository.
  2. Open po/<lang>.po in your editor.
  3. Find the entries you want to improve and edit only the msgstr values.
  4. Validate the file with msgfmt -c -o /dev/null po/<lang>.po.
  5. Commit, push and open a pull request.

What to translate

Translate everything that the end user sees. Leave technical strings, identifiers and brand names alone.

Translate Leave as-is
User-facing labels, descriptions and tooltips Code identifiers in backticks like sync-file-path
Setting names and section titles File paths, shell commands and DBus names
Dialog text, confirmations and toasts Brand and product names like Better Tray Icons, GNOME, Nextcloud
Button and switch labels The msgid line itself

If a string contains placeholders like %s, %d or {name}, keep them exactly as they appear in the source. You can move them around inside the sentence if your target language needs a different word order, but you must not remove or rename them.

Best practices

  • Match GNOME conventions. Many languages already have an established GNOME translation style. When in doubt, look at how the system settings of your distro are translated and follow the same tone, formality and vocabulary.
  • Stay consistent within the file. If you translate a recurring term one way at the top of the file, use the same translation everywhere else. Mixed terminology confuses users.
  • Translate meaning, not words. A word-for-word translation often reads awkwardly. Rewrite the sentence so it feels natural in the target language, as long as the meaning stays intact.
  • Mind the length. UI elements have limited space. A translation that is twice as long as the original may wrap or get truncated. If a literal version is too long, rephrase rather than cut.
  • Punctuation and capitalization. Follow the rules of your target language, not English. German nouns are capitalized, French uses non-breaking spaces before some punctuation marks, Spanish uses inverted question marks at the start of questions, and so on.
  • Quotation marks. Use the marks that are standard in your language. German typically uses „..." while French uses « ... ».
  • Numbers and dates. Keep the source format unless the target language strictly requires another one.
  • Proofread. Read your translation out loud, or have a native speaker review it, before opening the pull request.

What is not accepted

The following contributions will be closed without merging.

  • Translations that introduce offensive, insulting, defamatory, harassing or otherwise harmful language.
  • Translations containing hate speech, slurs or discriminatory content of any kind.
  • Translations that promote or contain content which violates applicable laws, including but not limited to copyright infringement, incitement, harassment or illegal commercial activity.
  • Translations produced by machine translation without any human review. An automated draft is fine as a starting point, but a fluent or native speaker must verify and correct it before submission.
  • Translations that intentionally distort the meaning of the source string, for example as a joke or a protest.
  • Contributions submitted under a license incompatible with GPL v3 or later.

By opening a pull request you confirm that your contribution complies with these rules and that you hold the right to submit it under the project license.

Opening the pull request

  • One language per pull request. If you want to contribute to multiple languages, open a separate pull request for each one.
  • Use a clear title. Good examples are Add French translation or Improve German translation of the Sync dialog.
  • Mention any related issue in the description, so reviewers can find the context.
  • Be patient. Reviews can take a few days, especially when a native speaker reviewer for the target language has to be found.

Compiling locales

You don't need to compile the .mo files yourself. Maintainers run npm run compile-locales before publishing a release, which generates locale/<lang>/LC_MESSAGES/bettertrayicons.mo from every po/<lang>.po.

If you want to preview your translation locally before opening the pull request, run the same command on your machine and reload the extension. On X11, press Alt+F2 and type r. On Wayland, log out and back in.

Questions

If anything on this page is unclear, or you're unsure how to translate a specific string, open an issue with the translation label. A clarification in writing is always better than a guess.

Thanks again for helping translate Better Tray Icons.

Clone this wiki locally