Introducing description placeholders for service action translations #2844
Conversation
📝 WalkthroughWalkthroughAdds a blog post announcing translation-placeholder support for service action descriptions and updates documentation to show how to supply optional Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro Cache: Disabled due to data retention organization setting Knowledge base: Disabled due to data retention organization setting 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge base: Disabled due to data retention organization setting
📒 Files selected for processing (2)
blog/2025-10-22-service-translation-placeholders.md(1 hunks)docs/core/integration-quality-scale/rules/action-setup.md(2 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
*/**(html|markdown|md)
⚙️ CodeRabbit configuration file
*/**(html|markdown|md): - For instructional content in documentation, use a direct and authoritative tone. Avoid expressions of politeness such as 'may' or 'please', and ensure the goal of the instruction is fronted.
- Apply the Microsoft Style Guide to ensure documentation maintains clarity and conciseness.
- In step-by-step instructions, front the location phrase in the instructional sentence.
- In step-by-step instructions, front the 'goal' in the instructional sentence.
- In step-by-step instructions, if in doubt what to front, front the 'goal' before the location phrase in the instructional sentence.
- do not hyphenate terms like 'top-right' or 'bottom-left' with 'corner'
*/**(html|markdown|md): - Use bold to mark UI strings.
If "" are used to mark UI strings, replace them by bold.
Be brief in your replies and don't add fluff like "thank you for..." and "Please let me know if"
Use sentence-style capitalization also in headings.
do not comment on HTML used for icons
Avoid flagging inline HTML for embedding videos in future reviews for this repository.
Files:
blog/2025-10-22-service-translation-placeholders.md
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: Redirect rules - developers-home-assistant
- GitHub Check: Header rules - developers-home-assistant
- GitHub Check: Pages changed - developers-home-assistant
🔇 Additional comments (2)
blog/2025-10-22-service-translation-placeholders.md (1)
1-6: Front matter structure is correct.docs/core/integration-quality-scale/rules/action-setup.md (1)
28-28: Code example correctly demonstrates the new parameter.The code block range update and new
description_placeholdersparameter are correctly placed and formatted. The example with{"example_url": "https://schedule.example.com"}provides clear, realistic guidance.Also applies to: 47-47
|
|
||
| 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. |
There was a problem hiding this comment.
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.
| 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.
| 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. |
There was a problem hiding this comment.
🛠️ 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} showLineNumbersEither 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.
1 participant
Proposed change
Introducing description placeholders for service action translations.
Blog post added
Type of change
Checklist
Additional information
Summary by CodeRabbit