Introducing description placeholders for service action translations

blog/2025-10-22-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.
+
+URLs that are part of the service transaction should be moved out of the service descriptions and translation strings using the 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.
+Optional description placeholders can be supplied.
 
 `__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"}
     )
 ```