feat: land machine translations post-merge instead of in the PR (#2115)

* feat: land machine translations post-merge instead of in the PR

The locale pipeline moves from committing translations onto the PR branch
(same-repo PRs only; fork PRs were skipped) to a daily post-merge run that
pushes them straight to master with the release App credential. The
completeness checks in test_locale_parity.py gate behind
LOCALE_COMPLETENESS_CHECKS=1 and run in the workflow as its verification;
PR CI keeps only deterministic, engine-free obligations.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NgWpy7arov56hET1PzoeCS

* fix: address review findings — restore two-job token isolation, split verification, close fail-open gate

Codex P1s: the push credential moves back to a fresh job consuming a
patch artifact through the rename pre-checks and locale allowlist; the
component placeholder check returns to PR CI, restricted to keys whose
English matches the baseline.

Review-agent findings: the staleness check (held gated-stub keys) no
longer blocks the push — it reddens the job instead of discarding every
translation and re-burning quota daily; both verification steps assert
zero junit skips and test_locale_sync_gate_shape.py pins the gate wiring
pre-merge; the filled-tool-sections asserts split out of
test_shipped_catalog_loads_and_is_registered so a meta-only stub
language can merge; wrong-ref dispatches fail loudly; docs now state
that hand-translating a changed English string requires a baseline
repin in the same PR (AGENTS.md, locales README, settings_ui AGENTS.md,
CONTRIBUTING.md).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NgWpy7arov56hET1PzoeCS

* fix: harden the push path per bot review round two

Codex P1: the push job now refuses any settings.js change outside the
generated FEATURE_META block (byte-compare against master with the
region stripped) — generate_locales preserves everything outside the
markers, so the whole-file allowlist entry was a smuggling channel for
served client-side JS. Codex P2s: the master-write concurrency group
moves to the short push job so the translate leg cannot make a hotfix
release queue behind it (a locale-sync group prevents self-overlap),
and the dispatch guard compares the full ref so a tag named after the
default branch cannot pass. CodeRabbit: the guard's ref values reach
the shell through env, never expanded (zizmor template-injection); the
rebase-retry fetches through the same authenticated URL as the push;
the shape test's export assertion narrows to the git-add step; the
baseline-drift set is computed once, cached, across the placeholder
test's parametrization.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NgWpy7arov56hET1PzoeCS

* fix: drop settings.js from the sync patch and pin gate semantics, per review

Patch76's review, both concerns. settings.js leaves the export and the
allowlist entirely: its generated FEATURE_META block derives from
en.json alone, which the pipeline never touches and PR CI keeps
current, so the sync never legitimately stages the file — the marker
region byte-compare it replaces guarded only outside the markers while
the block itself is executed JavaScript. With no executable file on the
patch, the no-code property holds by construction.

The shape test now pins semantics instead of tokens: the push predicate
is asserted with its negation, the allowlist arms are compared as an
exact set, the dispatch guard's actual ref comparison is required, and
every junit report written must be consumed. Replayed the review's
mutation matrix — inverting the predicate, widening the allowlist,
hollowing the guard, and deleting the skip-check call sites each now
fail exactly one assertion.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NgWpy7arov56hET1PzoeCS

* test: pin the catch-all's refusal and the credential-free checkout

Patch76's second matrix pass: gutting the catch-all arm to '*) ;;'
leaves the allowlist's parsed arm SET unchanged while admitting every
path — its exit 1 is the entire allowlist — and nothing read the
checkout steps, so removing persist-credentials: false survived too.
Both pinned; both mutations now fail exactly one assertion each.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NgWpy7arov56hET1PzoeCS

---------

Co-authored-by: kingpanther13 <kingpanther13@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: kingpanther13

.github/workflows/locale-sync.yml

@@ -336,7 +336,7 @@ On merge, `hotfix-release.yml` runs semantic-release, creates GitHub release, sy
 | `build-binary.yml` | Release | Linux/macOS/Windows binaries |
 | `addon-publish.yml` | Release | HA add-on update |
 | `sync-tool-docs.yml` | Push to master (`src/ha_mcp/tools/`, `scripts/extract_tools.py`) | Regenerate `tools.json`, README, DOCS.md |
-| `locale-sync.yml` | Same-repo PR touching locale catalogs, tool sources, or the locale scripts | Machine-translate stale/missing strings and commit them to the PR branch |
+| `locale-sync.yml` | Daily schedule + manual dispatch | Machine-translate stale/missing strings post-merge and push them straight to master |
 
 **Docker image tags** (`ghcr.io/homeassistant-ai/ha-mcp`): stable releases push `:latest` + `:stable` + semver tags (`release-publish.yml`); dev builds push only `:dev` + `:dev-<sha>` (`publish-dev.yml`) — **never `:latest`**, which is reserved for stable. The HA add-on images live in separate repos (`-addon-{arch}`, `-addon-dev-{arch}`) and are selected by an explicit `version:` pin, not by `:latest`.
 
@@ -745,10 +745,9 @@ lacks: nothing renders it. `tool_groups` and `tools` may do neither: each locale
 must carry exactly the renderable group headings and every tool name, no key
 more and none fewer. The check derives the tool set from
 the sources (`scripts/extract_tools.py`), not from the committed
-`site/src/data/tools.json` that `sync-tool-docs.yml` regenerates only after
-merge — so the PR adding a tool goes red, rather than the next PR someone
-opens. Separately from those key rules, both authored surfaces cap how much
-*text* a catalog
+`site/src/data/tools.json` — the check must not depend on a generated
+artifact that a separate post-merge workflow keeps current. Separately from
+those key rules, both authored surfaces cap how much *text* a catalog
 may leave byte-identical to English or omit outright, so a stub cannot ride the
 fallbacks: 5% for the settings UI `messages`, its `tools` titles and
 descriptions, and each generated add-on projection (per flavor, computed from
@@ -767,8 +766,24 @@ baseline diff (`tests/src/unit/locale_source_baseline.json`), retranslates
 the changed or missing keys in every language via the Gemini API
 (`GEMINI_API_KEY`; free tier), validates placeholders and markup, regenerates
 the derived catalogs, and repins the baseline. The `locale-sync.yml` workflow
-runs it automatically on same-repo PRs and commits the result to the PR
-branch for review; run it locally for fork PRs or to use a different engine.
+runs it AFTER merge, on a daily schedule, and pushes the result straight to
+master with the release App credential (the same pattern as the version-bump
+bots and `sync-tool-docs.yml`) — so any PR, fork or same-repo, merges
+without owing translations, and one sync run picks up everything merged
+since the last one. The checks that police translated content (missing or
+orphaned keys, staleness against the baseline, cross-surface shared wording,
+the untranslated-share ceilings, filled tool sections) are gated behind
+`LOCALE_COMPLETENESS_CHECKS=1` and run in that workflow, not in PR CI —
+`test_locale_sync_gate_shape.py` pins the wiring. What a PR still owes is
+deterministic and engine-free: regenerate the derived catalogs
+(`python scripts/generate_locales.py`) when a canonical English string
+changes, and placeholder parity on component keys whose English is current.
+To choose the wording yourself, translate in your own PR **and run
+`python scripts/update_locale_baseline.py` in it** — the repinned baseline
+is what tells the next sync your wording already covers the changed English
+(hand-edits win); without the repin the sync retranslates the key and
+overwrites you. Run `scripts/translate_locales.py` locally instead to
+machine-fill in-PR or to use a different engine (it repins for you).
 The baseline pins the English each translation was written against, because
 key parity cannot see a string whose meaning changed: #1993 flipped a policy
 string from ALL-match to ANY-match and left the Chinese text asserting the
@@ -783,8 +798,8 @@ tool shows one instead. Editing that summary moves the English out from under
 six catalogs; the pipeline retranslates them. One deliberate exception: a
 change to a feature-gated tool's PARSED docstring (its stub unchanged) is
 stub-review work, not translation work — the pipeline holds that baseline key
-stale, and the red check clears only when a human confirms the stub still
-describes the tool and runs `python scripts/update_locale_baseline.py`.
+stale, and the locale-sync run stays red until a human confirms the stub
+still describes the tool and runs `python scripts/update_locale_baseline.py`.
 
 **Rate limits and outages degrade loudly, never silently.** Engine calls are
 paced under the free-tier request rate and retry transient errors (429/5xx,
@@ -793,14 +808,15 @@ and the run continues, and two consecutive dead batches stop the run early
 instead of burning the remaining quota. A partial run — a daily-quota hit,
 an outage — still commits every finished translation plus
 `tests/src/unit/locale_sync_progress.json`, which the next run reads to
-resume where it stopped: **re-running the workflow is the entire recovery
-procedure.** Only a fully successful run repins the baseline and deletes the
-progress file, so CI stays red until every string is translated and nothing
+resume where it stopped: **re-running the workflow — or just waiting for the
+next day's cron — is the entire recovery procedure.** Only a fully
+successful run repins the baseline and deletes the progress file, so the
+sync runs stay red until every string is translated and nothing
 unvalidated ever ships. **The fallback when the engine is down is a human**:
-anyone (the PR author included) can hand-translate the strings the dry-run
+anyone can hand-translate the strings the dry-run
 lists, run `python scripts/generate_locales.py` and
-`python scripts/update_locale_baseline.py`, and push — CI goes green and the
-next pipeline run no-ops (it also cleans up any committed progress file).
+`python scripts/update_locale_baseline.py`, and open an ordinary PR — the
+next sync run no-ops (it also cleans up any committed progress file).
 Hand-edits always win; the machine only ever touches strings whose English
 changed. The engine itself is one function (`_call_gemini`) with
 `GEMINI_API_URL` / `GEMINI_MODEL` / `GEMINI_API_KEY` overrides for any

AGENTS.md

@@ -50,8 +50,10 @@ uv run lefthook install --reset-hooks-path
 - **Docs**: Update README.md for user-facing changes
 - **PRs**: Use the template, ensure tests pass
 - **Translations**: A language ships on all four translated surfaces or not at
-  all. Read `src/ha_mcp/settings_ui/locales/README.md` first — a catalog copied
-  from `en.json` fails CI
+  all. Read `src/ha_mcp/settings_ui/locales/README.md` first. Changing an
+  English string owes no translations — the post-merge locale-sync workflow
+  machine-fills them daily, and its verification rejects a catalog left
+  byte-identical to English
 
 ## 💤 Abandoned PRs
 

CONTRIBUTING.md

@@ -36,7 +36,7 @@
 the run early. Partial runs are resumable — completed work is recorded in
 ``tests/src/unit/locale_sync_progress.json`` and skipped on the rerun; only a
 fully successful run repins the baseline and deletes that record, so the
-parity suite stays red until every string is translated.
+locale-sync runs stay red until every string is translated.
 
 Usage::
 
@@ -1002,8 +1002,9 @@ def _repin_baseline(module: Any) -> None:
     so nothing on screen went stale, but someone must confirm the stub still
     describes the tool. Automation must not wave that through — changed
     ``" (parsed)"`` keys keep their OLD hash here, leaving
-    ``test_translations_are_checked_against_current_english`` red until a
-    human confirms and runs ``scripts/update_locale_baseline.py`` (the manual
+    ``test_translations_are_checked_against_current_english`` — run by the
+    locale-sync workflow's completeness verification — red until a human
+    confirms and runs ``scripts/update_locale_baseline.py`` (the manual
     repin, which is that confirmation).
     """
     current = module.english_sources()

scripts/translate_locales.py

@@ -37,7 +37,7 @@ Any reachable HA instance works for `HOMEASSISTANT_URL` / `HOMEASSISTANT_TOKEN`.
 - `settings.html` — the page markup. `__HA_MCP_CSS__` and `__HA_MCP_JS__` are filled once at import. `__HA_MCP_THEME_PREFS__`, `__HA_MCP_I18N__`, `__HA_MCP_LANG__`, and `__HA_MCP_DIR__` are filled per request by `_render_settings_html()`.
 - `settings.js` — the client script, injected into `<script>__HA_MCP_JS__</script>`. Not served as a separate asset.
 - `settings.css` — the stylesheet, injected into `<style>__HA_MCP_CSS__</style>`.
-- `_i18n.py` and `locales/*.json` — auto-discovered translation catalogs. English is the per-key fallback for `messages`. Adding a language is not a single-file change: it ships on all four translated surfaces or not at all, its `tool_groups` and `tools` sections are mandatory and exact, and `en.json` is the wrong starting point because it carries both of those empty. See `locales/README.md` for the procedure and the repository-root `AGENTS.md` § Translations for the rules CI enforces. The wheel, sdist and binary declarations match the locale directory by pattern, so a new catalog needs no packaging edit — but keep those patterns intact when touching packaging.
+- `_i18n.py` and `locales/*.json` — auto-discovered translation catalogs. English is the per-key fallback for `messages`. Adding a language is not a single-file change: it ships on all four translated surfaces or not at all. Its `tool_groups` and `tools` sections must end up exact — the post-merge locale-sync workflow fills and verifies them, so a `meta`-only stub may merge — and `en.json` is the wrong starting point because it carries both of those empty by design. See `locales/README.md` for the procedure and the repository-root `AGENTS.md` § Translations for the rules CI enforces. The wheel, sdist and binary declarations match the locale directory by pattern, so a new catalog needs no packaging edit — but keep those patterns intact when touching packaging.
 
 ## Gotchas (read before editing)
 

src/ha_mcp/settings_ui/AGENTS.md

@@ -25,10 +25,12 @@ Home Assistant language code names every file:
 - `homeassistant-addon-dev/translations/<code>.yaml` (generated)
 
 Add the two authored catalogs — this one may start as a `meta`-only stub
-(`native_name`, `dir`) — then run `python scripts/generate_locales.py` and let
-`scripts/translate_locales.py` (or the `locale-sync.yml` workflow on the PR)
-machine-fill every string; review its output like any other diff. Also
-add the new code to the locale list in the repository-root `AGENTS.md`
+(`native_name`, `dir`) — then run `python scripts/generate_locales.py` and
+merge: the post-merge `locale-sync.yml` workflow machine-fills every string
+over its next daily runs. To fill them in your own PR instead, run
+`scripts/translate_locales.py` yourself and review its output like any
+other diff. Also add the new code to the locale list in the repository-root
+`AGENTS.md`
 § Translations — that list is pinned by
 `test_agents_md_lists_every_shipped_locale`. The engine reads the target
 language from `meta.native_name`, so any language an LLM can write — natural
@@ -69,21 +71,30 @@ import, so the failure names the file but arrives as a broken test module:
 
 ## What CI checks
 
+In PR CI (`tests/src/unit/test_locale_parity.py`, ungated):
+
 - Every surface carries the same set of language codes.
-- `tool_groups` and `tools` name exactly the renderable groups and tools — a
-  tool added to the codebase turns every locale red in the PR that adds it.
+- The generated files (both add-on YAMLs, `FEATURE_META`) are byte-exact
+  generator output (`test_derived_catalogs_match_the_canonical_store`); run
+  `python scripts/generate_locales.py` after touching any `addon.*`,
+  `addon_stable.*` or `features.*` key.
+- Component-catalog `{placeholder}` parity, for keys whose English still
+  matches the baseline — a hand edit that drops a placeholder fails the PR
+  that makes it; a translation awaiting a machine rewrite is excluded.
+
+In the post-merge `locale-sync.yml` workflow only (the same test file, gated
+behind `LOCALE_COMPLETENESS_CHECKS=1` — a PR that changes English merges
+without these, and the daily sync owes them afterwards):
+
+- `tool_groups` and `tools` name exactly the renderable groups and tools.
 - At most 5% of this catalog's `messages`, and 5% of its `tools` texts, may be
   byte-identical to English or missing outright; the component catalogs allow
   15%, because they carry product names as keys of their own. A single tool
   whose `title` *and* `description` are both still English fails by name
   however small the share.
-- The generated files (both add-on YAMLs, `FEATURE_META`) are byte-exact
-  generator output (`test_derived_catalogs_match_the_canonical_store`); run
-  `python scripts/generate_locales.py` after touching any `addon.*`,
-  `addon_stable.*` or `features.*` key.
 - The English each translation was written against is hashed in
   `tests/src/unit/locale_source_baseline.json`, so a later edit to an English
-  string turns the locales red rather than leaving them silently stale —
+  string reads as stale rather than silently keeping the old meaning —
   `scripts/translate_locales.py` retranslates exactly those keys and repins
   the baseline. Adding a language does not change any English source, so no
   baseline regeneration is needed for it.