Chapter 19. Localization of DHIS2

Table of Contents

19.1.
19.2. DHIS2 i18n tool
19.3. Using the DHIS2 translation server
19.4. Database translation app

Localization involves the adaptation of an application to a specific 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. In addition to translation of the user interface itself, metadata content which is contained in the database must also be considered to be translated.

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.

[Important]Important
  • 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.

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

  • Some special variables (e.g. {0} ) used curly brackets. This denotes a variable which will be replaced by a number or other value by the application. You must place this variable notation in the correct position.

There are a number of tools which can be used to support the localization of the user interface as well as the database content, which will be discussed below.