Changes between Version 24 and Version 25 of Translating

Timestamp:

Aug 27, 2008 9:38:26 PM (16 years ago)

Author:

Dmitry A. Kuminov

Comment:

Added the subversion information.

Translating

@@ -35 +35 @@
 == Prerequisites ==
 
-The only prerequisite at the moment to create a new or update an existing translation is the [http://doc.trolltech.com/4.3/linguist-manual.html Qt Linguist] tool. In order to get Qt Linguist, download the latest 4.x.x version of the Open Source Edition of the Qt toolkit for C++ for your platform from the [http://trolltech.com/downloads/opensource Trolltech site]. Alternatively, you can try to download the toolkit sources from the [ftp://ftp.trolltech.com/qt/source/ Trolltech ftp site] 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 Qt4.
+There are two prerequisities to create a new or update an existing translation:
+
+ 1. [http://subversion.tigris.org/ subversion tool], to get and update {{{.ts}}} source files from the SVN repository that contains the VirtualBox OSE source code. In order to install subversion, download the latest version from the [http://subversion.tigris.org/getting.html Tigris web site].
+
+ 2. [http://doc.trolltech.com/4.3/linguist-manual.html Qt Linguist tool], to edit {{{.ts}}} files. In order to get Qt Linguist, download the latest 4.x.x version of the Open Source Edition of the Qt toolkit for C++ for your platform from the [http://trolltech.com/downloads/opensource Trolltech web site]. Alternatively, you can try to download the toolkit sources from the [ftp://ftp.trolltech.com/qt/source/ Trolltech ftp site] 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 Qt4.
+
 
 Note that the full !VirtualBox source code is '''not''' necessary to perform a translation or to test it. See below for detailed instructions.
@@ -44 +49 @@
 
  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 the [http://virtualbox.org/svn/vbox/trunk/src/VBox/Frontends/VirtualBox4/nls] directory in the source tree.
+
  3. Add a comment to ticket:2018 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 translation templates for each component: [http://virtualbox.org/svn/vbox/trunk/src/VBox/Frontends/VirtualBox4/nls/VirtualBox_xx_YY.ts VirtualBox_xx_YY.ts] and [http://virtualbox.org/svn/vbox/trunk/src/VBox/Frontends/VirtualBox4/nls/qt_xx_YY.ts qt_xx_YY.ts].
- 5. Rename the templates to {{{VirtualBox_my_MY.ts}}} and {{{qt_my_MY.ts}}}, respectively.
- 6. Start Qt Linguist, open and translate renamed files you got in step 5.
+
+ 4. Go to some directory on your local hard drive and download the NLS subdirectories containing {{{.ts}}} files from the VirtualBox source tree by typing the following command in the command line window (terminal) of your host OS (assumes that subversion has been properly installed so that the svn executable can be found by the host OS):
+{{{
+svn co http://virtualbox.org/svn/vbox/trunk/src/VBox/Frontends/VirtualBox4/nls VirtualBox_nls
+}}}
+    This will create the {{{VirtualBox_nls/}}} subdirectory on your local drive containing all {{{.ts}}} files for the !VirutalBox GUI component and for Qt4 itself.
+
+ 5. Go to {{{VirtualBox_nls/}}} and copy the translation templates for each component to new files corresponding to your language. Taking the example from step 1, you will need to copy {{{VirtualBox_xx_YY.ts}}} to {{{VirtualBox_my_MY.ts}}} and {{{qt_xx_YY.ts}}} to {{{qt_my_MY.ts}}}.
+
+ 6. Start Qt Linguist, open and translate new files you got in step 5. Note that you should always keep the {{{.ts}}} files you translate inside the {{{VirtualBox_nls/}}} directory and not move them anywhere else.
+
  7. Make sure all the fields in a special context named {{{@@@}}} in the file {{{VirtualBox_my_MY.ts}}} are properly translated (see below).
- 8. Check your translation at runtime by referring to the '''Testing the translation''' section below.
+
+ 8. 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 @@@ ===
@@ -57 +77 @@
 
  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 {{{Sun Microsystems, Inc.}}}). 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.
+=== Picking up recent changes to the translation files ===
 
-== Updating the translation of an existing language ==
+Existing {{{.ts}}} files are periodically synchronized with the source code by the GUI maintainer at Sun, 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. See ticket:2018 for more information about the synchronization process.
 
-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.
+In order to get the latest changes to the existing {{{.ts}}} that appear as a result of the described synchronization, as well as all other modifications made by Sun developers or other contributors, you will need to do the following steps. These steps imply that you already performed step 5 of the section [#Preparingatranslationtoanewlanguage Preparing a translation to a new language] above and have a copy of the NLS subdirectory in the {{{VirtualBox_nls/}}} directory of your local hard drive.
+
+ 1. Go to the {{{VirtualBox_nls/}}} directory and type the following command in the command line window (terminal) of your host OS:
+{{{
+svn update
+}}}
+    This will pull out recent changes from the VirtualBox SVN (if any) and merge them with the local copy of the {{{.ts}}} file for your language (which, according to step 6 from [#Preparingatranslationtoanewlanguage Preparing a translation to a new language] you keep right there).
+
+ 2. In some rare cases there may be conflicts between the latest SVN version of the {{{.ts}}} file and your local version. You will have to resolve these conflicts manually (please see the [http://svnbook.red-bean.com/ subversion manual] for details). 
+
+== Updating the translation made by someone else ==
+
+If you want to continue the translation made by someone else, please perform the following steps:
 
  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:2018 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 [http://virtualbox.org/svn/vbox/trunk/src/VBox/Frontends/VirtualBox4/nls] and download translation files for all components ({{{VirtualBox_my_MY.ts}}} and {{{qt_my_MY.ts}}}).
- 4. Start Qt Linguist, open the downloaded files and update translations.
- 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.
+ 2. Look through comments to ticket:2018 to find out who is currently maintaining the translation to your language. Contact these people in order to coordinate your work and avoid conflicts.
 
-Existing translation source files are periodically synchronized with the source code by the GUI maintainer at Sun, 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:2018 for more information about the synchronization process.
+ 3. Download the NLS subdirectory from the !VirtualBox SVN repository as described in step 5 of the [#Preparingatranslationtoanewlanguage Preparing a translation to a new language] section.
+
+ 4. Follow other steps starting from step 6 in the [#Preparingatranslationtoanewlanguage Preparing a translation to a new language] section.
 
 == Translation hints ==
@@ -85 +119 @@
 
  1. '''Read''' the [http://doc.trolltech.com/4.3/linguist-manual.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. '''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.
+
  4. '''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.
+
  5. 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.
+
  6. 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.
 
@@ -95 +134 @@
 Use these steps to test your translation:
 
- 1. Select '''File -> Release...''' from the main menu of Qt Linguist.
- 1. 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.
- 1. Repeat the previous step for all other components ({{{qt_my_MY.qm}}}).
- 3. 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.
- 4. Navigate through '''all''' parts of the user interface and check the quality and meaningfulness of the 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.
 
 '''Please note''' that you cannot test translations with !VirtualBox before 1.4.0 because the translation suppport was not enabled in those releases. So either use the last release or compile the current code from SVN.
@@ -107 +150 @@
 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:2018.
 
-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).
+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 innotek 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 innotek Contributor's Agreement] (ICA) and send it to innotek or to make the following statement directly in the ticket:2018 comment where you attach your translation source file: