ha-translations
Add or fix user-facing strings for this Home Assistant custom integration — translations/en.json and other languages, icons.json, entity names and states, config flow labels and errors, service action descriptions, exception messages, and repair issue text. Use when asked to "update translations", "add a translation key", "translate", "fix the entity name", "add strings for the new sensor/action/option", "add icons", or when hassfest reports a missing or unused translation key. Covers the key structure, which keys each feature needs, placeholders, the icons.json contract, and the project's strict rule about only touching en.json. SYMPTOMS — load this if you are about to: write user-facing English into Python; edit a language file other than `en.json`; add an entity without its `entity.<platform>.<key>.name` key; skip `data_description` on a config flow field; or set `icon=` instead of using `icons.json`.
- License 许可
- MIT
- 所属仓库
- amg0/ha_ksenia
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- ha-translations
- description
- Add or fix user-facing strings for this Home Assistant custom integration — translations/en.json and other languages, icons.json, entity names and states, config flow labels and errors, service action descriptions, exception messages, and repair issue text. Use when asked to "update translations", "add a translation key", "translate", "fix the entity name", "add strings for the new sensor/action/option", "add icons", or when hassfest reports a missing or unused translation key. Covers the key structure, which keys each feature needs, placeholders, the icons.json contract, and the project's strict rule about only touching en.json. SYMPTOMS — load this if you are about to: write user-facing English into Python; edit a language file other than `en.json`; add an entity without its `entity.<platform>.<key>.name` key; skip `data_description` on a config flow field; or set `icon=` instead of using `icons.json`.
03 SKILL.md 正文
Translations and icons
translations/en.json is the source of truth for every string a user sees. Home Assistant falls back to the raw key
when a string is missing, so a missing key is a visible bug, not a cosmetic one.
Read blueprint.translations.instructions.md
first — it holds the rules: placeholder syntax and the single-quote trap that breaks hassfest, why [%key:…%] and
strings.json must never appear here, what hassfest rejects in a string, entity translation requirements, which fields
accept Markdown, proper nouns, the form of address per language, cross-language structure, and the UI text style.
This skill is which keys a given change needs, and how to write them.
The project rule on languages
- Update
en.jsononly. Never edit or create other language files on your own initiative — translations are contributed through the project's translation workflow, and machine-translating them creates churn no maintainer asked for. - If the developer explicitly asks for another language, confirm which files before starting.
- During feature work, business logic comes first. Use the translation key in code immediately, and fill in
en.jsoneither when asked or when the feature is complete.
Key structure
{
"config": {
"step": {
"user": {
"title": "…",
"description": "…",
"data": { "host": "Host" },
"data_description": { "host": "The hostname or IP address of the device." }
}
},
"error": { "cannot_connect": "…", "invalid_auth": "…", "unknown": "…" },
"abort": { "already_configured": "…" }
},
"options": { "step": { "init": { "data": {}, "data_description": {} } } },
"entity": { "sensor": { "pm25": { "name": "PM2.5", "state": {} } } },
"services": { "set_target_value": { "name": "…", "description": "…", "fields": {} } },
"exceptions": { "set_target_value_failed": { "message": "…" } },
"issues": { "deprecated_api_endpoint": { "title": "…", "description": "…" } },
"selector": { "mode": { "options": { "auto": "Automatic" }, "unit_of_measurement": "seconds" } },
"config_subentries": { "device": { "step": { "user": { "data": {} } } } },
"device": { "gateway": { "name": "…" } },
"system_health": { "info": { "api_endpoint": "…" } }
}
config also takes flow_title, progress and create_entry alongside step. Subentry strings live under
config_subentries.<type>, never under config.
Which keys does my change need?
| You added… | Keys required |
|---|---|
An entity with a translation_key |
entity.<platform>.<translation_key>.name |
An enum sensor or a select |
…plus entity.<platform>.<key>.state.<value> for every possible value |
| An entity attribute | entity.<platform>.<key>.state_attributes.<attr>.name (and .state for enum attributes) |
| A config flow field | config.step.<step>.data.<field> and config.step.<step>.data_description.<field> |
A new errors["base"] = "x" |
config.error.x |
A new async_abort(reason="x") |
config.abort.x |
| An options flow field | options.step.init.data.<field> and options.step.init.data_description.<field> |
| A service action | services.<action>.name, .description, .fields.<field>.name, .fields.<field>.description |
A raised HomeAssistantError |
exceptions.<translation_key>.message |
| A repair issue | issues.<issue_id>.title, plus either .description or .fix_flow.* — never both |
| A config subentry flow | config_subentries.<type>.step.<step>.…, mirroring the config shape |
| A config subentry type | …plus config_subentries.<type>.entry_type and .initiate_flow.user (both required) |
| A form section | step.<step>.sections.<section>.name and .description; its fields in the section's data |
| A menu step | step.<step>.menu_options.<option> |
| A custom submit button label | step.<step>.submit |
| A unit that is a word ("steps") | entity.<platform>.<key>.unit_of_measurement — and no native_unit_of_measurement |
| A trigger or condition | triggers.<id> / conditions.<id>: .name, .description, .fields.<field>.name |
A system_health value |
system_health.info.<key> |
A repair issue may also carry an optional short_title. How to name triggers and conditions:
triggers-conditions.md.
Two rules that catch most mistakes:
namevs.data. Entity names live underentity.*.name; form field labels live understep.*.data.*. They are not interchangeable.data_descriptionis not optional in practice. It is the small helper text under a field, and its absence is what makes a setup form feel unfinished.
Abort reasons Home Assistant translates itself
These carry their own text, so they need no config.abort key — but only when Home Assistant raises them. A flow that
calls async_abort(reason=…) with one of them itself passes translation_domain="homeassistant" or keeps its own key.
| Reason | Raised by |
|---|---|
reauth_successful, reconfigure_successful |
async_update_reload_and_abort() / async_update_and_abort() when reason is omitted |
already_in_progress |
async_set_unique_id() |
single_instance_allowed |
the single_config_entry manifest check |
no_devices_found |
the DiscoveryFlowHandler helper in config_entry_flow |
AbstractOAuth2FlowHandler adds authorize_url_timeout, missing_credentials, no_url_available, oauth_error,
oauth_failed, oauth_implementation_unavailable, oauth_timeout, oauth_unauthorized and
user_rejected_authorize — for any async_abort on it without a translation_domain, including your own.
already_configured is not one of them — it needs a key. Neither is the OAuth2 handler's missing_configuration.
Raising a translated exception
The pattern that ties Python to the JSON — every {placeholder} in the string must be supplied at the call site, and
vice versa (hassfest checks both):
{ "exceptions": { "set_target_value_failed": { "message": "Could not set the value: {error}" } } }
raise HomeAssistantError(
translation_domain=DOMAIN,
translation_key="set_target_value_failed",
translation_placeholders={"error": str(err)},
)
Writing the strings
- The style rules — sentence case, "you", the glossary's terms and the retired names to avoid — are in the instructions file. Proper nouns and capitalised abbreviations keep their casing.
- Keys are
snake_case— including translated state values and state attributes. Only the values are prose. - No trailing period on
nameanddatalabels; full sentences with a period fordescriptionanddata_description. - Do not repeat the device or integration name in an entity name —
_attr_has_entity_name = Truemeans Home Assistant prefixes it already. "Temperature", not "Blueprint device temperature". - Error messages say what happened and what to do, and never leak credentials, tokens, or raw stack traces.
- Match the wording Home Assistant uses for the same situation rather than inventing a variant — Core's shared strings.
- Use the word the project already settled on. If
docs/development/GLOSSARY.mdexists it decides the wording here, because renaming an entity later is a breaking change (ha-grillis where those terms are agreed).
icons.json
Entity icons belong in custom_components/<domain>/icons.json, not in EntityDescription(icon=...).
Do not give an entity an icon its device class already provides. A PM2.5 sensor, a temperature sensor, a battery sensor are all iconed correctly by Home Assistant; overriding them makes the integration look inconsistent with every other one. Add an icon where there is no device class, or where the context genuinely differs from it.
Beyond a plain icon, a key can carry:
range— pick by value:{"0": "mdi:battery-outline", "10": "mdi:battery-10", …}, ascending, and the icon chosen is the highest bound less than or equal to the current value.defaultcovers unavailable or unparseable states. If a key defines bothstateandrange,statewins.state_attributes— icons per attribute value, for things like a climate preset or a fan mode. Only attributes, not arbitrary keys.
{
"entity": {
"sensor": {
"pm25": { "default": "mdi:air-filter" },
"mode": { "default": "mdi:cog", "state": { "auto": "mdi:autorenew", "off": "mdi:power-off" } }
}
},
"services": {
"set_target_value": { "service": "mdi:target" }
}
}
Note the nesting: a service icon is {"service": "mdi:…"}, not a bare string. Sections get their own icons under
"sections".
Prefer a device_class over an icon whenever one fits — device classes give correct icons, unit conversion, and
assistant behaviour for free.
Validate
script/hassfest # the authoritative check: missing keys, unused keys, bad placeholders
script/lint # Prettier formats the JSON (2 spaces, no trailing commas)
Then restart Home Assistant and look at the actual UI — hassfest verifies structure, not whether the text reads well.
Do not
- Do not add keys "for later" — hassfest flags unused keys.
- Do not reformat the whole file while adding one key; keep the diff small and the ordering as it is.
- Do not translate
keyvalues, entity IDs, or anything that ends up in an automation.
The remaining rules are in
blueprint.translations.instructions.md.
04 同仓库更多 Skills
issues
Triage/fix the GitHub issue backlog via branch + PR, with auto-merge on green CI for this session.
ha-testing
Write, fix, or extend automated tests for this Home Assistant custom integration using pytest and pytest-homeassistant-custom-component. Use when asked to "add tests", "write a test", "the tests fail", "improve coverage", "add a regression test", "test the config flow", "update snapshots", or when a behavioural change needs verification before it can be called done. Covers the tests/ layout, the conftest.py fixtures this project needs, mocking the API client, config flow and entity test patterns, registry assertions, syrupy snapshots, freezing time, and the script/test commands. SYMPTOMS — load this if you are about to: instantiate an entity class directly instead of asserting on `hass.states`; write a test without `enable_custom_integrations`; use `time.sleep` instead of `async_fire_time_changed`; silence a DeprecationWarning to make the suite pass; or commit a snapshot you have not read.
ha-service-action
Add, change, or remove a Home Assistant service action (also called a "service" or "action") in this custom integration. Use when asked to "add a service", "add an action", "expose X as a service call", "add a service that returns data", "make this callable from an automation", or when editing services.yaml, the service_actions/ package, service schemas, service response data, or the async_setup() registration. Covers the services.yaml contract, probatio schemas, selectors, entity/device targeting, response data, translated error messages, and the Bronze quality-scale rule that actions must be registered in async_setup(). SYMPTOMS — load this if you are about to: register an action in `async_setup_entry()`; add a `services.yaml` field without a selector; add an `entity_id` field where `target:` belongs; raise a plain English `HomeAssistantError`; or swallow an action failure into a log line.
ha-release
Cut a release of this Home Assistant custom integration, or prepare the commits that feed it. Use when asked to "release", "cut a version", "bump the version", "prepare release notes", "what will the next version be", "write a commit message", "why didn't release-please pick this up", or when reviewing whether a change is user-facing. Covers the Conventional Commits rules commitlint enforces here, how release-please derives the version and changelog, the pre-1.0 bump rules, script/version and script/release-notes, skipping a commit from the notes, and the commit rules this project enforces for agents. SYMPTOMS — load this if you are about to: commit without an explicit request; offer to `git push`; label a user-facing fix as `chore` (chore, like every hidden type, never reaches the changelog and never triggers a release); write a commit subject over 100 characters or in sentence case; or edit the version in `manifest.json` by hand.
ha-quality-review
Perform a structured quality review of this Home Assistant custom integration, either as a full audit or scoped to a diff. Use when asked to "review the integration", "audit the code", "check quality scale", "are we bronze/silver/gold", "is this ready to release", "review my changes", "what's missing before publishing", or before opening a pull request that touches integration code. Covers running the automated gates first, then auditing architecture, the Integration Quality Scale rules, error handling, security, performance, user experience, and documentation — and reporting findings ranked by severity with concrete fixes. SYMPTOMS — load this if you are about to: report a review that only restates linter output; claim real-device testing that did not happen; give a finding without a file path and a fix; or judge quality without running `script/hassfest` and the test suite first.
ha-planning
Plan a large change to this Home Assistant custom integration before writing code, or record an architectural decision. Use when asked to "create a plan", "plan this feature", "how should we approach", "propose an architecture", "write an ADR", "document this decision", "should we use library X or write our own client", or whenever a change would touch more than about ten files or alter the integration's structure. Covers when a plan is mandatory, the phased plan format, where plans live, when a decision is worth recording, and the DECISIONS.md entry format used by this project. SYMPTOMS — load this if you are about to: start a refactor spanning more than ten files without confirmation; write a plan whose phases name no files; write one in prose nobody will finish reading; create a planning markdown file outside `.agents/scratch/`; or make a hard-to-reverse architectural choice without recording why.