Powercalc Translations
Developmentpowercalc-translationsPowercalc Translations is an Agent Skill for development published in the bramstroker/homeassistant-powercalc repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Use when adding, removing, renaming, or changing PowerCalc Home Assistant translation keys or strings; en.json is the source, all locale files must keep matching keys and placeholders.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/bramstroker/homeassistant-powercalc/blob/HEAD/.agents/skills/powercalc_translations/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/powercalc-translations, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
SKILL: PowerCalc Translations
Skill ID
powercalc.translations
Description
Use this skill whenever a task adds, removes, renames, or changes translation keys or translated strings for PowerCalc.
When This Skill Should Be Used
Use this skill for changes under:
custom_components/powercalc/translations/*.json
Also use it when implementation work adds or changes UI text, config flow strings, repair strings, selector labels, common strings, or any Home Assistant translation key consumed by PowerCalc.
Source of Truth
custom_components/powercalc/translations/en.jsonis always the source translation file.- Every other translation file must contain the same nested key paths as
en.json. - Non-English files must not introduce extra keys that are absent from
en.json. - Preserve the structure and key order from
en.jsonwhen adding missing keys.
Translation Mode Question
Before modifying non-English translation files, ask the user one concise question unless the task already answers it:
Should I copy the English strings into the other locale files, or should I actually translate them?
If the user chooses copy mode, copy the exact English string for new or changed keys into every locale. If the user chooses translate mode, translate the human-readable text while preserving every placeholder exactly.
Placeholder Rules
Placeholders use Home Assistant style braces, for example {entity}, {source}, or {docs_uri}.
For every string path that exists in en.json:
- Every locale must contain the exact same placeholder names for that path.
- Do not translate placeholder names.
- Do not add, remove, rename, or reorder placeholder braces while translating.
- If an English string changes placeholders, update every locale string at that same path.
Workflow
- Read
custom_components/powercalc/translations/en.jsonfirst. - Make the intended translation change in
en.json. - Apply the same key structure change to every other
*.jsonfile incustom_components/powercalc/translations/. - Use the chosen translation mode for non-English values.
- Preserve valid JSON formatting and existing indentation.
- Verify key parity and placeholders before claiming completion.
Validation
Before running tests, compare the nested leaf key paths in every locale file against en.json. Missing or extra paths must be fixed against en.json.
Run:
python .github/scripts/validate_translations.py
uv run pytest tests/test_translations.py
The validation script and test must pass before the work is complete.
Guardrails
- Do not edit translation keys in only one locale.
- Do not delete locale keys unless the same key was removed from
en.json. - Do not rely on machine translation when the user requested copy mode.
- Do not claim translated language accuracy unless it was reviewed or the user explicitly requested best-effort translation.