eGauge Internationalization (I18N) Instructions
How to Translate the eGauge User Interface
All user-visible strings for the eGauge User Interface are stored in a single file called the PO-file. To update an existing translation, please download the PO-file for the desired language, edit it as needed, then send us the updated file.
To create a translation for a new language, please download the messages.pot file and rename that to LANGUAGE_CODE.po, where LANGUAGE_CODE is the code for the language your translating to. You don’t need to worry about selecting the appropriate LANGUAGE_CODE if you are not sure – just use something unique so we can tell what language it is (for example, italian.po if you were to translate to Italian). Once you have this file, edit it as needed and then send it to us for review.
How to Edit a PO-File
The PO-file is a plain text file so you can use any text-editor to modify it. However, since the file has some special formatting-requirements, it is usually much easier to use Poedit for this purpose. Poedit is open-source and available pre-built for Windows, OS X, and most versions of Linux.
Poedit is quite easy to use but here are some tips:
- Make sure notes for the translators are being displayed, since those often contain useful tips on how something needs to be translated. This can be done with View → Display Notes for Translators. If you find the comments do not clarify something, feel free to ask us.
- We find it most convenient to sort the translatable strings by source. That way, similar things tend to be grouped together. You can do this with View → Sort by Source.
- When opening a PO-file, untranslated entries are normally shown first, in bold typeface. Next are “fuzzy” translations, shown in orange. Fuzzy translations get created when something changes in the user-interface and the system finds a similar translation but not an exact match. These usually require double-checking to verify that the translation is correct. If the translation is already correct, you can make a dummy change (e.g., add a blank and then delete it) to mark the translation as “current” (the “fuzzy” translation will be marked as an exact translation that way).
Translating Multi-Line Entries
Most translations are just a single word, phrase or sentence. However, some translations, especially the ones for the Help page, are multiple paragraphs long with embedded HTML formatting. Special care needs to be taken to translate such entries:
- Poedit is a bit picky about newlines: if an entry in English starts and/or ends with a new line-sequence (“\n”, i.e., backslash character followed by letter “n”), the translated entry also needs to start and/or end with a new line-sequence.
- Newline characters are dropped when the file is saved. For example:
will by transformed to “word1word2” when saved. It is therefore best to just use blanks to separate words. If you want a newline that gets preserved across saves, use the new line-sequence “\n”.
- We recommend using Ctrl-B to copy the English language version of the text into the Translation box and then edit the English text rather than typing everything from scratch. This makes it much less likely that an HTML tag is missed or misplaced.
- Try to preserve the HTML markup as much as possible. Also, don’t translate all words blindly. For example,
defines an anchor point named “foobar”. Since this is not a user-visible strings, it should NOT be translated. If you do translate such entries, it’ll likely break the user-interface since there may be other code that refers to the “foobar” name.
Variable Names in Translations
Some translations contain variable parts. When using a translation, software takes care of replacing the placeholders for the variable parts with actual values (which are already translated). Placeholders start with a percent sign (%). What follows the percent sign depends on the programming language of where the string appears:
- C: % is followed by a formatting code such as “s” for a string or “d” for a number.
- Python: % is usually followed by a variable-name in parentheses, followed by a formatting code such as “s” for a string. For example, “%(DEVNAME)s” would be replaced by the contents of variable DEVNAME, formatted as a string.
The translator comments will normally indicate what the placeholders are for to make it easy to figure out how to translate the strings.
Date/Time Formatting and Parsing
The eGauge user-interface uses patterns to assist in translating dates and times to user-readable strings. Similarly, patterns are used to specify how a date and/or time may be entered. Please see the Datetime Tester page for details.
Submitting an Updated/New PO-File
Please send any PO-File work to firstname.lastname@example.org for review.