Translating VirtualBox (I18N)

This document describes how users without a strong technical background in software engineering can contribute translations to other languages. The process is very straightforward and based on the easy to use ​Qt Linguist tool which is a part of the Qt Toolkit version 3.

Translation is possible for all languages, including languages with non-latin alphabets. The process requires you to perform an initial translation which you then have to keep up to date as VirtualBox evolves. The original language is English which -- together with German -- is handled by InnoTek. The Qt Linguist tool will also assist you in finding where your translation has to be updated for a new release of VirtualBox.

Language file naming and location

All language files in VirtualBox are named according to the following rule:

<component>_<lang>

where <component> is the name of the component (currently, VirtualBox is the only possible value which stands for the VirtualBox GUI front-end) and <lang> is the language identifier.

The language identifier has the form of <language>[_<TERRITORY>], where <language> is a two-letter language code as defined by ​ISO 639, and optional <TERRITORY> is a two-letter territory (country) code as defined by ​ISO 3166. See the examples of language file names at the end of this section.

Binary language files used at runtime are located in the nls subdirectory of the directory that contains the component's executable, and have the .qm extension. Source translation files are located in the nls subdirectory of the component's source tree and have the .ts extension.

At runtime, VirtualBox selects a binary language file for the given language identifier xx_YY in the following order (the first match wins):

1. <component>_xx_YY.qm
2. <component>_xx.qm
3. [built-in English translation]

The language identifier is initially chosen according to the current user's locale setting.

Here are some examples of language file names:

• VirtualBox_de.qm (Deutsch language, all territories)
• VirtualBox_ru.qm (Russian language, all territories)
• VirtualBox_zh_TW.qm (Chinese language, Taiwan)

Prerequisites

The only prerequisite at the moment to create a new or update an existing translation is the ​Qt Linguist tool. In order to get Qt Linguist, ​download and install the latest version of Qt Toolkit 3.x for your platform. Please note that we will not accept translation files processed by Qt Linguist version 4 (part of Qt Toolkit 4.x) because the format of language files may differ there.

Note that the VirtualBox source code is not necessary to perform a translation or to test it. See below for detailed instructions.

Preparing a translation to a new language

This section describes how to start a translation of VirtualBox to a new language.

1. Define a language identifier for your language according to the rule described above. If translations to your language vary depending on the country, use the _<TERRITORY> suffix, otherwise omit it (i.e. no need to apply the suffix if it represents the only possible country). Let's say that your language code is my_MY for the purpose of this description.
2. Check that your language is not yet supported by visiting this ​directory in the source tree.
3. Add a comment to ticket:234 that you are going to maintain the translation to your language to inform other people that may also want to participate. Before adding such a comment, check that nobody else has already started the translation to the same language.
4. Download the translation template ​VirtualBox_xx_YY.ts.
5. Rename the template to VirtualBox_my_MY.ts.
6. Start Qt Linguist, open the VirtualBox_my_MY.ts file and translate it.
7. Make sure all the fields in a special context named @@@ are properly translated (see below).
8. Check your translation at runtime by referring to the Testing the translation section below.

Special context @@@

A special context named @@@ contains translatable items necessary to identify the given translation file, so you must ensure they are properly translated. There are five items in this context:

1. Native language name (the original value is English). Translate it to a common, human-readable name of the language of your translation, as written in the language itself. For example, for Russian, it will be Русский. Please note that the <language> part in the name of the .ts file must match the language specified here.
2. Native language country name (the original value is --). If the language of your translation is the same regardless of the territory (country) of speaking, then translate it to an empty string. If you are translating to a particular variant of your language, translate this item to a common, human-readable name of the territory (country) where this variant is used, as written in the language itself. Please note that the <TERRITORY> part in the name of the .ts file must match the language specified here.
3. Language name, in English (the original value is English). The same as 1, but a common English spelling of the language name.
4. Language country name, in English (the original value is --). The same as 2, but a common English spelling of the territory (country).
5. Comma-separated list of translators (the original value is InnoTek). This item used is to specify a list of authors who worked on this translation. Please use the Latin alphabet here, to make it readable by everyone.

Every item in this special context has a self-descriptive comment field, so it will not be difficult to locate them in your translation file even if the order there differs from the order they are listed here.

Please read carefully the Translation hints section below to learn more about the translation process.

Updating the translation of an existing language

This section describes how to apply corrections to an existing language file or how to update it with translations for new strings added by the new release of the product.

1. Define a language identifier for your language according to the rule described above. If translations to your language vary depending on the country, use the _<TERRITORY> suffix, otherwise omit it (i.e. no need to apply the suffix if it represents the only possible country). Let's say that your language code is my_MY for the purpose of this description.
2. Look through comments to ticket:234 to find out who is currently maintaining the translation to your language. Contact these people in order to coordinate your work and avoid conflicts
3. Goto this ​directory and download the VirtualBox_my_MY.ts file.
4. Start Qt Linguist, open the VirtualBox_my_MY.ts file and translate it.
5. Check your translation at runtime by referring to the Testing the translation section below.

Please read carefully the Translation hints section below to learn more about the translation process.

Existing translation source files are periodically synchronized with the source code by the GUI maintainer at InnoTek, either a few weeks before a new product release, or after a big number of language-related changes in the UI. This synchronization is performed to add new (untranslated) strings used in the UI to translation files, which then need to be translated by contributors. See ticket:234 for more information about the synchronization process.

Translation hints

This section contains important notes about translating the VirtualBox product.

1. Read the ​Qt Linguist manual to get general information about translating Qt applications. Pay special attention to understanding the status of translatable items (unfinished, obsolete).
2. Preserve spaces around (and between) words if they are used for justification purposes. Examples of such items are category names in the global and VM settings dialogs where leading and trailing space characters serve as horizontal item margins. Also, a leading space in the translatable item is often used as a separator from the preceding word that will appear after string concatenation, and therefore needs to be preserved.
3. Translate only human-readable words and sentences. Leave HTML markup and other sorts of special characters untouched -- otherwise you may completely break the text appearance in the UI.

Testing the translation

Use these steps to test your translation:

1. Select File -> Release... from the main menu of Qt Linguist.
2. Specify <path_to_VirtualBox_exe>/nls/VirtualBox_my_MY.qm as the target path and file name and press Ok. This will generate a binary language file and save it to the proper directory.
3. Setup the locale corresponding to the my_MY language identifier and start VirtualBox.exe. The language file should be loaded automatically if you did everything right.
4. Navigate through all parts of the user interface and check the quality and meaningfulness of the translation.

Please note that you cannot test translations with VirtualBox version 1.3.8 and earlier because the translation suppport was not enabled in those releases. Presently, the only option to test is to use the SVN build. All future releases of VirtualBox will have the translation support enabled.

Submitting the translation

When you think your translation looks good and ready to be shared with others, you may submit the translation source file you created (VirtualBox_my_MY.ts, according to the examples above) by packing it to a .zip archive and attaching to ticket:234.

The same thing should be done after you have updated an existing translation, but please be careful with the name of the file you are attaching and make sure you will not replace somebody's else attachment with the same name (you may and should replace a previous attachment of the same name only if it was also attached by you and only if it contains an outdated version of the same translation file you are attaching now).