From f22fd1546df565756a2fef394c3cbd6e93bf725d Mon Sep 17 00:00:00 2001 From: Franck Nijhof Date: Tue, 11 Jul 2023 21:26:06 +0200 Subject: [PATCH] Add developer documentation about translations for services (#1835) Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com> --- blog/2023-07-11-translating-services.md | 17 +++++++++++ docs/dev_101_services.md | 19 +++++------- docs/internationalization/core.md | 39 +++++++++++++++++++++++++ 3 files changed, 64 insertions(+), 11 deletions(-) create mode 100644 blog/2023-07-11-translating-services.md diff --git a/blog/2023-07-11-translating-services.md b/blog/2023-07-11-translating-services.md new file mode 100644 index 00000000..86c58cb8 --- /dev/null +++ b/blog/2023-07-11-translating-services.md @@ -0,0 +1,17 @@ +--- +author: Franck Nijhof +authorURL: https://twitter.com/frenck +authorImageURL: /img/profile/frenck.png +authorTwitter: frenck +title: Translating services +--- + +We now support translating services in Home Assistant. Previously, the names & descriptions of services and their service fields have been hardcoded into the `services.yaml` files of each integration. + +We have now added support for translating these names & descriptions using our translation system. This means that the names & descriptions of services and their service fields can now be translated into any language. + +To achieve this, the `name` and `description` keys from each service and service field moves from the hardcoded `services.yaml` files to the translation files of each integration. + +An updated example of a `services.yaml` service description can be [found in our documentation](/docs/dev_101_services#service-descriptions). The [backend localization](/docs/internationalization/core#services) has been extended to have an example of a translated service, matching the example from the service description. + +The services translation is available as of Home Assistant 2023.8. We hope this will make Home Assistant more accessible to non-English users. diff --git a/docs/dev_101_services.md b/docs/dev_101_services.md index db51d17b..03214bd6 100644 --- a/docs/dev_101_services.md +++ b/docs/dev_101_services.md @@ -73,10 +73,6 @@ Services are published under the domain name of your integration, so in `service # Service ID set_speed: - # Service name as shown in UI - name: Set speed - # Description of the service - description: Sets fan speed. # If the service accepts entity IDs, target allows the user to specify entities by # entity, device, or area. If `target` is specified, `entity_id` should not be # defined in the `fields` map. By default it shows only targets matching entities @@ -103,10 +99,6 @@ set_speed: fields: # Key of the field speed: - # Field name as shown in UI - name: Speed - # Description of the field - description: Speed setting # Whether or not field is required (default = false) required: true # Advanced fields are only shown when the advanced mode is enabled for the user @@ -120,6 +112,7 @@ set_speed: # the input UI for this field selector: select: + translation_key: "fan_speed" options: - "off" - "low" @@ -127,6 +120,10 @@ set_speed: - "high" ``` +:::info +The name and description of the services are set in our [translations](/docs/internationalization/core#services) and not in the service description. Each service and service field must have a matching translation defined. +::: + ### Filtering service fields In some cases, entities from a service's domain may not support all service fields. By @@ -260,7 +257,7 @@ The use of response data is meant for cases that do not fit the Home Assistant s Service calls are registered with a `SupportsResponse` value to indicate response data is supported. -| Value | Description | -| ---------- | -------------------------------------------- | +| Value | Description | +| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `OPTIONAL` | The service performs an action and can optionally return response data. The service should conditionally check the `ServiceCall` property `return_response` to decide whether or not response data should be returned, or `None`. | -| `ONLY` | The service doesn't perform any actions and always returns response data. | +| `ONLY` | The service doesn't perform any actions and always returns response data. | diff --git a/docs/internationalization/core.md b/docs/internationalization/core.md index c31baaa9..d93de951 100644 --- a/docs/internationalization/core.md +++ b/docs/internationalization/core.md @@ -16,6 +16,7 @@ The `strings.json` contains translations for different things that the integrati | `issues` | Translations for repairs issues. | | `options` | Translations for the options flow. | | `selectors` | Selectors of the integration. | +| `services` | Services of the integration. | | `state` | States of the integration, keyed by device class. | ### Title @@ -91,6 +92,44 @@ The translation for selectors are defined under the `selector` key. It supports ``` +### Services + +The translations of service strings are defined under the `services` key. + +It supports translating the `name` and `description` of each service, +and the `name` and `description` of each service's `fields`. + +```json +{ + "selector": { + "fan_speed": { + "options": { + "high": "High", + "low": "Low", + "medium": "Medium", + "off": "Off", + } + } + }, + "services": { + "set_speed": { + "name": "Set speed", + "description": "Sets fan speed.", + "fields": { + "speed": { + "name": "Speed", + "description": "The speed to set." + } + } + } + } +} +``` + +:::note +Services may use selectors in their `fields`. The translation of those selectors can be provided using the `translation_key` property on the selector definition in the services.yaml file. See the [Selectors](#selectors) section and the [Service description](/docs/dev_101_services.md#service-descriptions) page for more information. +::: + ### Device automations The translation strings for device automations are defined under the `device_automation` key. An example strings file below describes the different supported keys.