Translating RawTherapee

Translating RawTherapee

This article explains how you can help translate RawTherapee's interface.

Introduction

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 /rtdata/languages

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 TP_EXPOSURE_EXPCOMP.
• The default file contains the key--value pair:

  TP_EXPOSURE_EXPCOMP;Exposure compensation

• The English (US) file contains the same pair, but prefixed with an exclamation mark:

  !TP_EXPOSURE_EXPCOMP;Exposure compensation

• Translations should contain the key with the value translated and the exclamation mark removed, e.g.:

  TP_EXPOSURE_EXPCOMP;Lorem ipsum

How To

1. Check whether there is an existing translation file of the language into which you're interested in translating by looking into /rtdata/languages
   • 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 Inuktitut for the purpose of this article.
   • If there is one, download it (right-click the "Raw" button and "Save link as").
2. Translate new strings.

   Open Inuktitut in 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

   !TP_EXPOSURE_EXPCOMP;Exposure compensation

   to

   TP_EXPOSURE_EXPCOMP;Lorem ipsum

3. Update existing strings

   If your Inuktitut file 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 default file in a window covering the right half of your screen, open Inuktitut in 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.

4. 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/generateTranslationDiffs script which will sort the entries, add new keys, and delete ones which are no longer used. We will then commit it to the codebase.
5. When you want to update your translation in the future, you must download the latest version of that file from the repository from /rtdata/languages

Markup

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:

• Write < using <
• Write > using >
• Write & using &

How to know when markup is needed? Look at default. For example:

• HISTORY_MSG_251;B&W - Algorithm uses markup to display the & character, and so should your translation.
• PARTIALPASTE_RAWCACORR_CAREDBLUE;CA red & blue does 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.