Chapter 19. Localization concepts

Table of Contents

19.1. DHIS2 i18n tool
19.2. Using the DHIS2 translation server
19.3. Important 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.

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 (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 DHIS2 has several resource bundles:

  1. i18n_global.properties (The ulimate fallback locale, which is English)

  2. i18n_module_pt.properties (Portuguese translations)

  3. 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 DHIS2, two of which will be discussed in the next sections.

19.1. DHIS2 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 DHIS2 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

  1. Press "Browse" when the application starts and select the path to the "dhis-2" directory inside your local copy (checkout) of the DHIS2 source code repository, followed by OK.

  2. 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".

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

  4. Once you have finished translating, make sure to press the "Save" button.