translations
Skill81 starsChanged 4 days agoMITView on GitHub
User-facing strings in translations/en.json — sensor and device display names and their naming patterns, entity translation keys and placeholders, config flow labels and errors, exception and repair issue messages, and the translation tests that require every used key and no unused ones. Use when adding, renaming, or removing any user-visible string, entity name, or output sensor, or when a translation test fails.
8 other projects use a version of this.
Adopted by
Most recently taken up by
- wikilayer/skillstheir own version, first seen Nov 13, 2026
- craftcms/cmstheir own version, first seen Nov 9, 2026
- WaniWani-AI/sdktheir own version, first seen Nov 8, 2026
- simonmichael/hledgertheir own version, first seen Oct 17, 2026
- zapek/Xerestheir own version, first seen Oct 8, 2026
- jtenniswood/espcontroltheir own version, first seen Oct 8, 2026
Other versions8 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 8
- simonmichael/hledger★ 4.8ksame name
- HiEventsDev/Hi.Events★ 4.2ksame name
- craftcms/cms★ 3.6ksame name
- jtenniswood/espcontrol★ 1.2ksame name
- zapek/Xeres★ 224same name
- WaniWani-AI/sdk★ 18same name
- wikilayer/skills★ 2same name
- MovGP0/Skills★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository18 other files it gives its agents.
- AGENTS.mdAGENTS.md
- agent-setupSkill
- config-flowSkill
- coverageSkill
- documentationSkill
- elementsSkill
- explain-planSkill
- integrationSkill
- lintSkill
- manifestSkill
- modelSkill
- performanceSkill
- pythonSkill
- release-notesSkill
- scenariosSkill
- testingSkill
- update-docsSkill
- update-versionSkill
The file
We split this skill into the rules it gives an agent
11 rules. 0 are common, 8 are distinctive, and 3 are very specific to this project.
0
Common
Most of the 8 edited versions we read keep these.
8
Distinctive
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
Clarity: Write for non-native English speakers
- Distinctive: line 16
Abbreviations: Avoid when possible
- Distinctive: line 20
Use backticks for: file paths, filenames, variable names, field entries
- Very specific: line 26
Read an existing entry in en.json for the shape of each, for example:
- Distinctive: line 71
Delete a string in the same change that stops using it.
- Distinctive: line 82
All repair issues must be actionable:
- Distinctive: line 94
Use translation keys for entity names:
- Distinctive: line 107
Use translation keys for user-facing exceptions:
- Distinctive: line 157
Do not use parentheses, brackets, or other special characters in display names.
- Very specific: line 179
Every entity of an element gets its placeholders from build_translation_placeholders() in entities/translation_placeholders.py.
- Very specific: line 180
Every configured field is available by its name, including fields inside sections, and name defaults to the element's title.
“Common” is measured: kept by at least 6 in 10 of the 8 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Translation and user-facing text
HAEO uses translations/en.json as a custom integration (not strings.json like core integrations).
Writing style
- Tone: Friendly and informative
- Perspective: Second person ("you" and "your")
- Clarity: Write for non-native English speakers
- Case: Sentence case for all titles and messages
- Abbreviations: Avoid when possible
Formatting in messages
- Use backticks for: file paths, filenames, variable names, field entries
- Example: "Check the
config.jsonfile"
en.json structure
The top-level groups are config (hub flow), options (hub options flow), config_subentries (one group per element type and the network), device, entity, exceptions, issues, selector, services, and common (strings HAEO reads itself).
Read an existing entry in en.json for the shape of each, for example:
{
"config_subentries": {
"grid": {
"step": {
"user": {
"title": "Grid configuration",
"data": {
"connection": "Connection",
"name": "Grid name"
},
"sections": {
"pricing": {
"name": "Pricing",
"data": {
"price_source_target": "Import price",
"price_target_source": "Export price"
}
}
}
}
},
"error": {
"name_exists": "A device with this name already exists"
}
}
},
"exceptions": {
"optimization_failed": {
"message": "The optimization failed: {error}"
}
}
}An element flow's name and connection labels sit in the step's top-level data, because those fields are outside every section.
Labels for sectioned fields sit under sections.{section}.data.
Checking translations
These checks keep en.json and the code in step, and all fail CI:
test_translations_match_used_keysintranslations/tests/test_translations.pyrequires every key the integration uses to be present, and every key present to be used. Delete a string in the same change that stops using it.- The pytest plugin
translations/tests/runtime_checks.pyruns in every test. It fails a test that shows a flow form, abort, repair issue, translated error, entity name, or enum state whose string or placeholderen.jsonlacks. translations/tests/flow_messages.pyreads each flow's code to find the errors, aborts, and steps itsasync_step_*methods can reach, so the translation tests require strings for exactly those.
So tests must use real translation keys, never placeholders such as "test_error".
Repair issues
All repair issues must be actionable:
- Clearly explain what is happening
- Provide specific steps to resolve (numbered list)
- Include relevant context (device names, error details)
- Explain what to expect after following the steps
❌ Bad: "Update firmware" ✅ Good: "Your device firmware version {version} is outdated. To update: 1) Open the manufacturer's app, 2) Navigate to device settings, 3) Select 'Update Firmware'."
Entity translations
Use translation keys for entity names:
class MySensor(SensorEntity):
_attr_has_entity_name = True
_attr_translation_key = "battery_power_charge"Output sensors use the output name as their translation key.
Input entities use {element_type}_{field_name}, which elements/field_hints.py builds from the schema.
Exception translations
Use translation keys for user-facing exceptions:
raise HomeAssistantError(
translation_domain=DOMAIN,
translation_key="input_unavailable",
translation_placeholders={"field": field, "element": element, "entities": entities},
)Icons
Icons live in icons.json, not en.json.
Sensor naming conventions
HAEO uses consistent patterns for sensor translation display names. These patterns affect both the UI display and the generated entity IDs.
Translation key patterns (entity_id generation)
Output names, and so translation keys, use subject-first ordering with an element prefix: {element}_{property}_{qualifier}, such as battery_power_charge, grid_power_import, and battery_state_of_charge.
Display name patterns (UI strings)
Display names follow these patterns for consistency, using sentence case (capital first letter, rest lowercase):
Power sensors: Action + noun pattern
- ✓ Correct: "Import power", "Export power", "Charge power", "Discharge power", "Active power"
- ✗ Incorrect: "Power import", "Power export", "Power charge", "Power active"
- Qualified variants: "{Qualifier} {action} power" (e.g., "Max charge power", "Max discharge power")
Price entities: Qualifier + price pattern
- ✓ Correct: "Import price", "Export price", "Shortfall price"
- ✗ Incorrect: "Price (Import)", "Price import"
Shadow price sensors: Constraint description + "shadow price"
- ✓ Correct: "Max import power shadow price", "Power balance shadow price", "SOC max shadow price"
- ✗ Incorrect: "Max Import Price (Shadow)", "Shadow Price (Max Import)"
- Pattern emphasizes "shadow price" as the subject being described
State/status sensors: Noun phrase
- "State of charge", "Energy stored", "Status"
Avoid special characters
Do not use parentheses, brackets, or other special characters in display names. These characters can interfere with entity ID generation and cause issues.
❌ Bad: "Power (Source to Target)", "Max Import Price (Shadow)" ✅ Good: "{source} to {target} power", "Max import power shadow price"
Parameterized translations
Connection sensors use {source} and {target} placeholders to display the names of the elements they join:
{
"entity": {
"sensor": {
"connection_power": {
"name": "{source} to {target} power"
}
}
}
}Every entity of an element gets its placeholders from build_translation_placeholders() in entities/translation_placeholders.py.
Every configured field is available by its name, including fields inside sections, and name defaults to the element's title.
Parameterize a string with these placeholders rather than writing one string per element type.
Home Assistant entity naming requirements
HAEO follows Home Assistant's entity naming conventions:
Required properties
has_entity_name = True- Required for all new integrationstranslation_key- Used to look up translated entity namestranslation_placeholders- Optional dict for parameterized translations
Entity name composition
Home Assistant generates friendly_name by combining device and entity names:
- Entity not in device:
friendly_name = entity.name - Entity in device with name:
friendly_name = f"{device.name} {entity.name}" - Entity in device with
name=None:friendly_name = device.name
Capitalization
Entity names should start with a capital letter, rest lowercase (unless proper noun or abbreviation):
- ✓ Correct: "Import power", "State of charge", "SOC max shadow price"
- ✗ Incorrect: "Import Power", "STATE OF CHARGE"
Documentation references
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

