White-labeling: Custom Translation

ThingsBoard supports a multilingual interface through its built-in internationalization (i18n) system. The Custom translation feature lets you add new languages, modify existing translations, and apply custom translations to dashboard titles, widget labels, device names, telemetry keys, and other UI elements.

1. Click the three-dot icon in the top-right corner and select Account.

2. In the profile settings, choose the desired language from the dropdown list.

3. Click Save to apply the changes.

The ThingsBoard interface will switch to the selected language.

If the desired language is not available, you can add one.

1. Navigate to the White labeling page and open the Custom translation tab. Click the Add new language button.

2. Select the desired language from the list.

3. Optionally upload a JSON file with a translation map for quick setup, or add translations manually later.

4. Click Add.

The new language is now available. You and your users can set it as the interface language.

The Custom translation tab shows a list of available languages with their translation progress as a percentage. Click the pencil icon next to a language to open the editor.

The editor has two tabs:

• Basic — edit existing keys or add new ones in a table view
• Advanced — upload a JSON file with a full translation map

The table has three columns:

1. Term key — links a UI element to its translation
2. English value — fallback value used when no translation exists for the selected language
3. Selected language value — the translated text

The editor provides filters to locate specific keys:

1. Open the translation map for the desired language and click the plus icon in the top-right corner.

2. Fill in the new row: enter the term key, its English value, and the value for the selected language.

3. Click anywhere outside the input field to save.

The new key is automatically added to every language in your list. Languages without a specific translation will use the English value as a fallback.

1. Open the language editor and use the search field to find the key you want to edit.

2. Update the translation value.

3. Click anywhere outside the input field to save.

To reset a key’s translation to the system administrator’s default, click the broom icon in that key’s row.

If you have many translation keys, uploading a JSON file is more efficient than adding them manually.

1. Open the language editor and switch to the Advanced tab.

2. Paste or upload your translation map in JSON format.

3. Click Save.

Example translation map:

{
  "dashboard": {
    "dashboards": "Instrumententafeln"
  },
  "notification": {
    "notification-center": "Benachrichtigungszentrale"
  },
  "white-labeling": {
    "white-labeling": "Weißkennzeichnung"
  },
  "integration": {
    "integrations-center": "Integrationszentrum"
  }
}

You can provide custom translations for any UI element — dashboard titles, widget names, device names, telemetry keys, and custom menu items — using the i18n key syntax.

In the title or label field of any UI element, replace plain text with a key using the i18n: prefix wrapped in curly braces:

{i18n:custom.translation.key}

Where:

• i18n: — required prefix
• custom.translation.key — the key added to the translation map

Then add the corresponding value for this key in each language’s translation map:

You can apply i18n keys to dashboard titles, widget titles, telemetry key labels, and axis labels. For a detailed, step-by-step walkthrough, see the recipe: Translate dashboard elements.

Custom translations work in widget functions — for example, in the HTML Value Card widget, where i18n keys in the HTML template are resolved to the user’s language. See the recipe: Custom translation in HTML Value Card.

Custom translation keys also work in cell content functions (data post-processing). See the recipe: Custom translation in data post-processing.

To delete a language or reset its translations to the default version, click the trash icon next to it and confirm the deletion.