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.

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.

Some languages are supported natively by mAirList (technically speaking, the respective .mo files are embedded into mAirList.exe). As of mAirList 3.1, the natively supported languages are:

German (de) - maintained by Torben Weibert
British English (en_GB) - maintained by Cad Delworth

You can create and 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\

There are more details below in Install Your .mo File.

To create a .mo file, download the template (default.pot) file, rename the file to mAirList.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.

As of July 2010, translation templates are currently available on request only. Please send an e-mail to info@mairlist.com and mention the language you are going to translate mAirList into.

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 copy template default.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. 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: e.g. "mAirList 3.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

Skip this step if you are the official maintainer of a particular translation file and using SVN to upload your file (see below) - your translation file will be merged with the current strings automatically every time there is a change.

With each new version of mAirList, there might be new messages introduced in that version that must be translated. In order to fill the gaps in your translation, you need to obtain an updated copy of the default.pot 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.po file.
Obtain the current default.pot template file.
Open your mAirList.po file with poEdit.
Select "Catalog -> Update from POT file" from the menu.
Choose the default.pot file 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.

Becoming the Official Maintainer of a Particular Language

The translation process described above is ok if you only want to translate a particular version of mAirList, and if you want to keep the translation file to yourself or within your organization. However, it might be favorable to make your translation public so that other people from your country can benefit from it. In this case, please consider to become the official maintainer of that language file.

Here's what you get when you are the official maintainer of a particular language:

You receive an account to our Subversion (SVN) system where the translation files for all languages are stored.
Your translation file will be update automatically whenever there is a change to the translation template. There's no need for a manual merge anymore, all you need to do is update the SVN and add the missing translations.
Your language file will be embedded into the mAirList.exe executable and thus included in every official download of mAirList.
Your name will be displayed in the About dialog on the Localization tab whenever someone is using your language file.

On the other hand, we request that you commit yourself to the project and translation in the long term and are willing to process any updates as quick as possible, as a courtesy to the people relying on your translation file.

If you are interested in becoming the official maintainer for a particular language, please send an e-mail to info@mairlist.com.

In the following, we will give an overview on how to work with SVN as an official maintainer of a language file.

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.

TortoiseSVN download page

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

When you are an official maintainer, you will receive a username and password for the SVN system, as well as the exact URL to use when connecting to our SVN repository.

Check Out the Localization Files

When you access the repository for the first time, you need to "check out" the project into a so-called first. This means that a local copy -- the so-called working 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 repository URL received by us.
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 release (3.0, 3.1, ...), each folder containing one folder per language. Each language folder contains a LC_MESSAGES</coder> folder with an <code>mAirList.po file inside. For example,

 v3.1\nl\LC_MESSAGES\mAirList.po

is the translation file for Dutch for the v3.1 release.

You may find other files in the repository, for example the scripts to update and merge all translation 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.

Update Your Working Copy

Whenever there are any strings added or removed from the translation template, the scripts on our server will prepare (merge) your translation file automatically to reflect these changes. It is therefore recommended to update your working copy before making any changes to your translation file:

Open Exlorer and navigate to the top level folder of your working copy.
Right click anywhere into the blank space.
From the context menu, select "SVN Update".

You can repeat these steps as often as you wish to ensure that you always have the latest versions of all files in your working copy.

Update Your Translation File

At this point, you can start to edit your mAirList.po file with poEdit as described above. In particular, take care of any untranslated changes that might have been merged into your file from the latest translation template.

At this point, the icon of your mAirList.po file should have a small red X next to it to indicate that you made changes to the file that haven't been propagated to SVN yet.

Check In Your Changes

Once you have updated your translation, you can "check in" your new mAirList.po file:

Right click the mAirList.po file, 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.po file just replaced). You are also asked to enter a log message. Always enter some useful information here, for example "translated new messages from v3.1.0". The log messages will later appear in the version.txt file in the language pack.
Click OK.
TortoiseSVN will now ask for your username and password.