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 contains translations for different things that the integration offers that need to be translated.
|Title of the integration.|
|States of the integration, keyed by device class.|
|Translations for the config flow.|
|Translations for the options flow.|
|Translations for the device automations.|
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.
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.
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:
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:
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:
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:
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.