Localization Service

Access info

Usage

The Localization Service enables callers to store and maintain localized data for use in software applications.

Application- and tenant-level access

This service accepts both an application-level and a tenant-level security access key. The key you use determines your permissions:

• If you have an application-level access key, you can run both the queries and mutations of this service. Any localization data you create is available to all tenants of the current application.
• If you have a tenant-level service access key, you can run only queries. This means you can check for the presence of any localization data defined at application level and view its content.

Note that you can perform the actions above only if the scope of your app-level or tenant-level key has access to queries (and mutations, if applicable) of the Localization Service.

How it works

The following terms are used in conjunction with this service:

• Locale. A locale is the combination of language and country (also known as “culture”) for which you would like to keep a separate translation. For example, en-US is a locale that identifies English language in the United States, de-DE identifies German language in Germany, and so on.
• Label. A label is a string in your application that can be translated. Graphical user interface elements such as buttons, input names, dialog boxes, and so on must all be identified by a label in order to be translatable.
• Translation. A translation is the text of a label adapted (translated) to a particular locale.

You can create, retrieve, update, and delete locales, labels, and label translations as demanded by the application’s requirements. For example, to localize your application in English and Romanian, you might want to proceed as follows:

1. Create the en-US and ro-RO locales, by running the createLocale mutation. For example, to create the ro-RO locale, run the following code:

mutation createLocale($input:CreateLocaleInput!) {
  createLocale(input:$input) {
    code
    language
    country
    name
    active
  }
}

{
  "input": {
    "language": "ro",
    "country": "RO"
  }
}

2. For each label in your application, run the createLabel mutation and specify the label identifier (code) and its default text. The default text will be used in all contexts when no translation of that label is found. For example, you could create a label code btnCreateAccount with the following call:

mutation createLabel($input:CreateLabelInput!) {
  createLabel(input:$input) {
    code
    text
    description
  }
}

{
  "input": {
    "code": "btnCreateAccount",
    "text": "Create Account",
    "description": "The button for creating new accounts."
  }
}

3. For each label in your application, run the createLabelTranslation mutation, to have all your application’s labels translated. The end user behind this action is typically a translator. For example, to add a translation of the previously created button in Romanian, the mutation would look as follows:

mutation createLabelTranslation($input: CreateLabelTranslationInput!) {
  createLabelTranslation(input:$input) {
    code
    localeCode
    labelCode
    text
  }
}

{
  "input": {
    "localeCode": "ro-RO",
    "labelCode": "btnCreateAccount",
    "text": "Creează Cont"
  }
}

After all labels have been translated, you can retrieve the translations available for a particular locale with the translations query. For example, the query in the code listing below retrieves all label translations in Romanian. You would typically run this query when the application starts (so as to populate the translated labels according to the currently selected locale), or when a user has changed the locale of the application from the graphical user interface.

query translations($filter:TranslationsFilter!) {
  translations(filter:$filter) {
    localeCode
    labelCode
    text
    translated
  }
}

{
  "filter": {
    "localeCode": "ro-RO"
  }
}

The response looks similar to the one below:

{
  "data": {
    "translations": [
      {
        "localeCode": "ro-RO",
        "labelCode": "btnCreateAccount",
        "text": "Creează Cont",
        "translated": true
      }
    ]
  }
}

The translated field in the response indicates whether a translation of the label has been found in the selected locale. Value true means the text field stores the label’s translation in the selected locale. Value false means that no translation was found, so the text field stores the default (not translated) text of the label.

Queries

labels

Returns the list of all labels, along with the translations available for each label.

Arguments

LabelsFilter input

Result

Label type

LabelTranslation type

locales

Returns a list of locales. For each locale, all the translations linked to it are also included.

Arguments

LocalesFilter input

Result

Locale type

translations

Returns all translations available for the locale code supplied as argument. If a translation for this locale is not found, then the default label value is placed in the text field.

Arguments

TranslationsFilter input

Result

The result in an array of Translation type objects.

Translation type

version

Returns the API version.

Mutations

createLabel

Creates a new label that identifies a translatable GUI element in your application.

Arguments

CreateLabelInput input

Result

See the Label type.

createLabelTranslation

Adds a translation in a particular locale, to an existing label. Both the locale and the label must exist.

Arguments

CreateLabelTranslationInput input

Result

See the LabelTranslation type.

createLocale

Creates a new locale.

Arguments

CreateLocaleInput input

Result

See the Locale type.

deleteLabel

Deletes a label.

Arguments

Result

See the Label type.

deleteLabelTranslation

Deletes the translation of a label.

Arguments

Result

See the LabelTranslation type.

deleteLocale

Deletes a locale.

Arguments

Result

See the Locale type.

updateLabel

Updates a label’s details.

Arguments

UpdateLabelInput input

Result

See the Label type.

updateLabelTranslation

Updates a label translation.

Arguments

UpdateLabelTranslationInput input

Result

See the LabelTranslation type.

updateLocale

Updates a locale. Note that the only locale property that can be updated is active.

Arguments

UpdateLocaleInput input

Result

See the Locale type.

Appendices

Language codes

Country codes