mirror of
https://github.com/home-assistant/developers.home-assistant.git
synced 2025-07-24 17:56:31 +00:00
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
GitHub
parent
c7a626ed29
commit
f22fd1546d
17
blog/2023-07-11-translating-services.md
Normal file
17
blog/2023-07-11-translating-services.md
Normal 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.
|
||||
@ -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. |
|
||||
|
||||
@ -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.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user