docs: correct the meta-only stub claim in the add-a-language procedure (#2144)

Both the locales README and AGENTS.md said a new language's settings catalog
may start as a meta-only stub. Following that literally leaves a PR red: the
Decision and PredicateOp word checks in test_settings_ui_i18n.py apply to every
catalog and are not behind LOCALE_COMPLETENESS_CHECKS, and once a catalog does
carry messages, the address-register check in test_translate_locales.py wants
one whose English addresses the reader.

Both documents now name what a catalog owes before it merges, and the README's
list of ungated PR-CI checks gains the two checks that live outside
test_locale_parity.py. Verified by running the corrected procedure: a stub with
meta plus those keys, an empty component catalog, regenerated projections and
the code added to the AGENTS.md locale list leaves the three locale test files
green.

Three comments carried the same claim and now describe what they actually
guard: the _TRANSLATED_LOCALES exclusion in test_translate_locales.py, and the
completeness marker plus the tools-tab docstring in test_settings_ui_i18n.py.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: Patch76

AGENTS.md

@@ -762,9 +762,16 @@ code (`de`, `es`, `fr`, `it`, `ru`, `zh-Hans`) names every file:
 That list of codes is itself pinned by
 `test_agents_md_lists_every_shipped_locale`: adding a language means adding its
 code here, in the same PR, or the suite goes red. To add a language, add the
-two authored catalogs (settings UI + component; the settings one can start as
-a `meta`-only stub), regenerate, and let the translation pipeline below fill
-the strings.
+two authored catalogs (settings UI + component), regenerate, and let the
+translation pipeline below fill the strings. The component catalog may start
+empty; the settings one may not start `meta`-only, because three ungated
+checks read the shipped catalogs themselves: every decided `Decision` outcome
+and every `PredicateOp` operator needs a translated word
+(`policies.pending.decision.*`, `policies.operators.*` — a value that still
+spells the backend literal counts as untranslated), and at least one
+translated key must have English that addresses the reader in the second
+person, which is where `scripts/translate_locales.py` reads the catalog's
+address register. `src/ha_mcp/settings_ui/locales/README.md` names the tests.
 
 Settings UI catalogs are auto-discovered (no registration). Their `messages` may
 omit keys — English is the per-key fallback — but may not carry one `en.json`

src/ha_mcp/settings_ui/AGENTS.md

@@ -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 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.
+- `_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 near-empty catalog may merge, though not a `meta`-only one: the `Decision` and `PredicateOp` words plus one reader-addressing key are checked ungated against the shipped catalogs — 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/locales/README.md

@@ -24,10 +24,12 @@ Home Assistant language code names every file:
 - `homeassistant-addon/translations/<code>.yaml` (generated)
 - `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
-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
+Add the two authored catalogs, 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. The component catalog may start as an empty object;
+this one needs `meta` (`native_name`, `dir`) plus the handful of `messages`
+keys the ungated checks below demand — a `meta`-only catalog is red in PR CI.
+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`
@@ -71,9 +73,26 @@ 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):
+In PR CI (ungated — `tests/src/unit/test_locale_parity.py` unless another file
+is named):
 
 - Every surface carries the same set of language codes.
+- Every decided `Decision` outcome (all but `pending`) and every
+  `PredicateOp` operator has a word in every catalog, non-blank — and in every
+  catalog but `en.json` not still spelled the way the backend does
+  (`test_every_decided_outcome_has_a_catalog_word`,
+  `test_every_predicate_operator_has_a_catalog_word` in
+  `tests/src/unit/test_settings_ui_i18n.py`). These words render inside
+  otherwise translated sentences, and the page payload merges English
+  underneath, so a missing key shows English's own word rather than reading as
+  a gap — and the bare enum literal where English lacks the key too. That is
+  why they are owed at once rather than left to the sync.
+- At least one translated key whose English addresses the reader in the
+  second person, so `scripts/translate_locales.py` can show the engine
+  how this catalog addresses its reader
+  (`test_every_shipped_catalog_gets_reader_addressing_samples` in
+  `tests/src/unit/test_translate_locales.py`). Without one the pipeline
+  translates the rest of the catalog with no register to imitate.
 - 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.*`,
@@ -82,9 +101,9 @@ In PR CI (`tests/src/unit/test_locale_parity.py`, ungated):
   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):
+In the post-merge `locale-sync.yml` workflow only (the same files, 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

tests/src/unit/test_settings_ui_i18n.py

@@ -309,9 +309,10 @@ def test_shipped_catalog_loads_and_is_registered(locale: str) -> None:
 
 # Same gate as ``test_locale_parity.completeness`` (see the marker comment
 # there): filled tool sections are the post-merge locale-sync workflow's to
-# owe, not the PR's — a new language legitimately merges as a ``meta``-only
-# stub the daily sync then fills. ``test_locale_sync_gate_shape`` pins the
-# env-var wiring on both files.
+# owe, not the PR's — a new language legitimately merges as a near-empty
+# catalog the daily sync then fills, carrying only what the ungated checks in
+# this file ask of it. ``test_locale_sync_gate_shape`` pins the env-var wiring
+# on both files.
 _completeness = pytest.mark.skipif(
     not os.environ.get("LOCALE_COMPLETENESS_CHECKS"),
     reason=(
@@ -326,9 +327,9 @@ def test_shipped_catalog_loads_and_is_registered(locale: str) -> None:
 def test_shipped_catalog_translates_the_tools_tab(locale: str) -> None:
     """Both tool sections must be filled once the sync has run.
 
-    Split from the structural check above so a ``meta``-only stub catalog
-    can merge and be filled post-merge; an empty section here after a clean
-    sync run means the fill never happened.
+    Split from the structural check above so a near-empty catalog can merge
+    and be filled post-merge; an empty section here after a clean sync run
+    means the fill never happened.
     """
     catalog = CATALOGS[locale]
 

tests/src/unit/test_translate_locales.py

@@ -36,10 +36,12 @@
 )
 
 _SETTINGS_LOCALES = _REPO_ROOT / "src" / "ha_mcp" / "settings_ui" / "locales"
-# Catalogs that carry translated text. A new language may ship as a meta-only
-# stub for the pipeline to fill (AGENTS.md § Translations), and a stub has no
-# wording to sample yet — requiring samples of it would forbid the documented
-# way to add a language.
+# Catalogs that carry translated text. A catalog with no `messages` yet has no
+# wording to sample, so sampling it would fail on emptiness rather than on the
+# property this checks. Such a catalog cannot ship anyway — the `Decision` and
+# `PredicateOp` word checks in test_settings_ui_i18n.py apply to every catalog
+# (AGENTS.md § Translations) — so the exclusion narrows this check rather than
+# opening a way past it.
 _TRANSLATED_LOCALES = sorted(
     path.stem
     for path in _SETTINGS_LOCALES.glob("*.json")
@@ -790,9 +792,12 @@ class TestMetaOnlyStub:
     def test_documented_stub_language_flow_does_not_crash(
         self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
     ) -> None:
-        """AGENTS.md says a new language may start as a meta-only stub catalog
-        and the pipeline fills every string — so a catalog with no messages/
-        tools/tool_groups sections must plan cleanly and be writable."""
+        """A new language starts as a near-empty catalog the pipeline fills, and
+        the sections it does not carry yet are absent rather than empty — so a
+        catalog with no messages/tools/tool_groups sections must plan cleanly
+        and be writable. What a shipped catalog owes beyond that is checked
+        against the real files (see the address-register check above), not
+        here."""
         locales = tmp_path / "locales"
         locales.mkdir()
         (locales / "en.json").write_text(