Multi Language API¶

The Multi Language API is a REST API that enables the caller to set up translations for key metadata attributes in one or more languages.

An organization that operates in several countries needs its catalog to be readable by people who work in different languages. Rather than duplicating each element, open metadata keeps the element in its original language and attaches a separate translation for each additional language. The original remains the authoritative description, and a user interface can show the translation that matches its user's language, falling back to the original where none exists.

How translations are stored¶

Each translation is a TranslationDetail element linked to the element it translates with the TranslationLink relationship. An element can have any number of translations - one for each language, or several for one language where the translations differ by locale.

flowchart LR
    E["Element<br/>(original language)"] -- TranslationLink --> T1["TranslationDetail<br/>language=Spanish<br/>locale=es-ES"]
    E -- TranslationLink --> T2["TranslationDetail<br/>language=Spanish<br/>locale=es-MX"]
    E -- TranslationLink --> T3["TranslationDetail<br/>language=French"]

Figure 1: An element with three translations, two of them for the same language in different locales.

A translation has the following properties:

The translation is anchored to the element it translates, so it is deleted with that element rather than being left behind.

Operations¶

All the operations are called with the unique identifier (GUID) of the element being translated.

Finding the matching translation¶

setTranslation, clearTranslation and getTranslation all start by looking for the existing translation that matches the requested language and locale. The rules are:

• The language must match exactly. The comparison is case-sensitive, so Spanish and spanish are different languages - choose a convention and use it consistently. The language is required: a request without it is rejected with an invalid parameter error, even though it is passed as an optional query parameter.
• If a locale is supplied, the translation's locale must match it too.
• If no locale is supplied, a translation for the language that has no locale is preferred. If every translation for the language has a locale, the first one found is used.

This means a single translation per language can be maintained without ever mentioning a locale, while an element that needs regional variants can address each one by its locale.

The operations then act on the match:

• setTranslation creates a new translation if there is no match. Otherwise, it updates the matching translation, replacing all of its properties with those in the request - a property that is left out of the request is cleared.
• clearTranslation deletes the matching translation. If there is no match, the request still succeeds, since there is already no translation for that language.
• getTranslation returns the matching translation, or an empty response if there is none.

URL marker¶

The Multi Language API is one of the generic view services, whose operations can be called through the URL marker of any view service running in the view server:

{{baseURL}}/servers/{{viewServer}}/api/open-metadata/{urlMarker}/elements/{elementGUID}/translations

Using multi-language as the URL marker routes the request to the metadata access server configured for the Multi Language view service. Using the URL marker of another view service - for example glossary-manager - routes it to the metadata access server configured for that service, so that a user interface built on one specialized API can maintain translations without needing a separate configuration.

Example¶

###
# @name setTranslation
POST {{baseURL}}/servers/{{viewServer}}/api/open-metadata/multi-language/elements/{{elementGUID}}/translations
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "class" : "NewElementRequestBody",
  "properties": {
    "class": "TranslationDetailProperties",
    "language": "Spanish",
    "languageCode": "es",
    "locale": "es-ES",
    "displayName": "add translated display name here",
    "description": "add translated description here",
    "additionalTranslations": {
      "summary": "add translated summary here"
    }
  }
}

###
# @name getTranslation
GET {{baseURL}}/servers/{{viewServer}}/api/open-metadata/multi-language/elements/{{elementGUID}}/translations/retrieve?language=Spanish&locale=es-ES
Authorization: Bearer {{token}}

Further information¶

• 0022 Translations defines the TranslationDetail entity and TranslationLink relationship.
• Egeria-api-multi-language.http contains sample requests for every operation in this API.

Raise an issue or comment below