From dab13a943247cb661f6d130ea446bb7096f20df8 Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Mon, 27 Mar 2023 10:37:36 +0200 Subject: [PATCH] Add blog post about translatable entity names + improve docs (#1726) Co-authored-by: Franck Nijhof --- blog/2022-03-23-entity_name_translations.md | 81 +++++++++++++++++++++ docs/core/entity.md | 2 +- docs/internationalization/core.md | 20 ++++- 3 files changed, 98 insertions(+), 5 deletions(-) create mode 100644 blog/2022-03-23-entity_name_translations.md diff --git a/blog/2022-03-23-entity_name_translations.md b/blog/2022-03-23-entity_name_translations.md new file mode 100644 index 00000000..2450cf20 --- /dev/null +++ b/blog/2022-03-23-entity_name_translations.md @@ -0,0 +1,81 @@ +--- +author: Erik Montnemery +authorURL: https://github.com/emontnemery +title: "Translating the name and attributes of entities" +--- + +It's now possible to translate the name of entities, and this is preferred over hard coding a name in natural language in the Python implementation. Also, entity components provide shared translations, for example, for binary sensor device classes, which should be used to avoid translating the same thing multiple times. + +Also, the frontend now has full support for translated entity state attributes for both the names and their values. + + +:::warning +Pointing to translations via the `translation_key` property is currently only supported for entities with a `unique_id`. + +Additionally, translating entity names requires that the `has_entity_name` property is set to `True`. +::: + +## Translating entity name +The following example `strings.json` is for a `sensor` entity with its `translation_key` property set to `thermostat_mode`: + +```json +{ + "entity": { + "sensor": { + "thermostat_mode": { + "name": "Thermostat mode" + } + } + } +} +``` + +The following example `strings.json` is for a `sensor` entity with its `translation_key` property set to `temperature_sensor` where a shared translation provided by the `sensor` integration is used: + +```json +{ + "entity": { + "sensor": { + "temperature_sensor": { + "name": "[%key:component::sensor::entity_component::temperature::name%]" + } + } + } +} +``` + +## Translating entity attributes +The following example `strings.json` is for a `demo` domain `climate` entity with its `translation_key` property set to `ubercool`, which has custom `fan_mode` and `swing_mode` settings: + + +```json +{ + "entity": { + "climate": { + "ubercool": { + "state_attributes": { + "fan_mode": { + "state": { + "auto_high": "Auto High", + "auto_low": "Auto Low", + "on_high": "On High", + "on_low": "On Low" + } + }, + "swing_mode": { + "state": { + "1": "1", + "2": "2", + "3": "3", + "auto": "Auto", + "off": "Off" + } + } + } + } + } + } +} +``` + +For more details, see the [`entity name translation`](/docs/internationalization/core/#name-of-entities) [`entity attribute translation`](/docs/internationalization/core#entity-state-attributes) and [`entity`](/docs/core/entity#generic-properties) documentation. diff --git a/docs/core/entity.md b/docs/core/entity.md index c9030e8d..f3fc4108 100644 --- a/docs/core/entity.md +++ b/docs/core/entity.md @@ -74,7 +74,7 @@ Properties should always only return information from memory and not do I/O (lik | entity_picture | URL | `None` | Url of a picture to show for the entity. | | extra_state_attributes | dict | `None` | Extra information to store in the state machine. It needs to be information that further explains the state, it should not be static information like firmware version. | | has_entity_name | boolean | | Return `True` if the entity's `name` property represents the entity itself (required for new integrations). This is explained in more detail below. -| name | string | `None` | Name of the entity | +| name | string | `None` | Name of the entity. Avoid hard coding a natural language name, use a [translated name](/docs/internationalization/core/#name-of-entities) instead. | | should_poll | boolean | `True` | Should Home Assistant check with the entity for an updated state. If set to `False`, entity will need to notify Home Assistant of new updates by calling one of the [schedule update methods](integration_fetching_data.md#push-vs-poll). | | translation_key | string | `None` | A key for looking up translations of the entity's state in [`entity` section of the integration's `strings.json`](/docs/internationalization/core#state-of-entities). | unique_id | string | `None` | A unique identifier for this entity. Needs to be unique within a platform (ie `light.hue`). Should not be configurable by the user or be changeable. [Learn more.](entity_registry_index.md#unique-id-requirements) | diff --git a/docs/internationalization/core.md b/docs/internationalization/core.md index 5dab55f5..39bbc516 100644 --- a/docs/internationalization/core.md +++ b/docs/internationalization/core.md @@ -153,6 +153,8 @@ The translation strings for repairs issues are defined under the `issues` key. A Integrations can provide translations for names of its entities. To do this, provide an `entity` object, that contains translations of the names and set the entity's `translation_key` property to a key under a domain in the `entity` object. If the entity's `translation_key` property is not `None` and the `entity` object provides a translated name, `EntityDescription.name` will be ignored. +Entity components, like `sensor`, already have existing translations available that can be reused by referencing those. This includes common translations for entity names based on a device class. For example, it already has translations available for a "Temperature" sensor that can be referenced. Referencing existing translations is preferred, as it prevents translating the same thing multiple times. + The following example `strings.json` is for a `sensor` entity with its `translation_key` property set to `thermostat_mode`: ```json { @@ -166,6 +168,20 @@ The following example `strings.json` is for a `sensor` entity with its `translat } ``` +The following example `strings.json` is for a `sensor` entity with its `translation_key` property set to `temperature_sensor` where a shared translation provided by the `sensor` integration is used: + +```json +{ + "entity": { + "sensor": { + "temperature_sensor": { + "name": "[%key:component::sensor::entity_component::temperature::name%]" + } + } + } +} +``` + #### State of entities Integrations can provide translations for states of its entities under other integrations like sensor if the base entity component does not provide translations, or if the translation provided by the base entity component do not match the integration's entity. To do this, provide an `entity` object, that contains translations for states and set the entity's `translation_key` property to a key under a domain in the `entity` object. @@ -214,10 +230,6 @@ If your integration provides entities under its domain, you will want to transla #### Entity state attributes -:::info -Translation of entity state attributes also requires frontend support, which is currently only available for `climate` entities. -::: - Integrations can provide translations for its entities' state attributes under other integrations like sensor if the base entity component does not provide translations, or if the translation provided by the base entity component do not match the integration's entity. To do this, provide an `entity` object, that contains translations for entity state attributes and set the entity's `translation_key` property to a key under a domain in the `entity` object. To differentiate entities and their translations, provide different translation keys. The following example `strings.json` is for a `demo` domain `climate` entity with its `translation_key` property set to `ubercool`, which has custom `fan_mode` and `swing_mode` settings: