Change Display Language

By default, GoodData displays the user interface in English.

You can enable a different display language for your organization, workspace, or even for individual users. Dashboards and Analytical Designer are then displayed in the language that you select.

Available Languages

The GoodData user interface supports the following languages, listed alphabetically:

• Chinese
• Chinese (Cantonese)
• Chinese (Traditional)
• Dutch
• English (Australia)
• English (Great Britain)
• English (USA)
• Finnish
• French
• French (Canada)
• German
• Italian
• Japanese
• Portuguese (Brazil)
• Portuguese (Portugal)
• Russian
• Spanish
• Spanish (Latin America)

Change the Language

To change the display language:

1. Create the locale setting.
2. Enable the language that you want to use.

Below is a table of language IDs that you can use to enable different languages. The IDs are listed in alphabetical order:

Organization

To change the display language for the whole organization, use one of the following methods:

curl $ENDPOINT/api/v1/entities/organizationSettings \
  -H "Content-Type: application/vnd.gooddata.api+json" \
  -H "Accept: application/vnd.gooddata.api+json" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -X POST \
  -d '{
    "data":
    {
        "type": "organizationSetting",
        "id": "{some_id}",
        "attributes": {
            "content": {"value": "{LANGUAGE_ID}"},
            "type": "LOCALE"
        }
    }
}' | jq .

curl $ENDPOINT/api/v1/entities/organizationSettings/locale \
  -H "Content-Type: application/vnd.gooddata.api+json" \
  -H "Accept: application/vnd.gooddata.api+json" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -X PUT \
  -d '{
    "data":
    {
        "type": "organizationSetting",
        "id": "{some_id}",
        "attributes": {
            "content": {"value": "{LANGUAGE_ID}"},
            "type": "LOCALE"
        }
    }
}' | jq .

Invoke-RestMethod -Method Post -Uri '$ENDPOINT/api/v1/entities/organizationSettings' `
-ContentType 'application/vnd.gooddata.api+json' `
-H @{ 
    'Accept' = 'application/vnd.gooddata.api+json'
    'Authorization' = 'Bearer {API_TOKEN}' 
} `
-Body '{
    "data":
    {
        "type": "organizationSetting",
        "id": "{some_id}",
        "attributes": {
            "content": {"value": "{LANGUAGE_ID}"},
            "type": "LOCALE"
        }
    }
}' | ConvertTo-Json

Invoke-RestMethod -Method Put -Uri '$ENDPOINT/api/v1/entities/organizationSettings/locale' `
-ContentType 'application/vnd.gooddata.api+json' `
-H @{ 
    'Accept' = 'application/vnd.gooddata.api+json'
    'Authorization' = 'Bearer {API_TOKEN}' 
} `
-Body '{
    "data":
    {
        "type": "organizationSetting",
        "id": "{some_id}",
        "attributes": {
            "content": {"value": "{LANGUAGE_ID}"},
            "type": "LOCALE"
        }
    }
}' | ConvertTo-Json

Workspace

To change the display language for individual workspaces, you need to use the API:

curl $ENDPOINT/api/v1/entities/workspaces/{WORKSPACE_ID}/workspaceSettings \
  -H "Content-Type: application/vnd.gooddata.api+json" \
  -H "Accept: application/vnd.gooddata.api+json" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -X POST \
  -d '{
    "data":
    {
        "type": "workspaceSetting",
        "id": "{some_id}",
        "attributes": {
            "content": {"value": "{LANGUAGE_ID}"},
            "type": "LOCALE"
        }
    }
}' | jq .

curl $ENDPOINT/api/v1/entities/workspaces/{WORKSPACE_ID}/workspaceSettings/locale \
  -H "Content-Type: application/vnd.gooddata.api+json" \
  -H "Accept: application/vnd.gooddata.api+json" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -X PUT \
  -d '{
    "data":
    {
        "type": "workspaceSetting",
        "id": "{some_id}",
        "attributes": {
            "content": {"value": "{LANGUAGE_ID}"},
            "type": "LOCALE"
        }
    }
}' | jq .

Invoke-RestMethod -Method Post -Uri '$ENDPOINT/api/v1/entities/workspaces/{WORKSPACE_ID}/workspaceSettings' `
-ContentType 'application/vnd.gooddata.api+json' `
-H @{ 
    'Accept' = 'application/vnd.gooddata.api+json'
    'Authorization' = 'Bearer {API_TOKEN}' 
} `
-Body '{
    "data":
    {
        "type": "workspaceSetting",
        "id": "{some_id}",
        "attributes": {
            "content": {"value": "{LANGUAGE_ID}"},
            "type": "LOCALE"
        }
    }
}' | ConvertTo-Json

Invoke-RestMethod -Method Put -Uri '$ENDPOINT/api/v1/entities/workspaces/{WORKSPACE_ID}/workspaceSettings/locale' `
-ContentType 'application/vnd.gooddata.api+json' `
-H @{ 
    'Accept' = 'application/vnd.gooddata.api+json'
    'Authorization' = 'Bearer {API_TOKEN}' 
} `
-Body '{
    "data":
    {
        "type": "workspaceSetting",
        "id": "{some_id}",
        "attributes": {
            "content": {"value": "{LANGUAGE_ID}"},
            "type": "LOCALE"
        }
    }
}' | ConvertTo-Json

User

To change the display language for individual users, you need to use the API:

curl $ENDPOINT/api/v1/entities/users/{USER_ID}/userSettings \
  -H "Content-Type: application/vnd.gooddata.api+json" \
  -H "Accept: application/vnd.gooddata.api+json" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -X POST \
  -d '{
    "data":
    {
        "type": "userSetting",
        "id": "{some_id}",
        "attributes": {
            "content": {"value": "{LANGUAGE_ID}"},
            "type": "LOCALE"
        }
    }
}' | jq .

curl $ENDPOINT/api/v1/entities/users/{USER_ID}/userSettings/{locale_id} \
  -H "Content-Type: application/vnd.gooddata.api+json" \
  -H "Accept: application/vnd.gooddata.api+json" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -X PUT \
  -d '{
    "data":
    {
        "type": "userSetting",
        "id": "{some_id}",
        "attributes": {
            "content": {"value": "{LANGUAGE_ID}"},
            "type": "LOCALE"
        }
    }
}' | jq .

Invoke-RestMethod -Method Post -Uri '$ENDPOINT/api/v1/entities/users/{USER_ID}/userSettings' `
-ContentType 'application/vnd.gooddata.api+json' `
-H @{ 
    'Accept' = 'application/vnd.gooddata.api+json'
    'Authorization' = 'Bearer {API_TOKEN}' 
} `
-Body '{
    "data":
    {
        "type": "userSetting",
        "id": "{some_id}",
        "attributes": {
            "content": {"value": "{LANGUAGE_ID}"},
            "type": "LOCALE"
        }
    }
}' | ConvertTo-Json

Invoke-RestMethod -Method Put -Uri '$ENDPOINT/api/v1/entities/users/{USER_ID}/userSettings/{locale_id}' `
-ContentType 'application/vnd.gooddata.api+json' `
-H @{ 
    'Accept' = 'application/vnd.gooddata.api+json'
    'Authorization' = 'Bearer {API_TOKEN}' 
} `
-Body '{
    "data":
    {
        "type": "userSetting",
        "id": "{some_id}",
        "attributes": {
            "content": {"value": "{LANGUAGE_ID}"},
            "type": "LOCALE"
        }
    }
}' | ConvertTo-Json

Metadata Localization

When you extend your analytics across various regions and languages, it’s beneficial to adapt the embedded analytics to fit local contexts. This includes translating the content within visualizations, assigning local names to data entities, and adjusting date or currency formats as needed.

Language settings can be customized at different levels: organization-wide, for individual tenants (workspaces), or even for specific users. Typically, the metadata language aligns with the user interface (UI) language. However, situations may arise where you prefer the metadata in one language and the UI in another. For instance, while using the Analytics Designer in English, you might wish to provide the embedded visualizations to your end-users in multiple languages, which they can select from their account settings.

XLIFF Files

Metadata localization within GoodData uses standard XLIFF files (version 2.0 or 2.1). These files contain all translatable text strings. The translations are stored within the workspace that originates the entities, i.e. translations of entities must be added to workspaces that have ownership of them. A single XLIFF file can serve multiple workspaces, assuming they are copies of an original workspace and remain unaltered. Modifications to a cloned workspace or the creation of a new workspace necessitate generating new XLIFF files for each case.

Entities subject to localization include titles, descriptions, tags (in attributes, labels, facts, datasets, metrics, attribute hierarchies, dashboards, visualizations, and filters), along with free-form content in dashboards, visualizations, and filters. The Declarative API does not support localization.

This localization feature is designed for scenarios where modifications to workspace metadata, dashboards, or visualizations are carried out in the original English version, which is then translated and distributed to users in other languages. Translation between languages (e.g., German to French) is not supported; translations can only be made from the default language (en-US) to the target language. Should a translation for a string/entity not exist, GoodData defaults to using the original language values.

Metadata Localization Process

The process of localizing metadata involves three main steps:

1. Export an XLIFF file for localization purposes.
2. Translate the content into the desired languages.
3. Import the localized XLIFF file back into GoodData.

Exporting an XLIFF File

To begin the localization process, use the GET API to export metadata strings that require translation for each language. This action will generate an XLIFF file for any specified language.

To retrieve the original text strings, use the following API call:

POST {"locale":"<locale-identifier>"} to api/v1/actions/workspaces/<id>/translations/retrieve

If translations already exist, specify a locale identifier in the above API call to obtain translations for a specific language.

To show a list of already translated locales, use the following API call:

GET api/v1/actions/workspaces/<id>/translations

Translating the XLIFF File

Within the XLIFF file, specify the target language using the standard IETF RFC 5646 language tag (for example, es-ES for Spanish or ja-JP for Japanese). Translate the strings contained within the <source> tags and add your translations within the same segment, enclosed in <target> tags.

Example structure of an XLIFF file:

<xliff xmlns="urn:oasis:names:tc:xliff:document:2.0" version="2.0"
       srcLang="en-US" trgLang="cs-CZ">
 <file id="cz-cz-translation">
  <group id="fact">
   <group id="fact.volume">
    <unit id="fact.volume.title">
     <segment>
        <source>tagA</source>
        <target>Translation of tagA</target>
     </segment>
     <segment>
        <source>tagB</source>
        <target>Translation of tagB</target>
     </segment>
    </unit>
   </group>
  </group>
 </file>
</xliff>

To aid translators in understanding the context of free-form segments, each segment contains JSON paths within the source text. This is accomplished using mrk inline elements, making it easier for translators to navigate and comprehend the document structure.

Example:

<segment id="<hashed_value>">
  <source>
    <mrk id="1" type="free-form:path" value="<json_path>"/>Source text
  </source>
  <target>Translated text</target>
</segment>

Importing the XLIFF File

After translating the strings in the XLIFF files, they can be imported back into GoodData. Administrators will use an API call with the corresponding XLIFF file for each language.

To create or update translations, use:

POST the XLIFF document to api/v1/actions/workspaces/<id>/translations/set

To remove translations for a specific locale, use:

POST {"locale":"<locale-identifier>"} to api/v1/actions/workspaces/<id>/translations/clean

Setting Up Metadata Localizations

To choose a specific metadata localization through the API, you can set the desired locale using the METADATA_LOCALE parameter. To do so, follow the same steps as described in the sections above. See Change the Language for Organization, Workspace, or User for details.

Only users with organization.MANAGE or workspace.MANAGE permissions can configure metadata localizations for a workspace. Once set up, users can choose their preferred language for metadata.

Limitations of Metadata Localizations

• Whenever a metadata string of an object is modified (for example, if the author of a dashboard changes its title), all associated translations are reset. To ensure that translations remain up-to-date, the organization’s administrator is required to perform a new export-import process for localization for each language.

• The default language, en-US, cannot be targeted for translations. If attempted, such translations will be ignored by the backend.

• Multi-line text strings should not include indentation. For instance:

      <target>Multi-line
  text.
      </target>
  

  Automatic formatting by some code editors might indent these elements, potentially causing issues with backend processing.

• Filtering operations use the original language.

• In the XLIFF file, translations must maintain the original tag values’ order. Changing the order of segments can result in lost ordering and incorrect segment returns in XLIFF exports for that language, as illustrated by the example of improper segment order.

• Localized versions are intended solely for content consumption. For instance, a user with a German localized version will see metrics and reports in German but cannot alter the names of these metrics or reports.