Acp Translate

ACP Translate

Maintains four parallel translation bundles, each with en.json as the single source of truth and every other language matching its structure exactly:

1. custom_components/adaptive_cover_pro/translations/ — the standard HA translation files (title, config, options, entity, selector, services). Validated by hassfest against HA's strict schema.
2. custom_components/adaptive_cover_pro/summary_i18n/ — the config-summary label bundle (en.json / de.json / fr.json), a nested tree of dotted-key → template strings consumed by _build_config_summary in config_flow.py. This lives outside translations/ on purpose: it is a custom config_summary category that hassfest's schema forbids as a top-level key in translations/en.json, so it is loaded directly by _load_summary_labels instead of via async_get_translations.
3. custom_components/adaptive_cover_pro/reason_i18n/ — the pipeline-reason label bundle (en.json / de.json / fr.json), a nested tree of dotted reason-code → Python str.format template strings consumed by the pure reason_i18n.py resolver to localize pipeline decision-trace reasons, position explanations, and control-state reasons on sensor.* attributes and for the companion Lovelace card. This also lives outside translations/ on purpose: it is not an HA translation category, so it is loaded directly by reason_i18n.py's resolver instead of via async_get_translations.
4. custom_components/adaptive_cover_pro/troubleshoot_i18n/ — the diagnostics-triage finding bundle (en.json / de.json / fr.json), a nested tree of dotted TriageCode → str.format template strings consumed by troubleshoot_i18n.py to render TRIAGE_RULES findings in the config-flow Troubleshoot step, the config summary, and scripts/triage_json.py. Same rationale as the two above: not an HA translation category, loaded directly by its own resolver. Every new triage rule adds a leaf here, so this bundle changes whenever diagnostics/triage.py gains a row.

⚠️ Every operation below applies to ALL FOUR directories. When syncing, adding, or dropping a language, process translations/<lang>.json, summary_i18n/<lang>.json, reason_i18n/<lang>.json, and troubleshoot_i18n/<lang>.json. The summary_i18n/en.json source of truth must stay byte-identical (flattened) to the code-owned _SUMMARY_LABELS_EN (config_flow.py) + COVER_TYPE_LABELS_EN / GEOMETRY_LABELS_EN (cover_types/_summary_labels.py) dicts — a drift guard in tests/test_config_flow_summary_i18n.py / tests/test_policy_summary_i18n.py enforces this. Likewise, the reason_i18n/en.json source of truth must stay byte-identical (flattened) to the code-owned _REASON_TEMPLATES_EN dict (reason_i18n.py) — a drift guard in tests/test_reason_i18n.py enforces this, and troubleshoot_i18n/en.json has the identical relationship to _TRIAGE_TEMPLATES_EN (troubleshoot_i18n.py), guarded by tests/test_troubleshoot_i18n.py. If you change those code dicts, regenerate the matching en.json first, then sync de/fr.

Officially shipped languages: en, de, fr. Any new language is added only on explicit maintainer request via this skill.

Picking the Operation

Match what the user asks for:

If ambiguous, ask the user one clarifying question before proceeding.

Model Strategy

Why Haiku-only for Sync: Incremental changes are small and build on an existing high-quality baseline. Placeholder preservation is verified by tests. Sonnet review is not cost-justified for small diffs.

Why Sonnet for Add language data_descriptions: Full rebuilds produce ~286 long help-text strings with domain concepts (azimuth, elevation, glare zones, climate modes). These benefit from a register/accuracy pass. Step descriptions, labels, and error/abort messages are simple enough for Haiku alone.

Sonnet review-pass key pattern (Add language only):

• Any dotpath containing .data_description. — these are the long help text strings

Everything else stays with Haiku output.

Cost budget: ~$0.03 per 2-language sync; ~$0.25 per 2-language full rebuild. If a run seems headed above $0.50 for one language, stop and ask the user.

Operation 1 — Sync

Use when translations/en.json has changed and DE/FR need to catch up.

Steps

All four bundles. Run the diff + dispatch for translations/, summary_i18n/, reason_i18n/, and troubleshoot_i18n/. A given language's four files can have independent deltas — compute and propagate each separately. The summary_i18n files are small nested trees (flatten the same way); their dotpaths look like rules.force, cover_types.blind, geometry.slat.depth. The reason_i18n files are likewise small nested trees; their dotpaths look like solar.tracking, manual.holding_label, fragment.season_summer, engine.direct_sun. The troubleshoot_i18n files are the smallest; their dotpaths are all under one triage root — triage.custom_safety_bypass, triage.skip_age, triage.sun_tracking_gate_closed.

1. Diff. Load all translation files (all four directories) via Bash+Python (see Reading Translation Files — do NOT use the Read tool). Flatten each to dot-path keys. For each non-en file compute:

   • added: keys in en but not in target
   • removed: keys in target but not in en
   • changed: keys where the en value text changed since the target was last generated. Detect by heuristic: if target[k] looks like an obvious placeholder (equals en[k] verbatim, or is a short English phrase when the rest of the file is clearly in the target language), treat it as changed. When unsure, retranslate — cost of a re-translation is negligible.

2. If nothing to do, report "DE/FR already in sync with en.json" and exit.

3. Dispatch one subagent per language in parallel (single message, two Agent tool calls). Each subagent handles all FOUR of that language's files (translations/<lang>.json, summary_i18n/<lang>.json, reason_i18n/<lang>.json, and troubleshoot_i18n/<lang>.json) and receives:

   • Absolute paths to translations/en.json + summary_i18n/en.json + reason_i18n/en.json + troubleshoot_i18n/en.json and to its own four target files
   • The list of added + changed dotpaths to translate, per file
   • The list of removed dotpaths to strip from each target
   • The language name and ISO code

   The subagent's job (Haiku only — no Sonnet review for Sync):

   • Extract the values at the requested dotpaths from en.json via Bash+Python (see Reading Translation Files — do NOT use the Read tool directly on these files).
   • Run the Haiku translation prompt (see Subagent Prompt Templates) on all of them.
   • Load the target file, merge in the new values, delete removed keys, and write it back via Bash+Python.
   • Return a one-paragraph summary: counts added/changed/removed, any placeholder-preservation warnings, cost estimate.

4. Verify. Run ./scripts/validate_translations.py --ci (covers translations/ only — it does not validate summary_i18n/, reason_i18n/, or troubleshoot_i18n/) and venv/bin/python -m pytest tests/test_translations.py tests/test_config_flow_summary_i18n.py tests/test_policy_summary_i18n.py tests/test_reason_i18n.py tests/test_troubleshoot_i18n.py -q. If either fails, report the failure verbatim and stop. Do not attempt a second auto-sync round.

5. Report. Use the Output Format below.

Operation 2 — Add Language

Use to rebuild DE/FR from scratch or to add a brand-new language.

Steps

1. Validate. The language code must be a valid HA locale (BCP-47 form: de, fr, es, pt-BR, zh-Hans, etc.). If en, refuse — we don't retranslate English. If the file already exists and the user did not say "rebuild" or "retranslate", confirm they want to overwrite.

2. Delete the existing file if rebuilding, so the subagent produces a clean file.

3. Dispatch one subagent per requested language in parallel. If the user says "add DE and FR", send a single message with two Agent tool calls. Each subagent builds all FOUR files for its language and receives:

   • Absolute paths to translations/en.json, summary_i18n/en.json, reason_i18n/en.json, AND troubleshoot_i18n/en.json
   • Absolute paths to the four target files it must write (translations/<lang>.json, summary_i18n/<lang>.json, reason_i18n/<lang>.json, troubleshoot_i18n/<lang>.json)
   • Language name + ISO code
   • The domain-term glossary (see below) — customized per language

   The subagent's job:

   • Load the full translations/en.json, summary_i18n/en.json, reason_i18n/en.json, and troubleshoot_i18n/en.json trees via Bash+Python (see Reading Translation Files).
   • Pass 1 — Haiku bulk: Run the Haiku translation prompt on all keys from all four files. Capture output as a JSON object.
   • Pass 2 — Sonnet review (data_descriptions only): Filter the Haiku output to include ONLY keys containing .data_description. (these exist only in translations/, not the other three bundles) — do not send any other keys to Sonnet. reason_i18n and troubleshoot_i18n have no data_description keys at all, so they never enter the Sonnet pass — they stay Haiku-only, same as summary_i18n's non-data_description keys. Run the Sonnet review prompt on this filtered subset. Merge corrected values back into the Haiku output.
   • Write translations/<lang>.json, summary_i18n/<lang>.json, reason_i18n/<lang>.json, AND troubleshoot_i18n/<lang>.json via Bash+Python: each with the same nested structure as its en.json source, 2-space indent, ensure_ascii=False, trailing newline.
   • Return a summary: key counts written per file, how many data_description keys were reviewed by Sonnet, placeholder warnings, cost estimate.

4. Update tooling. After subagents return:

   • Add the language code to the LANGUAGES constant in scripts/validate_translations.py (unless already present).
   • Update any per-language lists in tests/test_translations.py.

5. Verify. Run ./scripts/validate_translations.py --ci (covers translations/ only — it does not validate summary_i18n/, reason_i18n/, or troubleshoot_i18n/) and venv/bin/python -m pytest tests/test_translations.py tests/test_config_flow_summary_i18n.py tests/test_policy_summary_i18n.py tests/test_reason_i18n.py tests/test_troubleshoot_i18n.py -q. Do not proceed to commit if either fails.

6. Report. If the language is new (not in the previously-shipped set), remind the user to update README's supported-languages list and add a release-notes line.