Skip to content

Update API description of locales #1710

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jason-p-pickering merged 1 commit into from
Mar 12, 2026
Merged

Update API description of locales #1710

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 35 additions & 2 deletions src/developer/web-api/i18n.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,44 @@ representations are supported.

/api/33/locales/ui

An example of the response in JSON format:

```json
[
{
"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](https://tools.ietf.org/html/bcp47) 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 are two required parameters: `country` and `language`.
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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). An optional parameter is `language`, which should correspond to a valid [ISO 639-1 language code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes). A third option paramater `script` can also be provided, corresponding to a valid [ISO 15924 script code](https://en.wikipedia.org/wiki/ISO_15924). 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 { #webapi_translations }

Expand Down Expand Up @@ -127,7 +160,7 @@ Send PUT request to `api/dataElements/{dataElementUID}` with full object payload
"created": "2010-02-05T10:58:43.646",
"name": "ANC 1st visit",
"shortName": "ANC 1st visit",
"translations":
"translations":
[
{
"property": "SHORT_NAME",
Expand Down