Localizations Service

The localization service is a simple service that features storage and retrieval of text snippets, translated into multiple languages. A snippet is identified by a key, for example 'mail_greeting', and has associated values in all translated languages.

The notification service as well as the template service are aware of the localization service, and have built-in support for localizations. They both use the localization service in order to generate notifications and emails in appropriate languages based on a pre-defined template, which in turn are filled with localization keys that can be retrieved by the localization service.

Intro

The Localization Service provides a database to store text snippets in multiple languages that can be retrieved on demand by using a localization key. These keys can be included in the Template Service to automatically provide the text messages in the preferred language.

Objects and attributes

LocalizationSets

Text snippets are stored in a LocalizationSet object, which is uniquely identified by its key attribute. The translations and their respective language codes (ISO 639-1) are stored as key-value pairs in the text attribute.

Tip: It is recommended to compose text snippets with complete sentences because the order of words in a sentence can differ between languages due to their unique set of grammar rules.

Common timestamp attributes

All Extra Horizon Services keep track of the time of creation (creation_Timestamp) and of the most recent update (update_Timestamp) of their stored objects.

Note: The timestamp attributes in the Localization Service have a number format, whereas other Services use a string($date-time) format.

Using Variables in a LocalizationSet

Generic text snippets are often combined with user-specific data, such as the user’s name or medical records. These variables can be added to the text strings of the LocalizationSet as $1, $2, etc.

Example LocalizationSet

{
  "key": " heart_rate",
  "text": {
    "EN": "On $1 at $2, your heart rate was $3 bpm.",
    "ES": "El $1 a la(s) $2, su frecuencia cardíaca era de $3 lpm.",
    "NL": "Uw hartslag was $3 hsm op $1 om $2."
  }
}

When requesting text snippets, a value for each variable should be added in numeric order. This means that the first additional argument in the request corresponds to $1.

Example List LocalizationSet text(s) in specific language(s) request

Request body:

{
  "localization_codes": ["NL"],
  "localizations": ["heart_rate, 06/10/2021, 21:00, 63"]
}

Request Response:

{
  "heart_rate": {
        "NL": "Uw hartslag was 63 hsm op 06/10/2021 om 21:00."
        "EN": "On 06/10/2021 at 21:00, your heart rate was 63 bpm.",
  }
}

Actions

This section gives an overview of the available Localization Service endpoints. The full descriptions, including the required permissions and/or scopes, can be found in the API reference documentation.

Managing LocalizationSets

The four CRUD actions are available to set up LocalizationSets. The {languageCode: string} pairs in a set can be updated but cannot be removed individually.

Create LocalizationSet(s)

POST /

List all LocalizationSets

GET /

Update LocalizationSet(s)

PUT /

Delete LocalizationSet(s)

DELETE /

Using LocalizationSets

Text snippets in one or more languages can also be requested directly from the Localization Service with the following endpoint. The response will include the snippet in the requested language(s), if available, and in English.

List LocalizationSet text(s) in specific language(s)

POST /request

In addition, LocalizationSets can be implemented in the Template Service by using double curly brackets: {{key}} in the text fields. The Services will then communicate with each other to provide the text snippets in the user’s preferred language, if available. If not, the default text is returned, i.e. the English version of the snippet.