Add developer documentation about translations for services (#1835)

Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>
This commit is contained in:
Franck Nijhof 2023-07-11 21:26:06 +02:00 committed by GitHub
parent c7a626ed29
commit f22fd1546d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 64 additions and 11 deletions

View File

@ -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.

View File

@ -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. |

View File

@ -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.