= 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 [https://doc.qt.io/qt-5/qtlinguist-index.html Qt Linguist] tool which is a part of the Qt toolkit for C++ version 5.

If you are just wanting to point out a mistake or any other issue with one of the existing translations, you should add a comment onto the end of ticket:4503.  Translators are encouraged to subscribe to that ticket by adding a short comment onto it themselves so that they will be notified about updates to the ticket.

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 and Russian -- is handled by the !VirtualBox team. The Qt Linguist tool will also assist you in finding where your translation has to be updated for a new release of !VirtualBox.

We have tried to keep the information about how to do translation as understandable as possible, but if something is still not quite clear to you feel free to ask on the [https://www.virtualbox.org/wiki/Mailing_lists developers' mailing list].

== 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 and {{{<lang>}}} is the language identifier. Possible values for the {{{<component>}}} part are:
||{{{VirtualBox}}} ||''!VirtualBox GUI'' front-end||
||{{{qt}}}         ||Qt library itself (built-in dialogs and other resources like key names)||

The language identifier has the form of {{{<language>[_<TERRITORY>]}}}, where {{{<language>}}} is a two-letter language code as defined by [http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes ISO 639], and optional {{{<TERRITORY>}}} 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. {{{<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:

 - {{{qt_de.qm}}} (Qt translation, Deutsch language, all territories)
 - {{{VirtualBox_ru.qm}}} (!VirtualBox GUI translation, Russian language, all territories)
 - {{{VirtualBox_zh_TW.qm}}} (!VirtualBox GUI translation, Chinese language, Taiwan)

== Prerequisites ==

To create a new or update an existing translation, you will need the [https://doc.qt.io/qt-5/qtlinguist-index.html Qt Linguist tool], to edit {{{.ts}}} files. In order to get Qt Linguist, download the latest 5.x.x version of the Open Source Edition of the Qt toolkit for C++ for your platform from the [http://www.qt.io/download-open-source/ Qt web site]. Alternatively, you can try to download the toolkit sources and compile them yourself to get a Qt Linguist application. Please note that we will not accept translation files processed by Qt Linguist version 3 (part of Qt Toolkit 3.x.x) because the format of language files is incompatible with the newer versions of Qt.

Note that the full !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 in the list on ticket:17708 (the translation ticket).

 3. Add a comment to ticket:17708 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 files {{{VirtualBox_xx_YY.ts}}} and {{{qt_xx_YY.ts}}} from the web page [https://www.virtualbox.org/download/testcase/nls/] to your computer (please be aware that the address of that page may change occasionally and check back to this instruction page if you are in doubt) and rename the files for your language using the language identifiers described above.  For example, the name {{{VirtualBox_yi.ts}}} would be correct for Yiddish, and {{{qt_sw_TZ.ts}}} for Tanzanian Swahili.

 5. Start Qt Linguist, open and translate new files you got in step 5.

 6. Make sure all the fields in a special context named {{{@@@}}} in the file {{{VirtualBox_my_MY.ts}}} are properly translated (see below).

 7. Make sure you followed the [#Translationhints Translation hints] while translating.

 8. Check your translation at runtime by referring to the [#Testingthetranslation Testing the translation] section below.

 9. Submit your translation as described in the [#Submittingthetranslation Submitting the translation] section.

=== Special context @@@ ===

A special context named {{{@@@}}} contains translatable items necessary to identify the given translation file, so you must ensure they are properly translated. This context is currently present only in the {{{VirtualBox_my_MY.ts}}} file. 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 {{{Oracle Corporation}}}). 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.

=== Picking up recent changes to the translation files ===

Existing {{{.ts}}} files are periodically synchronized with the source code by the GUI maintainer at Oracle, either a few weeks before a new product release, or after a big number of language-related changes in the user interface (UI). This synchronization is performed to add new (untranslated) strings used in the UI to {{{.ts}}} files which then need to be translated by contributors. Updates will be announced on ticket:17708.  To translate the newly added text, you should replace the copies of the translation files on your computer with the new ones on the web page, which will contain any work which you have submitted previously.

== Updating a translation done by someone else ==

If you want to continue a translation done by someone else, please perform the following steps:

 1. Determine the language identifier for your language as described above. If translations to your language vary depending on the country or region, 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:17708 to find out who is currently maintaining the translation to your language. Contact these people in order to coordinate your work and avoid conflicts by adding a comment to ticket:17708 (this is less important if you will be working on a new regional variant of the language, but consider that you may still gain a lot from working together).

 3. Copy the existing translation files from the web page mentioned in the [#Preparingatranslationtoanewlanguage Preparing a translation to a new language] section.  If you are working on a new regional variant of the language rename the files appropriately.

 4. Follow other steps starting from step 6 in the [#Preparingatranslationtoanewlanguage Preparing a translation to a new language] section.

== Translation hints ==

This section contains important notes about translating the !VirtualBox product.

 1. '''Read''' the [https://doc.qt.io/qt-5/qtlinguist-index.html Qt Linguist manual] to get general information about translating Qt applications. Pay special attention to understanding the status of translatable items (unfinished, obsolete).

 2. Properly translate '''Plural Forms'''. !VirtualBox may contain sentences which include {{{%n}}} markers. This marker is used when numbers could be included either in a singular or plural variant. The Qt translation mechanism allows you to translate this one sentence to different variants to let the result look more natural. For more information on this topic see [https://doc.qt.io/archives/qq/qq19-plurals.html Plural Form(s) in Translation(s)].

 3. '''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.

 4. 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.

 5. '''Don't translate''' items starting with the '''{{{#}}} (hash)''' sign in contexts {{{VBoxGlobalSettingsDlg}}} and {{{VBoxVMSettingsDlg}}}, such as {{{#general}}}, {{{#input}}} and so on. They are responsible for the settings category hyper-link feature on the VM Details page and translating them will break this feature.

 6. When Qt Linguist shows the source text of the translatable item, it uses special text fragments inside it to mark unprintable characters, for example: '''{{{(new-line)}}}''' for new-line marks or '''{{{(sp)}}}''' for ambiguous space characters. However, if you copy the source text to the translation field (to use it as a template for translation), Qt Linguist will not replace these special fragments back with real control/formatting characters -- they will remain {{{(new line}}}} and {{{(sp)}}} in the translation and will appear like that in the GUI as well. Therefore, you should be careful and always replace them with the corresponding formatting characters (new-line or space) manually.

 7. In general, it's '''not recommended''' to translate '''{{{Ctrl+<latin_letter>}}}''' shortcuts (for example, Ctrl+S used to open the VM Settings Dialog) because they are intended to be language neutral and should have the same action regardless of the selected UI language. Translate them only if there is a very special reason to do so in your language; otherwise simply leave the original. Note that the action name starting with a different letter or having a different underscored ({{{Alt+<any_letter>}}}) accelerator in your language is not a valid reason to translate the corresponding {{{Ctrl+<latin_letter>}}} shortcut.

== Testing the translation ==

Use these steps to test your translation:

 1. Select '''File -> Release As...''' from the main menu of Qt Linguist.

 2. Specify {{{<path_to_VirtualBox_exe>/nls4/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. Repeat the previous step for all other components ({{{qt_my_MY.qm}}}).

 4. Setup the locale corresponding to the {{{my_MY}}} language identifier and start {{{VirtualBox.exe}}}. The language files should be loaded automatically if you did everything right.

 5. 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 files you created ({{{VirtualBox_my_MY.ts}}} and {{{qt_my_MY.ts}}}, according to the examples above) by packing it to a .zip archive named {{{VirtualBox_my_MY.zip}}} and attaching to ticket:17708.

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. Note though that you may and normally should replace a previous attachment of the same name if it was also attached by you and if it contains an outdated version of the same translation file you are attaching now.

'''PLEASE REMEMBER''' that before your translation can be included into the !VirtualBox code base and distribution archives, '''you must allow Oracle Corporation to make use of your contributions'''. The [wiki:Contributor_information] section describes how to do it. Basically, you have two options: either to fill out the [wiki:ICA Oracle Contributor's Agreement] (ICA) and send it to Oracle Corporation or to make the following statement directly in the ticket:17708 comment where you attach your translation source file:

{{{
  The <MyLanguage> (<my_MY>) translation attached here by <my_full_name>
  is published under the terms of the [wiki:"MIT license"].
}}}

assuming that {{{<MyLanguage>}}} is the language name, {{{<my_MY>}}} is the language identifier and {{{<my_full_name>}}} is your '''full name''' that has exactly the same spelling you used in the .ts file itself (in the list of translators in the special context {{{@@@}}}). It's enough to do it only once for a given language. If you translate !VirtualBox to more than one language than a separate statement for every language is necessary.