Custom translations

The text of cards or dashboards can be translated into multiple languages by using custom translations. For example, the title, description, and labels of a card can be translated into multiple languages based on the user's language settings. You need to request and reference the translations for dashboards or cards that are in your organization.

Requesting translations

After you create a card or dashboard, you can request the translated content for your card or dashboard. Use the following procedure to request translated content.

  1. Create a JSON file that contains all the translation keys and values. For a sample JSON file, see Example of a sample JSON file.
  2. Create a support ticket and attach the JSON files to the ticket. For more information, see Contacting IBM Support.
    Make sure that you create one JSON file for each language in which you want the translated content and attach all the files to support ticket. The support team validates the content of the provided files. If the files pass validation, the support team uploads the translations to your organization and notifies you after they are deployed successfully.
    Note: The support team checks the only format of the JSON file; the correctness of the translation is not checked.

Example of a sample JSON file

The following code snippet is a sample English JSON file.

{
  "title": "MyTitle",
  "table": {
    "title": "MyTableTitle",
    "header": "MyHeader",
    "columns": {
      "first": "Name",
      "second": "Quantity"
    },
    "footer": "Click me",
    "description": "All about my table"
  }
}
Where,
Key
A unique identifier that is used to retrieve associated data in a data structure, for example, title.
Value
The data that is associated with a specific key in a key-value pair, for example, MyTitle.

Referencing translations

After the translation files are uploaded and deployed successfully, use the following procedure to reference the translation keys.

  1. Create translation keys as shown in the following format,
    Table 1. Format of translation keys
    Format Examples
    Provider ID.key c8fd3637-d40a-4d47-a5ef-62cfaa96bbd7.title or {{tenantId}}.title
    Provider ID.nested key c8fd3637-d40a-4d47-a5ef-62cfaa96bbd7.table.header or {{tenantId}}.table.header
    Where,
    Provider ID
    The tenant ID of your organization, for example, c8fd3637-d40a-4d47-a5ef-62cfaa96bbd7. You can use interpolation instead of writing the complete tenant ID, for example, {{tenantId}}.
    Note: Some fields might not accept the interpolation.
    Delimiter (.)
    A character that separates the provider ID and key.
    Key or nested key
    The unique identifier that is used to retrieve associated data in a data structure, for example, title or table.header.
  2. To reference the translation keys in cards, use the following procedure. You can also reference keys in dashboards.
    1. From the navigation menu, click Card builder.
    2. On the My cards tab, click the name of the card that you want to edit.
    3. In the right side panel, on the General tab, in the Card name field, enter the translation key, for example c8fd3637-d40a-4d47-a5ef-62cfaa96bbd7.title.

      Similarly, you can reference the translation keys for other fields, such as description, card title or header, and labels.

  3. To reference the translation keys in dashboards, use the following procedure.
    1. From the navigation menu, click Dashboard builder.
    2. On the My dashboards tab, click the name of the dashboard that you want to edit and then click the Settings icon.
    3. In the Name field, enter the translation key, for example c8fd3637-d40a-4d47-a5ef-62cfaa96bbd7.title.

      Similarly, you can reference the translation keys for other fields, such as the description, and labels.

Fetching translations

After deployment, all available translations in the appropriate language are retrieved according to the current user's language settings. The translated value of a key is resolved according to the following rules:
  • If the translation exists in the target language, the target language content is shown.
  • If no translation exists in the target language, but one exists in the default language, the default language content is shown.
    Note: The default language is English.
  • If no translation exists in the default language, the key is shown.