====== How to Translate mAirList Into Other Languages ======

The graphical user interface of mAirList is in English, but can easily be translated into other languages using the techniques described in this document.

A couple of translation files (currently German and French) are included by default with each installation of mAirList. In the following you will learn how to create a translation file for another language.

===== How translation works =====

mAirList uses a Delphi port of the [[https://www.gnu.org/software/gettext/|GNU gettext]] translation toolkit. When you start mAirList, it will determine the desired language is set up in the config (or use the default language of your Windows system), and then check if there is a translation file present for that language in the program folder. If this is the case, it will use the translations from that file instead of the English original every time a text is displayed somewhere.

  * ''default.pot'' - This is the so-called **translation template**. It contains the list of original English strings, but no translations. The template is supplied with each mAirList installation (since v4.4), and can be found in the mAirList program folder.
  * ''mAirList.po'' - This is the actual **translation file** that contains both the English strings and the translated strings. It must be located in a folder whose name matches the ISO code of the target language, see instructions below. The ''.po'' file is actually a text file, so you can open it in a text editor to explorer its contents. For editing it is recommended to use a special software though, e.g. poEdit, see below.
  * ''mAirList.mo'' - This is the **compiled binary version** of the ''.po'' file. It it generated automatically every time you save the ''.po'' file in poEdit. The application uses this binary ''.mo'' file because it allows faster access than the text file.

====== Preparing the translation ======

===== Locate translation template =====

Before we can start the translation, we first need to locate the translation template ''default.pot''. It is included with every installtion of mAirList. Open Windows Explorer and navigate to the mAirList program folder, then go to the ''locale'' subfolder, and you should see it:

{{ :tutorials:other:pasted:20141009-114616.png?400 }}

===== Create language folder =====

Inside the ''locale'' folder, you see a couple of subfolders, one for each translation that is already included by default: ''de'' (German), ''en_GB'' (British English), ''fr'' (French).

To start a new translation, you must first create a folder that matches the two-letter ISO 639-1 code of the language, e.g. ''da'' for Danish. For a list of all language codes see here: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes

If you're creating a translation for a special variant of a language for a particular country, you can also add the two-digit country code, separated by an underscore sign, to the language code, e.g. ''en_AR'' for Argentinian Spanish.

**Important**: Inside the "language code" folder you created, you must create another folder named ''LC_MESSAGES''. This is where the translation file goes in the next step.

In the end it should look like this:

{{ :tutorials:other:pasted:20141009-115429.png?400 }}

===== Copy and rename translation template =====

Finally we have to copy the translation template ''default.pot'' to our newly created ''LC_MESSAGES'' folder, and rename it to ''mAirList.po'':

{{ :tutorials:other:pasted:20141009-115646.png?400 }}

Now we're almost ready to start the translation.

===== Download and install poEdit =====

While ''.po'' files are plain text files and could be edited with any text editor, we recommend that you use a dedicated po file editor. Our favorite is //poEdit//, which is available for download here (the free version is fine, you don't have to pay for the Pro version if you don't want to): http://poedit.net/

When you're editing the ''mAirList.po'' file inside the mAirList program folder, it is necessary to run poEdit as Administrator, or you won't be able to save your work. To do so, adjust the security settings of ''poEdit.exe'' so that it always runs as Administrator:

{{ :tutorials:other:pasted:20141009-121529.png?300 }}

(Sorry, no English screenshot available.)

====== Do the actual work ======

Having installed poEdit, you can double-click the ''mAirList.po'' file and poEdit will open it.

===== Set project name =====

The first time open the ''.po'' file, poEdit will display a message saying //Translation's project name isn't set//, and show a button //Set name// which displays the following dialog: 

{{ :tutorials:other:pasted:20141009-120154.png }}

Enter //mAirList// as the project name, your name and e-mail as the team name/e-mail (it will give you the credits for the translation in the //About// dialog later), and both charsets to //UTF-8//. Then click //OK// to save.

===== Enter translations =====

Now you're ready to enter the translation strings. In the poEdit main window, there is a table that displays the English strings on the left, and the translations on the right (initially empty):

{{ :tutorials:other:pasted:20141009-120935.png?400 }}

Click a line, and enter the translation into the text field at the bottom. You can now also use the arrow keys to move to the next string. Untranslated strings are in bold and at the top of the list, finished translations are in normal text and move down to the bottom when you save the file.


<WRAP tip>
**Remember to click //Save// once in a while to save your work!**

However, mAirList must not be running at the time you save the translation in poEdit, because otherwise the ''.mo'' file cannot be written. If this is an issue for you, you can copy the ''mAirList.po'' and ''mAirList.mo'' files to another location, edit them from there, and copy them back to the ''LC_MESSAGES'' folder when you're done.
</WRAP>

When you save the ''.po'' file, you will notice that poEdit also created the ''mAirList.mo'' file in the same folder:

{{ :tutorials:other:pasted:20141009-122539.png?400 }}

So everything is in place now, and if the language is the same as your Windows language, mAirList should automatically detect and use the file. Otherwise run mAirList Configuration, go to //GUI -> General//, and set the language code accordingly:

{{ :tutorials:other:pasted:20141009-123053.png?400 }}
===== Important hints =====

There are a couple of things that you have to take special care of when doing the translation.

==== Variables ====

You will notice that some of the English texts contain special placeholders starting with a ''%'' sign, like this:

  Importing file %d of %d (%d errors). Estimated time remaining: %s
  
These are variables which will be filled with the actual text or data by mAirList. In particular, you will come accross the following placeholders:

  * ''%d'' - number
  * ''%<format>f'' - number with decimal point
  * ''%s'' - string/text

**It is important that the translated text uses the exact same variables, in the exact same order!** Otherwise software will crash later. For example. the above text would be translated to German like this:

  Importiere Datei %d von %d (%d Fehler). Verbleibende Zeit: %s
  
Note that the variables ''%d'', ''%d'', ''%d'', ''%s'' appear in the same order. Again, this is very important!
==== Quotation marks ====

Inside the ''.po'' file (remember that it's a text file) double quotes ("") are used to delimit the strings. Now when a double quote appears in one of the English strings, it will have a backslash (\) sign before it, to "escape" it:

  \"A\" and \"B\" Buttons (left to right)
  
Again it is very important that you also use a backslash sign before any double quote in the translated text:  
  
  \"A\"- und \"B\"-Taster (links nach rechts) 
====== New program versions ======

When you install a new version of mAirList, it may happen that there are new strings that must be translated. The installer will put a new ''default.pot'' file into the program folder. Your task is to merge that new template into your exisiting translation.

In order to do so, open your ''mAirList.po'' file in poEdit, then click //Catalogue -> Update from POT file// from the menu. Select the new ''default.pot'' file and click //Open//.

poEdit will read the new template and add any new strings to your translation (and remove obsolete ones).

Sometimes poEdit will also make a **suggestion** based on your existing translations; these **fuzzy** translations are marked with a green star in the translation table. You can accept the suggestion by unchecking //Edit -> Translation is fuzzy// in the menu, or pressing ''Ctrl+U''. Or just enter a new one.

====== Make your translation available to the public ======

When you have finished a translation for a language that is not yet supported out of the box by mAirList, we will be happy to receive your translation files and included in the official distribution from now on.

For details please contact us at [[mailto:info@mairlist.com|info@mairlist.com]].