Translation mechanism

[arnoud]

To make the ScanCircle website, scan program and mailings multi-lingual, the international GNU gettext standard (see https://gnu.org/software/gettext/manual/gettext.html) has been adopted. This works with the following file types:

1. .pot: the translation template containing all keywords (msgid) including instructions for the translator. There is only 1 .pot file for each domain and it is used by ScanCircle to create and update the .po files before distributing it to the translator;
   
2. .po: the translation file containing all translations (msgstr) including comments by the translator. There is 1 .po file per language for each .pot file and it is updated by the translator using a .po file editor and sent back to ScanCircle when completed;
   
3. .mo: the compiled translation file. There is 1 .mo file for each .po file, it is created by ScanCircle from the .po file and used by the applications to retrieve the translations for specific keywords within a specific domain in a specific language.
   

The following domains are used:

1. Scanner: minimal definitions for the scan program (about 50 phrases*);
   
2. Global: the global definitions, mainly for the website (about 450 phrases*);
   
3. Results: definitions for scan results, registrations and end-user mailings (about 650 phrases*);
   
4. Partner: definitions for partner program, partner mailings and invoices (400-450 phrases*). Since this is only for interaction with partners, translation is optional (defaults to English).
   

In most gettext implementations, the msgid contains the original (English) text itself. However, a slightly different approach was chosen because:

1. a lot of the output (e.g. menus, pages, lists, advices, mailings, invoices) is generated programmatically which means that the keyword should not be free text;
   
2. the MVC implementation on the website does not allow special characters in parameters;
   
3. the original English text may need corrections (would require changing the msgid).
   

So instead, the msgid contains a tag like "home:easy:desc" (home page, easy block, description). Unfortunately, this would mean that the original English text is missing in the .po file which makes it difficult for the translator. Also most .po file editors expect the msgid to contain the original (English) text in order to offer automated translations from previous or machine translations. Therefore, for the translators, the msgid value (tag) is moved to the msgctxt field (message context) and the msgid is replaced with the original English text. This also has the advantage that in some .po file editors, the msgctxt field (which is an indication where the text is used) is shown as well and that the msgid in combination with the msgctxt is always unique (because the msgctxt always is, where the original English text might not be). To differentiate between the normal .po and .pot files, these files are named .xlt.po and .xlt.pot. When the translation in the .xlt.po file is completed, this process will be reversed before creating the .mo file. So the translator will not see much difference other than the extra message context field.

Translation tips:

1. Download POEdit from www.poedit.net (the free version suffices) or use another .po file editor;
   
2. When ScanCircle creates a .xlt.po file for a new language, machine translations will be used to prefill the msgstr fields. Although this helps with about 90% of the translation, it may be in the completely incorrect context. Therefore all machine translations will be marked “fuzzy” meaning that they require your attention so please check this carefully and update the translation or turn off the “Needs work” option;
   
3. During the creation of the .xlt.po file, some special characters in the original text are counted. If the translated text contains less or more of these characters, this is logged as a “translator comment” (shown as a text balloon icon in POEdit). Please note that these comments may be incorrect, so optionally adjust the translation and remove the comment when handled;
   
4. If the language has a formal and informal version (e.g. French vous/toi, German Sie/du), then use the formal version but it should not be over-polite;
   
5. Try and keep the translations about the same length as the original, especially if it concerns headers or labels, unless it negatively affects the translation;
   
6. Leave the *bold*, _italics_, [links], %s parameters and newlines (\n) in the translation and don’t use double quotes (");
   
7. Please pay special attention to singular/plural translations (date/time units in the global domain) and make sure you check both translations (shown in separate tabs in POEdit);
   
8. If in doubt about a certain translation, please check with ScanCircle or add a translator comment. Also please inform ScanCircle about any errors in the original English text;
   
9. If any updates are required to the original English text, the .xlt.pot file will be updated by ScanCircle and the original English text will be included as the “previous untranslated string”. The .xlt.pot file will then be used to update the .xlt.po files, causing the previous translation to be marked “Needs work”. The original English text is also shown to the translator until he/she updates the translation or turns off the “Needs work” indicator;
   
10. Before returning the .xlt.po file to ScanCircle, first save your changes. In POEdit, this will perform some extra checks (warnings shown as a yellow triangle icon in the left margin). Enable “View > Input with errors first”, but note that these warnings may be incorrect;
    
11. Next, use the “Validate” function of the .po file editor, to make sure there are no other errors and no more translations that require your attention. Also check if all translator comments (text balloons in the left margin in POEdit) have been accounted for;
    
12. Do not manually edit the .xlt.po file and certainly do not change the msgctxt or the order within the .xlt.po file (it is okay to view the .xlt.po file in a different order in a .po file editor);
    
13. If you have manually edited the .xlt.po file and cannot open it anymore using the .po file editor, the file may contain non-UTF8 characters. Please replace these by their UFT-8 equivalents.
    

For the moment, the exchange of .xlt.po files from ScanCircle to the translator and back will be done by means of email. At a later stage, a translation platform like Pootle may be used.

If you want to contribute and translate ScanCircle to your local language, please reply to this post or send me an email or Private Message using the buttons below.

---

*) A phrase can be 1 word, 1 line or a number of lines.