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)
Note
Unless you set a specific display language for a workspace or a user, the settings are inherited from their parents:
- Workspaces inherit the settings from their parent entity, i.e. parent workspace or organization.
- Users inherit the language settings from their workspaces.
Change the Language
To change the display language:
- Create the
locale
setting. - 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:
Language | Language ID |
---|---|
Chinese | zh-Hans |
Chinese (Cantonese) | zh-HK |
Chinese (Traditional) | zh-Hant |
Dutch | nl-NL |
English (American - default) | en-US |
English (Australian) | en-AU |
English (British) | en-GB |
Finnish | fi-FI |
French | fr-FR |
French (Canadian) | fr-CA |
German | de-DE |
Italian | it-IT |
Japanese | ja-JP |
Portuguese | pt-PT |
Portuguese (Brazilian) | pt-BR |
Russian | ru-RU |
Spanish | es-ES |
Spanish (Latin American) | es-419 |
Note
You cannot change the texts nor add additional languages.
If you use an invalid language ID, English (en-US) will be used instead.
Organization
To change the display language for the whole organization, use one of the following methods:
Steps:
Go to Settings.
Under Localization > Display language, click Change.
Select one of the supported languages and click Apply.
To create the locale
organization settings, send the following POST request /api/v1/entities/organizationSettings
:
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 .
To enable a different language, send the following PUT request /api/v1/entities/organizationSettings/locale
:
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 .
To create the locale
organization settings, send the following POST request /api/v1/entities/organizationSettings
:
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
To enable a different language, send the following PUT request /api/v1/entities/organizationSettings/locale
:
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:
To create the locale
workspace settings, send the following POST request /api/v1/entities/workspaceSettings
:
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 .
To enable a different language, send the following PUT request /api/v1/entities/workspaceSettings/locale
:
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 .
To create the locale
workspace settings, send the following POST request /api/v1/entities/workspaceSettings
:
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
To enable a different language, send the following PUT request /api/v1/entities/workspaceSettings/locale
:
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:
To create the locale
user settings, send the following POST request /api/v1/entities/userSettings
:
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 .
To enable a different language, send the following PUT request /api/v1/entities/userSettings/locale
:
curl $ENDPOINT/api/v1/entities/users/{USER_ID}/userSettings/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": "userSetting",
"id": "{some_id}",
"attributes": {
"content": {"value": "{LANGUAGE_ID}"},
"type": "LOCALE"
}
}
}' | jq .
To create the locale
user settings, send the following POST request /api/v1/entities/userSettings
:
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
To enable a different language, send the following PUT request /api/v1/entities/userSettings/locale
:
Invoke-RestMethod -Method Put -Uri '$ENDPOINT/api/v1/entities/users/{USER_ID}/userSettings/locale' `
-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:
- Export an XLIFF file for localization purposes.
- Translate the content into the desired languages.
- 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.