Introducing description placeholders for service action translations (#2844)

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: Martin Hjelmare <[email protected]>

Author: 3 people

blog/2025-11-27-service-translation-placeholders.md

@@ -0,0 +1,11 @@
+---
+author: Jan Bouwhuis
+authorURL: https://github.com/jbouwh
+authorImageURL: https://avatars.githubusercontent.com/u/7188918?s=96&v=4
+title: Introducing description placeholders for service action translations
+---
+It is now possible to use translation placeholders for (custom) service actions.
+
+The [service action example](/docs/core/integration-quality-scale/rules/action-setup?_highlight=hass.services.async_register#example-implementation) now shows how to supply the available description placeholders during the registration of the service action.
+
+Move URLs from service descriptions and translation strings into description placeholders.

docs/core/integration-quality-scale/rules/action-setup.md

@@ -22,9 +22,10 @@ The example below is a snippet where the service action is registered in the `as
 In this example, the service call requires a configuration entry id as parameter.
 This is used to first fetch the configuration entry, and then check if it is loaded.
 If the configuration entry does not exist or the configuration entry that we found is not loaded, we raise a relevant error which is shown to the user.
+Supply description placeholders to enable translation of service parameters, for example, to reference external resources like documentation URLs that need to be localized or updated independently of the service description.
 
 `__init__py`:
-```python {13-19} showLineNumbers
+```python {13-20} showLineNumbers
 async def async_setup(hass: HomeAssistant, config: ConfigType) -> bool:
     """Set up my integration."""
 
@@ -43,6 +44,7 @@ async def async_setup(hass: HomeAssistant, config: ConfigType) -> bool:
         async_get_schedule,
         schema=SERVICE_GET_SCHEDULE_SCHEMA,
         supports_response=SupportsResponse.ONLY,
+        description_placeholders={"example_url": "https://schedule.example.com"}
     )
 ```
 

docs/dev_101_services.md

@@ -143,7 +143,18 @@ set_speed:
 ```
 
 :::info
-The name and description of the service actions are set in our [translations](/docs/internationalization/core#services) and not in the service action description. Each service action and service action field must have a matching translation defined.
+The name and description of the service actions are set in our [translations](/docs/internationalization/core#services) and not in the service action description. Each service action and service action field must have a matching translation defined. Description placeholders allow you to exclude elements like URLs from translations.
+
+```python
+...
+    hass.services.async_register(
+      DOMAIN,
+      "hello", handle_hello,
+      description_placeholders={"docs_url": "https://example.com/hello_world"},
+    )
+...
+```
+
 :::
 
 ### Grouping of service action fields

docs/internationalization/core.md

@@ -183,6 +183,8 @@ each collapsible section of fields.
 Note that also the translations for `name` and `description` of fields which
 are displayed in a collapsible section should be under the `fields` key.
 
+Set description placeholders when the [service action is registered](/docs/dev_101_services/#service-action-description-example).
+
 ```json
 {
   "selector": {
@@ -198,7 +200,7 @@ are displayed in a collapsible section should be under the `fields` key.
   "services": {
     "set_speed": {
       "name": "Set speed",
-      "description": "Sets fan speed.",
+      "description": "Sets fan speed. [Learn more.]({docs_url})",
       "fields": {
         "speed": {
           "name": "Speed",