This article explains how you can help translate RawTherapee's interface.
RawTherapee's graphical user interface contains text in many places. In order to allow showing this text in various languages, the code contains only a key, and whenever text is meant to be displayed the code looks for that key in a plain-text key--value pair translation file, which corresponds to the language selected by the user (or auto-detected by RawTherapee, based on system settings). When a key is found in the chosen translation file, they key's value is used. If not found, the English value is used as a fallback.
The file which contains the reference key--value pairs is called
default. It uses American English. All translations are based on this file. Whenever a key is not found in a translation, the value from this file is used.
Translation files reside in
Every once in a while we run the
/tools/generateTranslationDiffs script which updates each translation file with new keys from the
default file. If a new key--value pair is added to
default, the script copies this pair into the translation file if it did not exist, and since the value at that point is in English it prefixes that line with an exclamation mark - when RawTherapee looks for a translated string, it ignores lines prefixed with an exclamation mark. When someone translates that value, they must remove the exclamation mark so that it stops being ignored.
A shortcoming of the system is that if a key's value in the
default file changes and that entry has already been translated, then the translation becomes outdated and this fact is not marked in any way. For this reason people maintaining a translation need to keep an eye on changes to existing values in
default and update their translation accordingly. One way of keeping an eye on changes to
default is by checking git commits which affect that file.
Using the "Exposure compensation" label as an example:
- The key used in the code is
defaultfile contains the key--value pair:
English (US)file contains the same pair, but prefixed with an exclamation mark:
- Translations should contain the key with the value translated and the exclamation mark removed, e.g.:
- Check whether there is an existing translation file of the language into which you're interested in translating by looking into
- If one does not exist, download the
English (US)file (right-click the "Raw" button and "Save link as"), then rename it into your language - let's call it
Inuktitutfor the purpose of this article.
- If there is one, download it (right-click the "Raw" button and "Save link as").
- If one does not exist, download the
- Translate new strings.
Inuktitutin a modern text editor (Windows users: do not use "Notepad", get Notepad++ instead). All the strings that need translating are on lines that begin with an exclamation mark, you will find them at the end of the file if you're updating an existing translation. Translate them, and remove the exclamation mark prefix from each translated line.
- As an example, you would translate
- Update existing strings
- If your
Inuktitutfile has already been translated a long time ago, chances are that some of the translated parts are out of date. To update them, open the latest
defaultfile in a window covering the right half of your screen, open
Inuktitutin a window covering the left half of your screen, then go through each already-translated string in
Inuktitut, compare it to the English string in
default, and update the translation if it no longer matches the English string.
- If your
- When done translating, open a new issue in GitHub and attach your translation to it. Please do not create patch files of translations, just send us the whole translated file. We will then run it through the
/tools/generateTranslationDiffsscript which will sort the entries, add new keys, and delete ones which are no longer used. We will then commit it to the codebase.
- When you want to update your translation in the future, you must download the latest version of that file from the repository from
Some lines have elements which should appear in bold or italics, or have characters which must be written in a special way. This is accomplished using markup. However, parsing markup is slightly slower than parsing plain text, so RawTherapee only supports markup on keys which we know to require it. That means that if you use markup on keys which do not support it, then those keys will not display correctly. Always stick to the style used in
default. If a key in
default does not use markup then neither should your translation.
When a key uses markup, certain characters must be written using their HTML character entity reference name:
How to know when markup is needed? Look at
default. For example:
HISTORY_MSG_251;B&W - Algorithmuses markup to display the
&character, and so should your translation.
PARTIALPASTE_RAWCACORR_CAREDBLUE;CA red & bluedoes not use markup to display the
&character, and neither should your translation.
FILEBROWSER_EMPTYTRASHHINT;<b>Permanently</b> delete all files in trash.uses markup to make the word "Permanently" appear in bold when displayed in RawTherapee, and so should your translation.