Skip to content

Introducing description placeholders for service action translations #2844

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 5 commits into
base: master
Choose a base branch
from
Draft

Introducing description placeholders for service action translations #2844

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
81dc571
Introducing description placeholders for service action translations
jbouwh Oct 22, 2025
e673464
placeholders
jbouwh Oct 22, 2025
46dfd26
Update custom action docs
jbouwh Oct 27, 2025
4b726f1
Typo
jbouwh Oct 27, 2025
f8283c7
Add link
jbouwh Oct 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions blog/2025-10-22-service-translation-placeholders.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 place holders 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Clarify terminology and destination for moving URLs.

Line 11 uses "service transaction," which is non-standard; services are not typically called "transactions." Additionally, the phrasing "moved out of...using" obscures where URLs should go. Revise to clarify that URLs belong in description placeholders.

-URLs that are part of the service transaction should be moved out of the service descriptions and translation strings using the description placeholders.
+Move URLs from service descriptions and translation strings into description placeholders.

This revision uses direct phrasing per documentation guidelines and clarifies the intended action.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
URLs that are part of the service transaction should be moved out of the service descriptions and translation strings using the description placeholders.
Move URLs from service descriptions and translation strings into description placeholders.
🤖 Prompt for AI Agents 
In blog/2025-10-22-service-translation-placeholders.md around line 11, update
the sentence that currently says "service transaction" and "moved out of the
service descriptions and translation strings using the description placeholders"
to be explicit and unambiguous: replace "service transaction" with "service
descriptions" (or "service definitions") and rewrite the clause to say that any
URLs must be placed in description placeholders (not embedded in service
descriptions or translation strings) and that translation strings should
reference those placeholders; make the phrasing direct and simple per
documentation guidelines.

4 changes: 3 additions & 1 deletion docs/core/integration-quality-scale/rules/action-setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion | 🟠 Major

Expand explanation to introduce what description placeholders are.

Line 25 introduces description placeholders but provides no context about their purpose. Readers will encounter the term before the code example and need to understand why they're useful (e.g., for translations and externalized configuration). Revise to be more informative.

-Optional description placeholders can be supplied.
+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.

Alternatively, combine the explanation with the code block introduction:

-Optional description placeholders can be supplied.
-
-`__init__py`:
```python {13-20} showLineNumbers
+`__init__py`:
+
+Use the `description_placeholders` parameter to supply translatable values, such as URLs:
+
```python {13-20} showLineNumbers

Either approach makes the feature's purpose clear before the code example.

🤖 Prompt for AI Agents 
docs/core/integration-quality-scale/rules/action-setup.md around line 25: the
phrase "Optional description placeholders can be supplied." is too terse and
lacks context; replace or expand it to briefly define what description
placeholders are (tokens used to supply translatable/externalized values into
action descriptions), state common use cases (e.g., translations, injecting URLs
or config values), and suggest where to pass them (e.g., via a
description_placeholders parameter) and why that matters; optionally merge this
explanation into the code-block introduction so readers see both the purpose and
an immediate example of using description_placeholders with translatable values
like URLs.


`__init__py`:
```python {13-19} showLineNumbers
```python {13-20} showLineNumbers
async def async_setup(hass: HomeAssistant, config: ConfigType) -> bool:
"""Set up my integration."""

Expand All @@ -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"}
)
```

Expand Down