From 735b7c04b3639c9c96064a2b809b1c6bb692e8f9 Mon Sep 17 00:00:00 2001 From: Michael <35783820+mib1185@users.noreply.github.com> Date: Fri, 19 Jan 2024 15:28:18 +0100 Subject: [PATCH] Add placeholder for entity name translations (#1989) --- docs/core/entity.md | 29 +++++++++++++++-------------- docs/internationalization/core.md | 16 ++++++++++++++++ 2 files changed, 31 insertions(+), 14 deletions(-) diff --git a/docs/core/entity.md b/docs/core/entity.md index 4247df87..f23a98a8 100644 --- a/docs/core/entity.md +++ b/docs/core/entity.md @@ -69,20 +69,21 @@ Because these properties are always called when the state is written to the stat To avoid calculations in a property method, set the corresponding [entity class or instance attribute](#entity-class-or-instance-attributes), or if the values never change, use [entity descriptions](#entity-description). ::: -| Name | Type | Default | Description -| ----------------------- | ------------------------------| ------- | ----------- -| assumed_state | `bool` | `False` | Return `True` if the state is based on our assumption instead of reading it from the device. | -| attribution | str | None | `None` | The branding text required by the API provider. | -| available | `bool` | `True` | Indicate if Home Assistant is able to read the state and control the underlying device. | -| device_class | str | None | `None` | Extra classification of what the device is. Each domain specifies their own. Device classes can come with extra requirements for unit of measurement and supported features. | -| entity_picture | str | None | `None` | Url of a picture to show for the entity. | -| extra_state_attributes | dict | None | `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 | `bool` | `False` | Return `True` if the entity's `name` property represents the entity itself (required for new integrations). This is explained in more detail below. -| name | str | None | `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 | `bool` | `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). | -| state | str | int | float | None | `None` | The state of the entity. In most cases this is implemented by the domain base entity and should not be implemented by integrations. -| supported_features | int | None | `None` | Flag features supported by the entity. Domains specify their own. -| translation_key | str | None | `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). +| Name | Type | Default | Description +| ------------------------ | ------------------------------| ------- | ----------- +| assumed_state | `bool` | `False` | Return `True` if the state is based on our assumption instead of reading it from the device. +| attribution | str | None | `None` | The branding text required by the API provider. +| available | `bool` | `True` | Indicate if Home Assistant is able to read the state and control the underlying device. +| device_class | str | None | `None` | Extra classification of what the device is. Each domain specifies their own. Device classes can come with extra requirements for unit of measurement and supported features. +| entity_picture | str | None | `None` | Url of a picture to show for the entity. +| extra_state_attributes | dict | None | `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 | `bool` | `False` | Return `True` if the entity's `name` property represents the entity itself (required for new integrations). This is explained in more detail below. +| name | str | None | `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 | `bool` | `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). +| state | str | int | float | None | `None` | The state of the entity. In most cases this is implemented by the domain base entity and should not be implemented by integrations. +| supported_features | int | None | `None` | Flag features supported by the entity. Domains specify their own. +| translation_key | str | None | `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). +| translation_placeholders | dict | None | `None` | Placeholder definitions for [translated entity name](/docs/internationalization/core/#name-of-entities). :::warning It's allowed to change `device_class`, `supported_features` or any property included in a domain's `capability_attributes`. However, since these entity properties often are not expected to change at all and some entity consumers may not be able to update them at a free rate, we recommend only changing them when absolutely required and at a modest interval. diff --git a/docs/internationalization/core.md b/docs/internationalization/core.md index b605dce3..cb835253 100644 --- a/docs/internationalization/core.md +++ b/docs/internationalization/core.md @@ -231,6 +231,8 @@ If the entity's `translation_key` property is not `None` and the `entity` object 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. +It is also supported to use placeholders within the translation. If a placeholder is defined within the translation string, the entity's `translation_placeholders` property has to be set accordingly. + The following example `strings.json` is for a `sensor` entity with its `translation_key` property set to `thermostat_mode`: ```json { @@ -258,6 +260,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 `distance` and a placeholder `tracked_device`: + +```json +{ + "entity": { + "sensor": { + "distance": { + "name": "Distance of {tracked_device}" + } + } + } +} +``` + #### 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.