=== modified file 'src/docbkx/en/dhis2_localization_guide.xml' --- src/docbkx/en/dhis2_localization_guide.xml 2013-05-08 08:43:55 +0000 +++ src/docbkx/en/dhis2_localization_guide.xml 2013-08-19 09:26:41 +0000 @@ -2,20 +2,125 @@ Localization concepts - Localization involves the adaptation of an application to another location. When implementing DHIS2 in a given country, adequate resources should be allocated to translate the application when required. Translation of the user interface elements, messages, layout, date and time formats, currency and other aspects must be considered. DHIS2 supports internationalization (i18n) of the user interface through the use of Java property strings. Each element in the user interface has been assigned a specific key, which is linked to a value. - As an example, consider the following key/value pairs. + Localization involves the adaptation of an application to another location. When + implementing DHIS 2 in a given country, adequate resources should be allocated to translate the + application when required. Translation of the user interface elements, messages, layout, date + and time formats, currency and other aspects must be considered. DHIS 2 supports + internationalization (i18n) of the user interface through the use of Java property strings. Each + element in the user interface has been assigned a specific key which is linked to a value. As an + example, consider the following key/value pairs. org_unit_tree=Organisation Unit Tree error_occurred=An error has occurred. In French the same key/value pairs would appear as follows org_unit_tree=Arborescence des unités d'organisation error_occurred=Une erreur s'est produite - Note that the keys (before the = symbol) are the same in both examples, but the values (after the = ) symbol are in each of the respective languages. Each of these key/value pairs would need to be translated from the original language (English) to the destination language (e.g. French). When the user specifies French for the user interface language, all of the strings would then appear in French instead of the default language (English). Any strings which have not been translated, would appear in English. - There are a number of different mechanisms to begin to localize DHIS2, two of which will be discussed in the next sections. The web portal is a quite useful tool for collaborative translations by multiple people, however an on-line connection is required in order to utilize this resource. A special tool, the DHIS i18n Resource Editor, has been developed specifically to facilitate the translation of the application from one language to another and can be used off-line once a copy of the DHIS2 source code has been obtained. -
- Using the DHIS2 translation server - A web-based portal solution has been setup in order to facilitate the translation of DHIS2 into multiple languages. Simply direct your browser to http://translate.dhis2.net/ and register for an account by providing a username, email address and password. The server will send you a confirmation email which you can use to activate your account. Once you have activated your account, simply press the "Log in" link from the main portal page, and provide your username and password. + Note that the keys (text before the = symbol) are the same in both examples, but the values + (after the = ) symbol are in each of the respective languages. Each of these key/value pairs + would need to be translated from the original language (English) to the destination language + (e.g. French). When the user specifies French for the user interface language, all of the + strings would then appear in French instead of the default language (English). Any strings which + have not been translated, would appear in English. + The translation keys and values are stored in files called resource bundles. The resource + bundles follow fallback rules, meaning that one can create a hierarchy of resource bundles + through the file naming convention where property keys are searched from the bottom of the + hierarchy and returned at the first match. This comes in useful when you need partial + translations, for instance to cater for country-specific variances in a language. One example is + Portuguese for which DHIS 2 has several resource bundles: + + + i18n_global.properties (The ulimate fallback locale, which is English) + + + i18n_module_pt.properties (Portuguese translations) + + + i18n_module_pt_BR.properties (Brazilian Portuguese translations) + + + This structure allows us to have a full general Portuguese translation, and a partial + Brazilian Portuguese translation which provides translations of Brazilian-specific keys. For + keys which are not translated in the Brazilian Portuguese resource bundle, the system will fall + back to the general Portuguese translation. If the key is not present in that file either, the + system will fall back to the ultimate fallback locale which is English. + There are a number of different mechanisms to begin to localize DHIS 2, two of which will be + discussed in the next sections. +
+ DHIS 2 i18n tool + The i18n resource editor is Java desktop application which can be downloaded from + http://www.dhis2.org/downloads . It requires that you have checked out the DHIS 2 source code + from Bazaar (check out http://www.dhis2.org/development if necessary) and have a Java Runtime + Environment installed on your computer. On Windows, simly unpack the ZIP archvie and click the + executable file. On Linux, extract the archive, navigate inside the extracted directory and + invoke the following: + java -jar dhis-i18n-resourceeditor.jar + + + + Press "Browse" when the application starts and select the path to the + "dhis-2" directory inside your local copy (checkout) of the DHIS 2 source code repository, + followed by OK. + + + + + + + + + + Next, select the destination locale which you will translate strings into. Remember + that if you want to create or add to a general language translation, select e.g. + "Portuguese - [pt]. If you want to create a country-specific translation, select e.g. + "Portuguese - Brazil [pt_BR]. Locales which already have keys translated will show the + text "Resources for this locale exist". + + + + + + + + + + Select one of the web modules from the left hand side to translate, e.g. + dhis-web-maintenance-dataset. + + + + + + + + Once you have selected a module, click on a particular key from the left-hand side. A + reference value for the key will be displayed in the lower right-hand pane, and the + translation value will be displayed in the upper right-hand pane. Keys with missing values + will be indicated with a red icon. If the value does not exist, simply add the translation + there. + + + Once you have finished translating, make sure to press the "Save" button. + + +
+
+ Using the DHIS 2 translation server + A web-based portal solution has been setup in order to facilitate the translation of DHIS + 2 into multiple languages. Simply direct your browser to http://translate.dhis2.net/ and + register for an account by providing a username, email address and password. The server will + send you a confirmation email which you can use to activate your account. Once you have + activated your account, simply press the "Log in" link from the main portal page, + and provide your username and password. The first time you login, you should select your settings, by clicking "My account->Settings". Here you can select your interface language, the projects which you wish to work on, and the languages which you will translate into. Be sure to press "Save" when have finished making your changes. - To start translating, be sure you have logged in, and then press the "Home" link in the upper-right hand corner. Select a project (e.g. DHIS2) and then click on the language which you wish to translate. The number of words which need to be translated will be displayed under the "Summary" field. Click on one of the modules (e.g. dhis-2) and the keep drilling down through the folders to find a module which needs translation, (e.g. dhis-web->dhis-web-caseentry). Now click on the "Summary" text which will say something like "194 words need attention". You will be directed to the key/value pair which requires translation. + To start translating, be sure you have logged in, and then press the "Home" link + in the upper-right hand corner. Select a project (e.g. DHIS 2) and then click on the language + which you wish to translate. The number of words which need to be translated will be displayed + under the "Summary" field. Click on one of the modules (e.g. dhis-2) and the keep + drilling down through the folders to find a module which needs translation, (e.g. + dhis-web->dhis-web-caseentry). Now click on the "Summary" text which will say + something like "194 words need attention". You will be directed to the key/value + pair which requires translation. @@ -26,45 +131,6 @@ In this case, we need to translate the phrase "Name-based" from English to French. Enter the translation in the window just below the reference phrase.. If you are unsure if the translation is correct or needs review, you can mark it as "Fuzzy". Once you have completed the translation, just press "Submit". Your translations will be incorporated into the source code on a regular basis by the development team.
- DHIS2 i18n tool - - - Press "Browse" when the application starts and select the path of your local copy of the DHIS2 source code tree followed by OK. - - - - - - - - - - Next, select the destination locale which you will translate strings into. - - - - - - - - - - Select one of the modules from the left hand side to translate, e.g. dhis-web-caseentry. - - - - - - - - Once you have selected a module, click on a particular key from the left-hand pane. A reference value for the key will be displayed in the lower right-hand pane, and the translation value will be displayed in the upper right-hand pane. If the value does not exist, simply add the translation there. - - - Once you have finished translating, be sure to press the "Save" button. - - -
-
Important localization concepts @@ -72,7 +138,9 @@ There are a number of key/value pairs such as "format.FinancialApril.startDate=dd MMM yyyy 'to '" which are used for date/time formatting in the application. Part of the value should not be translated because it is actually a Java date formatting template. It this example it is "dd MMM yyyy". Consult this site for more information on the Java date formatting syntax. The part of the value which can be translated would be "to", for instance to "a" in Spanish. If these data format template strings are translated, it may result in errors in the application. - It is not necessary to translate a string from the original language (English) if the translated string is the same. You can simply leave it blank. By default, DHIS2 will use English values for all strings which have not been translated. + It is not necessary to translate a string from the original language (English) if + the translated string is the same. You can simply leave it blank. By default, DHIS 2 + will use English values for all strings which have not been translated. All translated strings must be stored in escaped UTF-8 format. If you are using the translation portal, be sure your browser settings are set to UTF-8 when translating. If you are using a text editor or other tool such as an IDE, you may need to convert the UTF-8 characters to escaped syntax, using the Java "native2ascii" utility. === modified file 'src/docbkx/en/resources/images/i18n/i18n_tool_main_window.png' Binary files src/docbkx/en/resources/images/i18n/i18n_tool_main_window.png 2012-01-23 05:19:30 +0000 and src/docbkx/en/resources/images/i18n/i18n_tool_main_window.png 2013-08-19 09:26:41 +0000 differ === removed file 'src/docbkx/en/resources/images/i18n/i18n_tool_select_locale.PNG' Binary files src/docbkx/en/resources/images/i18n/i18n_tool_select_locale.PNG 2012-01-23 05:19:30 +0000 and src/docbkx/en/resources/images/i18n/i18n_tool_select_locale.PNG 1970-01-01 00:00:00 +0000 differ === added file 'src/docbkx/en/resources/images/i18n/i18n_tool_select_locale.png' Binary files src/docbkx/en/resources/images/i18n/i18n_tool_select_locale.png 1970-01-01 00:00:00 +0000 and src/docbkx/en/resources/images/i18n/i18n_tool_select_locale.png 2013-08-19 09:26:41 +0000 differ === removed file 'src/docbkx/en/resources/images/i18n/i18n_tool_start_translating.PNG' Binary files src/docbkx/en/resources/images/i18n/i18n_tool_start_translating.PNG 2012-01-23 05:19:30 +0000 and src/docbkx/en/resources/images/i18n/i18n_tool_start_translating.PNG 1970-01-01 00:00:00 +0000 differ === removed file 'src/docbkx/en/resources/images/i18n/i18n_tool_startup.PNG' Binary files src/docbkx/en/resources/images/i18n/i18n_tool_startup.PNG 2012-01-23 05:19:30 +0000 and src/docbkx/en/resources/images/i18n/i18n_tool_startup.PNG 1970-01-01 00:00:00 +0000 differ === added file 'src/docbkx/en/resources/images/i18n/i18n_tool_startup.png' Binary files src/docbkx/en/resources/images/i18n/i18n_tool_startup.png 1970-01-01 00:00:00 +0000 and src/docbkx/en/resources/images/i18n/i18n_tool_startup.png 2013-08-19 09:26:41 +0000 differ