Add developer documentation about translations for services

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.

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,13 +112,18 @@ set_speed:
       # the input UI for this field
       selector:
         select:
+          translation_key: "fan_speed"
           options:
             - "off"
             - "low"
             - "medium"
             - "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.                                                                                                                                                         |

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.