docs: make the add-a-language procedure match what CI enforces (#2074)

* docs: make the add-a-language procedure match what CI enforces

Both places that tell a contributor how to add a language described a
procedure that fails. `locales/README.md` and `settings_ui/AGENTS.md` said to
copy `en.json` and translate the values; doing exactly that produces five red
tests, because `en.json` ships `tools` and `tool_groups` empty while every
catalog is required to carry both, and because a language has to land on all
four translated surfaces rather than this one.

The README also called `tool_groups` and `tools` optional, which contradicts
AGENTS.md § Translations and the check that enforces it. Neither file mentioned
that the locale list in AGENTS.md is itself pinned by a test, so that step was
documented nowhere.

In the other direction, `settings_ui/AGENTS.md` asked for locale JSON to stay
listed in the wheel, sdist and binary packaging declarations. All three match
the locale directory by pattern, so a new catalog needs no packaging edit at
all; the line now states the invariant that does have to hold.

CONTRIBUTING.md said nothing about translations and now points at the
procedure.

The README additionally records what CI checks — surface parity, the exact
`tool_groups`/`tools` sets, the 5% and 15% identical-or-missing ceilings, and
that adding a language moves no English source and therefore needs no baseline
regeneration.

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

* docs: name the two checks the add-a-language procedure still left out

Both were raised in review on #2074, and both are the defect this PR is
about: a procedure that does not say what CI enforces.

Both add-on flavors are held to the same 5% untranslated ceiling as the
settings UI catalog — `test_addon_catalog_is_not_a_copy_of_english` is
parametrized over both directories and passes
`_MAX_ENGLISH_IDENTICAL_SHARE` — while the README named 5% for this
catalog and 15% for the component ones and left the add-on flavors
unstated.

And an English string shipped from more than one catalog has to read the
same in every language: `test_one_english_string_reads_the_same_on_every_surface`
compares the surfaces against each other rather than against English, so
a contributor can translate all four catalogs faithfully and still go
red. That step belongs in the procedure, not only in the check list,
because it changes how a switch is worded rather than what CI reports
afterwards.

AGENTS.md § Translations states both already; the README, which is the
file a translator opens first, did not.

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

* docs: match the per-tool field rule and the AGENTS.md pointer to the code

`_validate_tools` skips a missing `title` or `description` per tool, and
`test_settings_catalog_keys_name_real_groups_and_tools` compares only the
tool-name key set, so describing both fields as "not optional" overstated
what CI enforces. The exactness is the key set; a field left out counts as
untranslated against the 5% `tools` ceiling, which is how the root AGENTS.md
already words it.

The scoped `src/ha_mcp/settings_ui/AGENTS.md` has no Translations section, so
its bare "`AGENTS.md` § Translations" resolved to itself. Name the
repository-root file, both there and in the same reference in
`locales/README.md`.

* docs: close the four remaining gaps between the procedure and the checks

Same class as the rest of this PR: rules a contributor hits but the README
does not state.

- `meta.native_name` has to be non-empty, differ from English's own name and
  be unique across catalogs (`test_native_names_name_their_own_language`).
  Copying a catalog and leaving the name is exactly what the procedure above
  invites, and the bullet was purely descriptive.
- `messages` values are also constrained at load time: the inline-markup
  allowlist and the panel-link rules raise inside `load_catalogs()`, so
  breaking one surfaces as an import error rather than a named locale
  failure.
- The four-file list carried no per-surface content rules, so following only
  this README produces four files and three red surfaces. Summarised, with a
  pointer to the root `AGENTS.md` § Translations.
- The one-wording rule is conditional in the assertion — the settings UI is
  the tiebreak only where a group has a settings UI member. Groups carried by
  the two add-on flavors alone have none, and that axis was missing from the
  framing above as well.

* docs: say in AGENTS.md that the locale list is pinned

The list of language codes in § Translations is asserted by
`test_agents_md_lists_every_shipped_locale`, and the section never said so —
the one rule this file owns that a contributor adding a language has to act
on. The procedure in `locales/README.md` already pointed here for it.

Kept off the pinned line itself: the test asserts exactly one line carrying
`names every file:` and parses every backticked token on that line as a
locale code.

---------

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

Author: Patch76

AGENTS.md

@@ -717,6 +717,9 @@ code (`de`, `es`, `fr`, `ru`, `zh-Hans`) names every file:
 `src/ha_mcp/settings_ui/locales/<code>.json`,
 `custom_components/ha_mcp_tools/translations/<code>.json`, and
 `homeassistant-addon{,-dev}/translations/<code>.yaml`.
+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.
 
 Settings UI catalogs are auto-discovered (no registration). Their `messages` may
 omit keys — English is the per-key fallback — but `tool_groups` and `tools` may

CONTRIBUTING.md

@@ -49,6 +49,9 @@ uv run lefthook install --reset-hooks-path
 - **Code**: Follow existing patterns, add type hints, test new features
 - **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
 
 ## 💤 Abandoned PRs
 

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 fallback; a new language is added by copying `locales/en.json`, translating values, and preserving keys/placeholders. Locale JSON must remain listed in wheel, sdist, and binary packaging declarations.
+- `_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.
 
 ## Gotchas (read before editing)
 

src/ha_mcp/settings_ui/locales/README.md

@@ -1,18 +1,96 @@
 # Settings UI translations
 
-The settings page discovers every `*.json` catalog in this directory. To add a
-language, copy `en.json`, rename it to the language code (for example
-`it.json`), translate the values, and keep the keys and `{placeholders}`
-unchanged. No Python or JavaScript registration is required.
-
-Catalog sections:
-
-- `meta.native_name`: language name shown in the selector.
-- `meta.dir`: `ltr` or `rtl`.
-- `messages`: interface labels, help text, notices, and runtime messages.
-- `tool_groups`: optional translations keyed by the English MCP tool tag.
-- `tools`: optional per-tool `title` and `description` overrides keyed by the
-  stable MCP tool name. Missing values fall back to the server-provided English.
-
-English is always the fallback, so an incomplete catalog remains usable while
-it is being expanded.
+The settings page discovers every `*.json` catalog in this directory. No Python
+or JavaScript registration is required, and no packaging file needs editing —
+the wheel, sdist and binary declarations all match this directory by pattern.
+
+## Adding a language
+
+A language ships on **all four** translated surfaces or not at all, and one
+Home Assistant language code names every file:
+
+- `src/ha_mcp/settings_ui/locales/<code>.json` (this directory)
+- `custom_components/ha_mcp_tools/translations/<code>.json`
+- `homeassistant-addon/translations/<code>.yaml`
+- `homeassistant-addon-dev/translations/<code>.yaml`
+
+Adding only this catalog fails `test_every_locale_ships_on_every_surface`. 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`.
+
+Only the first of those four files is described below, and the other three
+carry content rules of their own: the component catalog needs every `en.json`
+key with identical `{placeholders}` and no extra ones, and each add-on YAML
+needs a `name` and a `description` for every `schema:` key of *that* flavor's
+`config.yaml`, with nothing left behind for a key the schema no longer
+declares. The two flavors declare different schemas, so neither YAML is a copy
+of the other. The repository-root `AGENTS.md` § Translations states all of
+this; a contributor who writes only this catalog goes red on the other three.
+
+**Start from a translated catalog, not from `en.json`.** English for the tool
+titles and descriptions comes from the tool definitions at runtime, so `en.json`
+ships `tools` and `tool_groups` empty; a copy of it is missing both sections
+that this catalog is required to carry.
+
+**Read the other surfaces before you word a switch.** Wherever the same English
+text is shipped from more than one catalog, your wording has to be byte-identical
+in all of them. That is not only the add-on-options-versus-settings-UI axis: the
+two add-on flavors describe most of the same options, so a good part of the
+pinned parity is stable-against-dev, with no settings-UI text involved at all.
+Translating one surface at a time is exactly how one option ends up with two
+different sentences.
+
+## Catalog sections
+
+- `meta.native_name`: language name shown in the selector. It must be
+  non-empty, must not repeat English's own name, and must differ from every
+  other catalog's — a copied catalog that keeps the name it was copied from
+  fails `test_native_names_name_their_own_language`, because the picker would
+  then offer one label twice.
+- `meta.dir`: `ltr` or `rtl`. Omitting it means `ltr`; any other value is
+  rejected when the catalog loads.
+- `messages`: interface labels, help text, notices, and runtime messages. Keys
+  may be omitted — English is the per-key fallback at runtime — but see the
+  share limit below before leaving a catalog half-finished.
+- `tool_groups`: one entry per renderable MCP tool tag, keyed by the English
+  tag. Not optional, and exact: no key more and none fewer.
+- `tools`: `title` and `description` per tool, keyed by the stable MCP tool
+  name. The key set is not optional and exact in the same way; either field on
+  its own may be left out, but a missing one counts as untranslated against the
+  share limit below.
+
+Keep the keys and `{placeholders}` unchanged in every section.
+
+`messages` values carry two further rules, both enforced when the catalog
+loads rather than by a named test — breaking one raises a `ValueError` at
+import, so the failure names the file but arrives as a broken test module:
+
+- The only inline markup the page can restore is `<code>`, `<strong>`, `</a>`
+  and `<a href="#" data-panel-link="...">`, spelled exactly that way. Any other
+  tag — `<b>`, `<CODE>`, `<code >` — is rejected.
+- A `data-panel-link` target must be a tab the settings page declares, and a
+  translated message must link to the same tabs as its English source, with
+  the same multiplicity. The order may differ, so a translation is free to
+  reorder two links to suit its grammar.
+
+## What CI checks
+
+- 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.
+- At most 5% of this catalog's `messages`, and 5% of its `tools` texts, may be
+  byte-identical to English or missing outright. Both add-on flavors are held to
+  the same 5%; 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.
+- One wording per English string across surfaces, wherever the same English text
+  is shipped from more than one catalog. The failure names every group that
+  disagrees. Where a group has a settings UI member, that is the wording the
+  other surfaces follow today; a group carried only by the two add-on flavors
+  has no such member, so there pick one wording and use it in both.
+- 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. Adding a
+  language does not change any English source, so no baseline regeneration is
+  needed for it.