I18n¶

Locales¶

DHIS2 supports translations both for the user interface and for database content.

UI locales¶

You can retrieve the available locales for the user interface through the following resource with a GET request. XML and JSON resource representations are supported.

/api/33/locales/ui

An example of the response in JSON format:

[
{
"locale": "ar",
"languageTag": "ar",
"name": "العربية",
"displayName": "Arabic"
},
{
"locale": "ar_EG",
"languageTag": "ar-EG",
"name": "العربية (مصر)",
"displayName": "Arabic (Egypt)"
},
{
"locale": "uz_UZ_Cyrl",
"languageTag": "uz-Cyrl-UZ",
"name": "ўзбекча (Кирил, Ўзбекистон)",
"displayName": "Uzbek (Cyrillic, Uzbekistan)"
}
]

The locale property is an internal DHIS2 representation of the locale, and consists of the language code, country code and script code (if applicable) separated by underscores. It should not be confused with the languageTag property, which is the standard IETF BCP 47 language tag representation of the locale, with components separated by hyphens. The name property is the name of the locale in its own language, while the displayName property is the name of the locale in the users's preferred language.

Database content locales¶

You can retrieve and create locales for the database content with GET and POST requests through the dbLocales resource. XML and JSON resource representations are supported. To POST data, there is one required parameter: country. This should correspond to a valid ISO 3166-1 alpha-2 country code. An optional parameter is language, which should correspond to a valid ISO 639-1 language code. A third option paramater script can also be provided, corresponding to a valid ISO 15924 script code. Do take note that if the script parameter is provided, the language parameter must also be provided.

Example request to get database locales for US English:

/api/locales/dbLocales?country=US&language=en

Example request to create a new database locale for Canadian French: POST /api/locales/dbLocales?country=CA&language=fr

Translations¶

DHIS2 allows for translations of database content. If a metadata is translatable, then it will have a translations property.

That means you can retrieve and update translations using metadata class resources such as api/dataElements, api/organisationUnits, api/dataSets, etc.

Get translations¶

You can get translations for a metadata object such as DataElement by sending a GET request to api/dataElements/{dataElementUID}

The response contains full details of the DataElement which also includes the translations property as below

{
  "id": "fbfJHSPpUQD",
  "href": "https://play.dhis2.org/dev/api/29/dataElements/fbfJHSPpUQD",
  "created": "2010-02-05T10:58:43.646",
  "name": "ANC 1st visit",
  "shortName": "ANC 1st visit",
  "translations": 
  [
    {
      "property": "SHORT_NAME",
      "locale": "en_GB",
      "value": "ANC 1st visit"
    },
    {
      "property": "NAME",
      "locale": "fr",
      "value": "Soin prénatal 1"
    },
    {
      "property": "NAME",
      "locale": "en_GB",
      "value": "ANC 1st visit"
    }
  ]
}

{
  "translations": 
  [
    {
      "property": "SHORT_NAME",
      "locale": "en_GB",
      "value": "ANC 1st visit"
    },
    {
      "property": "NAME",
      "locale": "fr",
      "value": "Soin prénatal 1"
    },
    {
      "property": "NAME",
      "locale": "en_GB",
      "value": "ANC 1st visit"
    }
  ]
}

Create/Update translations¶

You can create translations by sending a PUT request with same JSON format to api/dataElements/{dataElementUID}/translations

{
  "translations": 
  [
    {
      "property": "SHORT_NAME",
      "locale": "en_GB",
      "value": "ANC 1st visit"
    },
    {
      "property": "NAME",
      "locale": "fr",
      "value": "Soin prénatal 1"
    },
    {
      "property": "DESCRIPTION",
      "locale": "fr",
      "value": "description in french"
    },
    {
      "property": "FORM_NAME",
      "locale": "fr",
      "value": "name in french"
    }
  ]
}

Alternatively, you can also just update the object with payload including the translations property.

Send PUT request to api/dataElements/{dataElementUID} with full object payload as below:

{
  "id": "fbfJHSPpUQD",
  "created": "2010-02-05T10:58:43.646",
  "name": "ANC 1st visit",
  "shortName": "ANC 1st visit",
  "translations":
  [
    {
      "property": "SHORT_NAME",
      "locale": "en_GB",
      "value": "ANC 1st visit"
    },
    {
      "property": "NAME",
      "locale": "fr",
      "value": "Soin prénatal 1"
    },
    {
      "property": "NAME",
      "locale": "en_GB",
      "value": "ANC 1st visit"
    }
  ]
}

The status code will be 204 No Content if the data value was successfully saved or updated, or 409 Conflict if there was a validation error (e.g. more than one SHORT_NAME for the same locale).

The common properties which support translations are listed in the table below.

The classes which support translations are listed in the table below.

Internationalization¶

In order to retrieve key-value pairs for translated strings you can use the i18n resource.

/api/33/i18n

The endpoint is located at /api/i18n and the request format is a simple array of the key-value pairs:

[
  "access_denied",
  "uploading_data_notification"
]

The request must be of type POST and use application/json as content-type. An example using curl, assuming the request data is saved as a file keys.json:

curl -d @keys.json "play.dhis2.org/demo/api/33/i18n" -X POST
  -H "Content-Type: application/json" -u admin:district

The result will look like this:

{
  "access_denied":"Access denied",
  "uploading_data_notification":"Uploading locally stored data to the server"
}