= 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 [http://doc.trolltech.com/3.3/linguist-manual-3.html Qt Linguist] tool which is a part of the Qt Toolkit version 3. Translation is possible for all language, 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: {{{ _ }}} where {{{}}} is the name of the component (currently, {{{VirtualBox}}} is the only possible value which stands for the the ''!VirtualBox GUI'' front-end) and {{{}}} is the language identifier. The language identifier has the form of {{{[_]}}}, where {{{}}} is a two-letter language code as defined by [http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes ISO 639], and optional {{{}}} is a two-letter territory (country) code as defined by [http://en.wikipedia.org/wiki/ISO_3166-1 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. {{{_xx_YY.qm}}} 2. {{{_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 [http://doc.trolltech.com/3.3/linguist-manual-3.html Qt Linguist] tool. In order to get Qt Linguist, [ftp://ftp.trolltech.com/qt/source/ 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 {{{_}}} 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 [http://virtualbox.org/svn/vbox/trunk/src/VBox/Frontends/VirtualBox/nls directory] in the source tree. 3. Download the translation template [http://virtualbox.org/svn/vbox/trunk/src/VBox/Frontends/VirtualBox/nls/VirtualBox_xx_YY.ts VirtualBox_xx_YY.ts]. 4. Rename the template to {{{VirtualBox_my_MY.ts}}}. 5. Start Qt Linguist, open the {{{VirtualBox_my_MY.ts}}} file and translate it. 6. If you want to check your translation at runtime, refer to the section '''Testing the translation''' below. Please read the [http://doc.trolltech.com/3.3/linguist-manual-3.html Qt Linguist manual] carefully 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 {{{_}}} 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. Goto this [http://virtualbox.org/svn/vbox/trunk/src/VBox/Frontends/VirtualBox/nls directory] and download the {{{VirtualBox_my_MY.ts}}} file. 3. Start Qt Linguist, open the {{{VirtualBox_my_MY.ts}}} file and translate it. 4. If you want to check your translation at runtime, refer to the section '''Testing the translation''' below. Please read the [http://doc.trolltech.com/3.3/linguist-manual-3.html Qt Linguist manual] carefully to learn more about the translation process, in particular, about the status of the translatable item (unfinished, obsolete). 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 updated by contributors. See ticket:234 for more information about the synchronization process. == Testing the translation == Use these steps to test your translation: 1. Select '''File -> Release...''' from the main menu of Qt Linguist. 2. Specify {{{/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. == 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 attaching it to ticket:234.