Translate mAirList into Other Languages
From mAirListWiki
Although mAirList is written in English, all text in the GUI (in message boxes, menus, buttons, etc.) can be translated into any other language. This process is called localization, and this page explains how you can localize (translate) mAirList into another language.
Before you start work on any translation, make sure the work has not already been done. Check the current list of mAirList language files (.mo files) on the mAirList download page.
Contents |
A Little Theory
Before mAirList displays text in any screen control such as a button, menu, or dialog box, it first checks which language was selected in Configuration Options. For non-English languages, mAirList uses an internal process to display a translated version of the original English text (for the technically minded, the component used is dxgettext—a Delphi equivalent of GNU gettext).
In total, gettext uses three different types of files:
- Translation template (.pot)—a text file containing all the original (English) messages.
- Text catalog (.po)—a text file containing both the English and the translated messages.
- Binary catalog (.mo)—the file used by mAirList, which contains the same information as the text catalog (.po) file, but compiled into a binary format for faster access.
You can install any number of .mo files to add as many or as few extra languages as you need, but each file must be stored in a specific folder on your PC:
mAirList program folder\locale\country code\LC_MESSAGES\
An exception is the German language file, which is embedded into the mAirList.exe file, so there is no external file or folder for it.
There are more details below in Install Your .mo File.
To create a .mo file, download the template (.pot) file, rename the file to .po, then use the poEdit 'Translation Editor' Program (obtainable from www.poedit.org) to add your translated text strings. Each time you save your translations in poEdit, it creates a new .mo file for the language you are translating to.
poEdit 'Translation Editor' Program
Although you can edit .po files with any text editor, we strongly recommend that you use a purpose-built .po editor.
Our preferred and suggested editor is the freeware poEdit, which makes translation a very easy 'one stop' process, compared to the alternative of using a simple text editor and then running several command-line utilities to create the .mo file.
Download the Translation Template
Before starting translation, you need to download a copy of the translation template (.pot file). The template contains only the English text strings, with—in poEdit terms—an empty 'translations' column.
There are currently two templates, one for each major mAirList version:
Because the two major mAirList versions use slightly different text strings, separate translations are needed for each version. Please translate the stable (v2.0.x) version first, because most of the strings in the v2.0.x template also exist in the v2.1.x template.
If you want to create a translation for version v2.1.x, we suggest that you:
- Translate the v2.0.x file.
- Make a copy of your finished v2.0.x translation (.po file).
- Merge the v2.1.x template into your copy of the completed v2.0.x .po file (see Merging Changes below).
- Translate the remaining 'new' or changed text strings.
Prepare Your Translation
You need to do a few things before you start the translating work.
First, create the language folder as described above. For example, for a Spanish translation—assuming that mAirList is installed in C:\Program Files\mAirList—create the folder:
C:\Program Files\mAirList\locale\es\LC_MESSAGES
es is the two-letter ISO 639-1 country code for Spanish. For a list of valid codes, see this link.
Then download the translation template mAirList.pot (see links above) into that new folder and rename it to mAirList.po. Make sure that you have obtained the template for the correct release of mAirList (2.0 or 2.1). Double click the .po file, and poEdit will open:
In the upper part of the window, you see the translatable strings and their translation. The blue color means that the string has not been translated yet. The blank text field in the bottom left corner is where you write your translation. The white text fields at the right hand side indicate where the string is used in the source code. This is not too useful, as mAirList is closed-source, but the names give an idea of where the string will be displayed. In the above example, the string "New" is used in the main window (MainForm), as the caption of the "New" tool button (tbNew), and also in the Edit Event List window.
Before starting the translation, select Catalog->Settings from the main window, and the following dialog appears:
Fill out the form with the correct information:
- Project name and version: "mAirList 2.0" or "mAirList 2.1"
- Team: your name
- Team's email adress: your email adress
- Language: the language you are translating into
- Country: If you are translating into a special country-specific dialect, you can select the country here. Otherwise, enter the main country where that language is spoken.
- Charset: "UTF-8"
- Source code charset: "iso-8859-15"
Close the dialog, and you're ready to go!
Enter Your Translation in poEdit
You can now start your translation. Select a string which is not yet translated (indicated by a blue line the list), and enter your translation into the bottom left text field.
Hint: Use Shift+Ctrl+Up and Shift+Ctrl+Down to navigate through the list without using the mouse. If a string does not need to be translated, use Alt+C to copy it to the translation field.
Take Care With Variables!
Many strings contain variables, which start with a % character. These are 'placeholders' for information which mAirList will 'fill in' when the text is displayed. %s represents variable text, and %d represents a variable number. For example, the error message:
Error loading BASS plugin %s: Error code %d
contains two variables. The first represents the name of the BASS plugin which failed, and the second represents the (numeric) error code. Your translated strings MUST contain EVERY variable present in the original English string, and variables must be in the SAME ORDER as in the original English string! If you break this rule, errors will occur when mAirList attempts to display your translated string.
A valid German translation of the example above would be:
Fehler beim Laden des BASS-Plugins %s: Fehler %d
Note that both the original variables are present and in the same order as in the original English version.
The translation template contains about 500 strings. If you don't want to translate all of them in a row, you can save the .po file and continue the translation later. mAirList will also accept an incomplete translation file; the missing messages will be displayed in English.
Install Your Language File
When saving the mAirList.po catalog file, poEdit will automatically create or update the associated binary catalog file mAirList.mo, located in the same folder. This is the file which is actually loaded and used by mAirList.
As you are already working in the correct language folder, you do not need to copy or move the .mo file anywhere - it's already in the right place. If the translation language coincides with the system language configured in the Windows Control Panel, mAirList will also look for the file and load it automatically. Otherwise, or to make sure that the right translation file is loaded, open mAirListConfig and enter the two-letter country code into the "Show GUI in language" field on the "Miscallaneous" page.
If you want to install your language file on another PC, create the corresponding LC_MESSAGES folder as described above, and copy the mAirList.mo file into it.
Merging Changes
With each new version of mAirList, there might be new messages introduced in that version that must be translated. The mAirList.pot template file on the server is automatically updated with every new version uploaded. In order to fill the gaps in your translation, you need to download the new template file, merge it into your translated .po file, and the translate the newly introduced strings.
These are the steps to perform:
- Make a backup of your
mAirList.pofile. - Download the current
mAirList.pottemplate file. - Open your
mAirList.pofile with poEdit. - Select "Catalog -> Update from POT file" from the menu.
- Choose the
mAirList.potfile just downloaded. - A dialog box will appear, displaying both the new and the obsolete strings.
- Click OK, and the changes will be merged
poEdit will move the new strings to the top of the list for easy translation. New strings for which no translation has been found are marked blue. For some strings, poEdit will try to "guess" a suitable translation among the existing strings - those translations are called "fuzzy" and will be marked yellow in the list. Unfortunately, this feature does not work very well; in most cases, the "guessed" translation is incorrect. You should revise any of the yellow lines. If you find a fuzzy translation which was guessed correctly, select "Edit -> Translation is fuzzy" from the menu or press Alt+U in order to remove the "fuzzy" flag.
Make your Translation Available to mAirList Users
All available translations are managed and stored in a Subversion (SVN) repository. Subversion is a version control system, allowing users to share and edit files concurrently, while keeping track of all changes, a version history etc.
The SVN repository contains one mAirList.po file per language and release (stable and testing). The mAirList Language Packs available for download are automatically generated from the files from the SVN repository regularly.
The easiest way to distribute your translation would be to send the finished .po file to Torben by e-mail. He will then put the file into the SVN repository. However, if you want to update your translations regularly (which you are encouraged to do), the most convenient way is to access the SVN repository by yourself. This is described below.
Download and Install TortoiseSVN
There are numerous SVN clients available. The most convenient one for the Windows operating system is certainly TortoiseSVN, which integrates seamlessly into Windows Explorer.
After installation, you will most likely need to reboot. Once your system is back up, you will find some new TortoiseSVN items in the context menu of Windows Explorer.
Get an Account for SVN
In order to edit files in the SVN repository, you need to obtain a username and password from Torben. Send him a mail, and specify which language you would want to maintain. He will prepare the folders for you and send you a password.
Note: You can read (check out) the files from the repository without login, but you will need the password once you want to commit your changes to the repository.
Check Out the Localization Files
When you access the repository for the first time, you need to "check out" the project first. This means that a local copy of all files is created on your PC. Follow these steps:
- Open Explorer and create a new folder where you want the files to be checked out, for example
c:\translation. - Right-click the new folder and select "SVN Checkout ...".
- Enter the following repository URL: https://secure.mairlist.com/svn/l10n/trunk
- Check that the "Checkout directory" value points to your newly created folder.
- Leave any other options untouched. In particular, make sure that "HEAD revision" is checked.
- Click OK.
- A dialog box will appear, showing details of the SSL certificate used. Click "Accept permanently".
- TortoiseSVN will now check out the files.
You will now find one folder per released, each folder containing one folder per language. Each language folder contains a mAirList.po file. For example,
v2.1\nl\mAirList.po
is the translation file for Dutch for the v2.1 release.
You may find other files in the repository, for example the makeLangPack.sh script which creates the language packs from the repository files. You can safely ignore any other file but "your" mAirList.po file.
You will notice that all files have a small green check added to their icon. This means that you haven't made any local changes to the files.
Check In Your Changes
Once you have updated your translation, you can "check in" your new mAirList.po file:
- Navigate to the folder corresponding to the mAirList release and language, for example
v2.1\nl. - Replace the mAirList.po file found in there by your new version. Always use the text catalog version
mAirList.po, NOT the binary catalogmAirList.mo! You will notice that the green check turns into a red exclamation mark, signalling that the file has been modified. - Right click your top-most folder (in our example,
c:\translation) and select "SVN Update". This will merge any changes made by other users in the mean time, and ensure that your check in operation will not fail due to any conflicts. - Right click the folder again, and select "SVN Commit..."
- A dialog box will appear where you see the files which are going to be committed (most likely, only the
mAirList.pofile just replaced). You are also asked to enter a log message. Always enter some useful information here, for example "translated new messages from v2.1.18". The log messages will later appear in theversion.txtfile in the language pack. - Click OK.
- TortoiseSVN will now ask for your username and password.
