ThingsBoard supports a multilingual interface through its built-in internationalization (i18n) system. Select and use the interface in the language that suits you best.
However, for more specific requirements, the
Custom translation
feature is available, which allows you to:
Use
custom translations
for dashboard titles, widgets, devices, telemetry keys, and other interface elements.
Change platform language
To change the language of your account, follow these steps:
Click the three-dot icon in the top-right corner of the screen and select “Account”.
In the profile settings, choose the desired language from the dropdown list.
Apply the changes.
After that, the ThingsBoard interface will switch to the selected language.
Adding new language
If the desired language is not in the list, you can add a new one. To do this:
Go to the “Custom translation” tab of the “White labeling” page, and click the “Add new language” button in the upper-right corner.
In the window that opens, select the desired language from the list.
You can immediately upload a
JSON file
with a translation map for quick localization setup, or leave this step for later and gradually fill in the translations.
Since the JSON file I provided includes only a limited set of translation keys, the translation progress is currently at 5%.
As you continue adding more translations, the progress indicator will automatically increase.
The new language has been successfully added. You and your users can now use it as the interface language for your instance. Since the JSON file I provided includes only a limited set of translation keys, the translation progress is currently at 5%. As you continue adding more translations, the progress indicator will automatically increase.
You can modify or extend the translation for any language. To do this, click the “pencil” icon next to the language you want to edit.
In the top-right corner, you'll find a toggle to switch between basic and advanced settings:
Just below, you'll see a table with three columns:
A terminology key used to link a user interface element with its translation.
Input field for the key value in English. This value will be used as a fallback for all languages that don't have a specific translation for this key.
Input field for the key value in the selected language.
You'll see a table with three columns: The term key, which links an interface element to a translation; Input field for the key value in English. This value will be used as a fallback for all languages that don't have a specific translation for this key; Input field for the key value in the selected language.
Filters
Below the translation map, you'll find convenient filters to help you locate specific keys:
The “
Translated
” filter displays keys that already have a translation for the selected localization.
The “
Untranslated
” shows keys that are still missing translations.
The “
Customized
” filter highlights only the keys whose translations have been manually modified by the user.
The “
Added key
” shows the keys that were manually added to the localization file.
Adding new translation key
To add a new translation key, go to the translation map of the desired language and follow these steps:
Click the plus icon in the top-right corner.
A new row will appear in the table below. Fill in the fields with the appropriate values — enter the key, its English value, and the value for the selected language.
Then click anywhere outside the input field to apply the changes.
The newly created key will be added to every language in your language list. All of these languages will use the English value as the default key value unless you provide a custom translation.
Upload translation map from JSON file
You can upload a JSON file containing a translation map with keys and their corresponding translations.
This option is useful if you have a large number of translation keys, and creating them manually through the basic interface would be too time-consuming.
Go to the language editing menu.
Switch to the “Advanced” tab.
Insert translation map with keys and their corresponding translations in JSON format.
Click “Save”.
To add custom translations:
1.
In the title field of the interface element, instead of plain text, insert a key with the
i18n:
prefix wrapped in curly braces:
{i18n:custom.translation.key}
* where:
ㅤㅤ‐ i18n: - required prefix.
ㅤㅤ‐ custom.translation.key - the internationalization key that has been added to the translation map.
2. Then, add the corresponding value for this key in the selected language's translation map.
Always add translations for all required languages.
Avoid duplicate keys; use a structured hierarchy (e.g., custom.section.subsection).
Test how the key is displayed after switching the UI language.
Using custom translation in the dashboard
Let’s say you’re an English-speaking user who manages a dashboard that is accessed by clients from different countries.
To ensure that every user can easily understand the interface, the names of all components — including the dashboard title, widgets title, device names, data keys, and any other elements — should be displayed in the user's preferred language.
As an example, I'll apply a custom translation for German language to the previously listed elements of the “Weather” dashboard.
Of course, you can use any other language depending on your specific needs.
First, add the “Weather” dashboard to your instance:
To set a custom translation for the dashboard title, follow these steps:
Go to the “Custom translations” tab and open the translation map for the German language.
Click the “plus” icon in the top-right corner.
Enter the translation key for the dashboard title:
custom.weather-dashboard.title
Enter the translations for this key in English and German in the appropriate fields. You can find all the required values in the table below.
The key and its translations have been added. Now let's set this key as the dashboard title:
Navigate to the “Dashboards” page and open the “Weather” dashboard details.
Enter edit mode and replace the title field text with a key using the i18n structure: the i18n prefix followed by the translation key, wrapped in curly braces — like this:
{i18n:custom.weather-dashboard.title}
Save your changes.
Since I'm using English as my interface language, the dashboard title appears in English.
Now, either switch to your user's account where the interface language is set to German, or simply change your own interface language to German.
You should see the dashboard title displayed in German according to the translation map — which means everything is working as expected.
Custom translation for widget elements
Just like we did for the dashboard title, let's now apply internationalization to the “Temperature and Humidity history” widget title, telemetry keys, and axis labels.
Once again, to demonstrate the result, I'll use a user instance with German set as the interface language.
First, add the keys along with their corresponding values in English and the selected language (in our case German). Use the values provided in the table below.
custom.weather-dashboard.temperature-and-humidity-widget.title
Temperature and Humidity history
Temperatur- und Luftfeuchtigkeitsverlauf
Temperature and Humidity history widget title
custom.weather-dashboard.temperature.telemetry-key
Temperature
Temperatur
Temperature telemetry key name
custom.weather-dashboard.humidity.telemetry-key
Humidity
Feuchtigkeit
Humidity telemetry key name
Now go to the “Weather” dashboard and enter the “Temperature and Humidity history” widget edit mode.
Assign the added keys in the i18n structure to the following fields:
Title for the widget: {i18n:custom.weather-dashboard.temperature-and-humidity-widget.title}
After that, save your changes.
Using custom translation in HTML Value Card widget
Custom translations can be used in widget functions — for example, in the “HTML Value Card” widget. Let's take a look at one such example.
1.Add translation keys to the translation map of the selected language (in my case, German).
Open the dashboard in edit mode and click the “Add widget” button.
Select the “HTML Value Card” widget from the “Cards” widgets bundle.
Specify the device that sends temperature readings as the data source, along with the corresponding telemetry key.
Go to the “Appearance” tab. Use your own code or copy the one provided below and paste it into the “HTML” field.
The code syntax requires placing the i18n key in quotation marks.
Example of using custom translation in the “HTML Value Card” widget:
<script>vardescription=document.getElementsByClassName('description')[0];vartemperature=${temperature};if(temperature>=25){description.innerText="{i18n:custom.my-widget.telemetry-value.high-temperature}";}elseif(temperature<=19){description.innerText="{i18n:custom.my-widget.telemetry-value.low-temperature}";}else{description.innerText="{i18n:custom.my-widget.telemetry-value.normal-temperature}"</script><divclass='card'><divclass='content'><divclass='column'><h1>{i18n:custom.devices.smart-device.name}</h1><divclass='value'>
{i18n:custom.weather-dashboard.temperature-telemetry}: ${temperature:0} °C
<divclass='description'><imgheight="70px"src="http://icons.iconarchive.com/icons/iconsmind/outline/512/Temperature-icon.png"alt="Temperature icon">
Click “Add”.
Save the dashboard.
Using custom translation in the data post-processing function
Custom translations can be used in data post-processing functions.
Let's take a look at one such example.
1.Add translation keys to the translation map of the selected language (in my case, German).
Open the dashboard in edit mode and click the “Add widget” button.
Select the “Entities table” widget from the “Tables” widgets bundle.
Specify the device that sends temperature readings as the data source.
In the “Columns” section, the name column (which displays the device name) is already added by default. Now, add two more columns:
For the first one, add the telemetry key “temperature” to display the temperature value in degrees Celsius.
For the second one, also use the telemetry key “temperature”, but configure this column to show the temperature range instead of the raw value.
For both column labels, apply the appropriate i18n translation keys wrapped in curly braces:
