Localization

This article describes localization (translation) of applications into different languages.

Please carefully study the material in this article before attempting to update or create a translation!

Translation files

Translations are stored in PO files (as produced by gettext) which are distributed together with the application, inside Languages folder:

• Languages\Application.po – Template file.
• Languages\Application.ru.po – Russian (RU) translation file.
• Languages\Application.es.po – Spanish (ES) translation file.
• Languages\Application.fr.po – French (FR) translation file.
• ...

The template file (Application.po / Application.pot) is used as the basis for creating translations for new languages, not yet available in the application.

Translation files (Application.XX.po) contain translated text. A two-letter language code in the file extension identifies a particular language.

Create new translations

To create a translation file for a new language:

1. Create a copy of Application.po (template file)
2. Rename it to Application.XX.po (translation file), where XX is a two-letter language code.
3. Translate entries to the new langauge using instructions below.
4. Populate PO file headers, copy from any other translation file and modify appropriately.
5. Save new file using UTF-8 encoding, without byte order mark (BOM).

Example of relevant entries in PO file headers for a new translation file:

msgid ""
msgstr ""
...
"Language: ru\n"
"X-Country: ru\n"
"X-Country-Name: Russia\n"
"X-Language-Name: Russian\n"
"X-Language-Name-Native: Русский\n"
"X-Translators: Your Name <your.email@example.com>\n"
...

• Language codes are defined in ISO 639-1
• Country codes are defined in ISO 3166-1 alpha-2.
• In conflicting and ambiguous situations:
  1. Name the translation file using Application.XX_YY.po format, where XX is a language code and YY is a country code.
  2. Set X-Language-Name header to highlight the difference between translations.

  For example: "en_US" code for English (United States), "en_GB" code for English (United Kingdom).

Editing translation file

The process involves translation of individual textual messages to create a mapping from original text to a different language.

Translation files (*.po) should be edited with specially designed translation tools, such as:

• Poedit – for Windows, Linux and Mac.

Translation files could also be edited manually using a text editor, but this is highly discouraged as tiny mistakes can result in corruption of the entire file.

Guidelines for translators

Guidelines for translators:

• Use the most up-to-date language files from the latest development version (Beta versions).
• Try not the exceed the length of the translated text, comparing to the length of the original text.

  Some components may not fit longer text, so it is better to make it shorter rather than longer.

• Beware of the special formatting, symbols and placeholders, e.g. "\n", "%s", "%d".

  Make sure to maintain such formatting, translate only actual words.

• If you don't have a good translation for some text, just leave those blank.

  Other people may be able to fill in the blanks later.

• Try to use formal but easy to understand language.

  Avoid the use of slang, which may not be understood by some readers.

Attribution to translators:

• Add your name to "X-Translators:" field in PO file headers.
• Please keep names of other translators (separate multiple names with a comma).

Auxiliary translation files

In addition to the main translation file, you may find auxiliary translation files in subfolders. These correspond to 3rd party components, for example, "LCLStrConsts" subfolder contains messages that appear in Lazarus Component Library (LCL). We do not handle the updates to auxiliary translation files directly, because we source that from the original vendor. If you wish, you can submit your improvements directly to the vendor.

Updates for "LCLStrConsts" translations should submitted to the Lazarus IDE project, using the following steps:

1. The translation should be based on the latest development files.
2. The translation file can be submitted via the issue tracker or as a merge request (preferred).

Loading specific language

All available language files are automatically added to the "Languages" menu on startup. Select a desired language and restart the application.

When selected language is set to "Autodetect" mode:

• Application automatically tries to recognize system language and loads appropriate translation file.
• It is also possible to load a specific language file, by either:
  1. Adding "--lang XX" command line parameters to the application, where XX is a two-letter language code.
  2. Setting "LANG" environmental variable to a two-letter language code.

Publishing your translation

Please send new and updated translation files via email, as attachments.

The email address can be found in the About dialog of every application.