Backend Localization

Translation Strings

Platform translation strings are stored as JSON in the home-assistant repository. These files must be located adjacent to the component/platform they belong to. Components must have their own directory, and the file is simply named strings.json in that directory. For platforms, they are named strings.<platform name>.json in the platform directory. This file will contain the different strings that will be translatable.

strings.json

The strings.json contains translations for different things that the integration offers that need to be translated.

CategoryDescription
titleTitle of the integration.
stateStates of the integration, keyed by device class.
configTranslations for the config flow.
optionsTranslations for the options flow.
device_automationTranslations for the device automations.

Title

This category is just a string: the translation of the integration name. This key is optional and Home Assistant will fallback to the integration name if it is omitted. Only include this if it's not a product brand.

State

If your integration provides entities under it's domain, you will want to translate the states. You do this by offering a state dictionary, that contains translations for states with different device classes. The key _ is used for entities without a device class.

{
"state": {
"problem": {
"off": "OK",
"on": "Problem"
},
"safety": {
"off": "Safe",
"on": "Unsafe"
},
"_": {
"off": "[%key:common::state::off%]",
"on": "[%key:common::state::on%]"
}
}
}

Config / Options

The translation strings for the configuration flow handler are defined under the config key. An example strings file below describes the different supported keys:

{
"config": {
// Optional. Title to show in list. Only will be rendered if placeholders required
"flow_title": "Discovered Device ({host})",
"step": {
"init": {
// Optional. Will show the integration name if omitted
"title": "The user visible title of the `init` step.",
// Optional
"description": "Markdown that is shown with the step.",
"data": {
"api_key": "The label for the `api_key` input field"
}
}
},
"error": {
"invalid_api_key": "This message will be displayed if `invalid_api_key` is returned as a flow error."
},
"abort": {
"stale_api_key": "This message will be displayed if `stale_api_key` is returned as the abort reason."
}
}
}

strings.sensor.json

Integrations can provide translations for states of its entities under other integrations like sensor. To do this, the entity will need a custom device class that starts with <domain>__<custom name>. You can then provide translations that will only be applied for your entity. Note that you cannot customize your translation when you use an official device class. Those are standardized.

To differentiate entities and their translations, provide different device classes. The following example strings.sensor.json is for a Moon sensor entity with the moon__phase device class:

{
"state": {
"moon__phase": {
"new_moon": "New moon",
"first_quarter": "First quarter",
"full_moon": "Full moon",
"last_quarter": "Last quarter"
}
}
}

Test translations

In order to test changes to translation files, the translation strings must be compiled into Home Assistant’s translation directories by running the following script:

python3 -m script.translations develop

Introducing new strings

To introduce new strings, add them to strings.json or to a platform strings file. Try to use as many references to common strings as possible. Common strings live in homeassistant/strings.json. You can refer to those translations using references. For example:

{
"config": {
"abort": {
"already_configured": "[%key:common::config_flow::abort::already_configured_device%]"
}
}
}

After the pull request with the strings file is merged into the dev branch, the strings will be automatically uploaded to Lokalise, where contributors can submit translations. The translated strings in Lokalise will be periodically pulled in to the core repository.

Last updated on