Add a new translation

How to add a new translation to Birdtray

Thank you very much for your time and effort! To help you add a new translation with as little effort as possible, you can follow these steps:

1. To add a new translation to Birdtray, you need to find out the language tag for the language you want to add.

2. Once you now the language tag of your language, crate a copy of the main_en.ts, dynamic_en.ts and installer_en.ts files from the translations directory in the same directory and replace the en with your language tag. You can use the short language tag (e.g. en instead of en_US), if there isn't another translation with the same short language tag already.

   To create the copies and make the changes it it best to create a fork of this repository using the button on the upper right on GitHub. Then you can make the changes in your fork and create one pull request in the end with all of your changes included, instead of creating one pull request per file, which is not preferred. If you need some guidance on how to work with forks, there is some help here (ignore the git part and everything involving the command line, it is not required, you can do everything online with GitHub).

3. Now open the new files with a text editor and find the line near the top that looks like this: <TS version="2.1" language="en_US">. Replace the en_US with your new language tag.

4. In order for Birdtray to find the new translation files, you need to edit the CMakeLists.txt file and add them to the appropriate list. (Replace the main_xx.ts and dynamic_xx.ts with the real names of your new translation files):

    set(MAIN_TRANSLATION_FILES
            src/translations/main_en.ts
            src/translations/main_de.ts
            src/translations/main_nl.ts
+           src/translations/main_xx.ts
            )
    set(DYN_TRANSLATION_FILES
            src/translations/dynamic_en.ts
            src/translations/dynamic_de.ts
            src/translations/dynamic_nl.ts
+           src/translations/dynamic_xx.ts
            )

5. Now you can edit the new translation files as described here.
6. The installer_xx.ts file requires some extra attention: Near the top of the file you will find a __LANGUAGE_NAME__ entry. The translation must be the name of one of the NSIS translation files here without the file extension (e.g. English.nsh becomes English).
7. We also need to add the translation of your language name to all installer_xx.ts files (including your new one). To do so, start by adding the following to the end of the installer_en.ts file:

    <message>
        <source>XXX</source>
        <translation>Lang_xx</translation>
    </message>

   Replace the xx with the language code you used for your installer_xx.ts file and XXX with the English translation of your language name. You can search for the translation of your language name in English on the Internet. For example, if you were to add German translations, you would add the following to the end of installer_en.ts:

    <message>
        <source>German</source>
        <translation>Lang_de</translation>
    </message>

   Once that is complete, copy the whole new message entry and add it to the end of every remaining installer_xx.ts file:

    <message>
        <source>XXX</source>
        <translation>YYY</translation>
    </message>

   XXX should be the English translation. Now replace the YYY-part with the translation of your language name in the language of the current file. Again, you can search for the translation of your language name in a particular language on the Internet.

Once you are done, you can add your GitHub username (and real name, if you want) to the translators file (Please read the Translators file section below before you do that). All that is left to do now is to create a pull request with your changes to the Birdtray repository. Please don't create a separate pull request per file, include all changes in one pull request. Thank you again for your effort!

After submitting the pull request

Once you submitted your pull request, you will see at the bottom of the pull request page that some automatic checks are performed. These can take a bit of time to complete, but once they are done they will tell you if they found some issues with your changes in the pull request.

If you see red in the circle, it means that at least one mayor problem was found:

If you see a green check mark, your changes don't have any major problems.

But there might still be some minor issues. To see those, click on the button and scroll down and look for comments like these:

If the checks find a problem or some warnings, please edit the files in your pull request to address the problem.

If a warning is invalid (because your language handles things differently then what the checker expects), you can suppress the warning by adding a translatorcomment as shown here:

    <message>
        <source>Some source text that ends in a dot.</source>
        <translatorcomment>checkTranslation ignore: punctuation_end_differ</translatorcomment>
        <translation>Some translation that does not end in a dot</translation>
    </message>

If you are using the Qt Linguist you can use the Translator comments for ... field.

The punctuation_end_differ in the example above is the id of the warning. It is included in brackets at the end of the message.

So if you want to suppress a different warning, then replace the punctuation_end_differ in the example above with the id of your warning. If you need to suppress multiple warnings for one translation, you can add multiple warning ids by separating them with a comma like this:

        <translatorcomment>checkTranslation ignore: punctuation_end_differ,indentation_wrong_end</translatorcomment>

Translators file

The translators file will be displayed by Birdtray when somebody opens the Translators dialog in the About tab in the settings. The file contains two lists. If you want to keep your translation updated, you can add your name to the Active maintainers list and we will notify you on GitHub a few weeks before we create a new release of Birdtray. Birdtray is in active development, the texts of the user interface can change and new texts are added. We really appreciate it if you are able to keep the translation updated and we want to make that as easy as possible for you. This way you don't have to constantly update the translation, only when we release a new version. If at any time you don't want to maintain the translation anymore, just create a new pull request here on GitHub and move your name to the second list.

Language tag

All translation are connected to their language via the language tag of that language. The language tag consists of the ISO 639‑1 code and optionally the ISO 3166-1 alpha-2 country code joined with a _ (e.g. en for English or en_US for American English).