fix: keep hardcoded config-flow labels untranslated (#2170)

* fix: keep hardcoded config-flow labels untranslated

The 2026-08-08 locale-sync run failed its content-completeness verification
and pushed nothing: filling `nl` for the first time, the engine translated
the on-screen option in `common.connect_local_lan` ("Local network" ->
"Lokaal netwerk"), which sends the reader looking for an option that is not
on the form. The prompt already asked for that literal to survive; nothing
enforced it, so the only thing that caught it was the parity test after the
run, which blocks the push for every locale at once.

`_validate` now rejects a translation that localises a selector label the
config flow hardcodes in Python. Quoting alone is not the signal: catalogs
correctly translate quoted cross-references to their own option labels, and
Home Assistant translates its own buttons — all six shipped catalogs
translate "Add entry" and all six keep "Local network". The label set is
read from `config_flow.py` at runtime rather than duplicated here, so a
rename cannot strand a stale copy; the existing
`test_connect_local_lan_quotes_the_bind_host_option` guards the rename
against the catalogs.

Authoring the `nl` string as well takes the key out of the work plan, so the
next run is clean rather than merely unblocked. Its English is unchanged
since the last baseline repin, so the sync will not retranslate it and no
repin is needed here — repinning now would freeze the strings that are
legitimately waiting for retranslation.

The workflow header and the module docstring both list what gets validated,
so both name the new check; the `.github/` edit is that comment only.

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

* chore: type the regex results the label check reads

`re.findall` is typed as `list[Any]`, so returning one of its elements made
`_untranslatable_label_dropped` return `Any` from a function declared
`str | None` — which the repository's mypy settings reject. Annotating both
call sites keeps the values typed as the strings the patterns already
guarantee.

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

* fix: read the quoted label through typographic quote marks too

The label check pulled quoted text out of the English source with a straight
double quote on both sides, so an English string that quoted the option the
way two shipped strings already do — `“…”` — never reached the comparison and
the label was free to be translated. Which quote mark an author reaches for
should not decide whether the option on the form is protected.

Widening the class leaves the measurement unchanged: still zero violations
across the 3232 English/translation pairs in the shipped catalogs, and the
string that failed the sync run is still rejected in both spellings.

The workflow header lists what the script validates and had been one item
short of the module docstring since before this change; it now names
formatting-tag parity as well, so the two lists read the same.

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

---------

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

Author: Patch76

.github/workflows/locale-sync.yml

@@ -18,8 +18,9 @@ name: Locale Sync
 # which is what tells the bot the changed English is already covered).
 #
 # Verification is three layers. (1) Every returned string is validated
-# before it is written (placeholder, markup and panel-link parity, in the
-# script). (2) After a clean run, the content-completeness checks that PR CI
+# before it is written (placeholder, markup, formatting-tag and panel-link
+# parity, plus the config flow's hardcoded option labels, in the script).
+# (2) After a clean run, the content-completeness checks that PR CI
 # skips run here under LOCALE_COMPLETENESS_CHECKS=1; a failure means the
 # output may be corrupt (the engine pasted English back, parity broke) and
 # BLOCKS the push — machine translations are recomputable, so dropping them

custom_components/ha_mcp_tools/translations/nl.json

@@ -1,5 +1,6 @@
 {
   "common": {
+    "connect_local_lan": "Lokaal/LAN (wanneer Netwerktoegang \"Local network\" is): {url}",
     "oauth_not_serving": "Legacy OAuth levert deze nog niet — start Home Assistant opnieuw op wanneer je daarom wordt gevraagd, om ze te activeren."
   }
 }

scripts/translate_locales.py

@@ -26,9 +26,10 @@
 run sees nothing stale and no-ops. Hand-edits always win; the machine only
 touches strings whose English changed.
 Every returned string is validated (placeholder parity, the settings UI markup
-allowlist, formatting-tag parity, panel-link parity) before it is written; a
-failure leaves that string unwritten and the run red rather than shipping a
-broken translation.
+allowlist, formatting-tag parity, panel-link parity, and the config flow's
+hardcoded option labels staying untranslated) before it is written; a failure
+leaves that string unwritten and the run red rather than shipping a broken
+translation.
 
 Rate limits and outages: requests are paced under the free-tier rate and
 retry transient errors with backoff; a persistently failing batch marks its
@@ -56,6 +57,7 @@
 from collections import Counter
 from collections.abc import Container
 from dataclasses import dataclass, field
+from functools import lru_cache
 from pathlib import Path
 from typing import Any, Literal, NamedTuple
 
@@ -415,10 +417,54 @@ def build_plan(module: Any) -> Plan:
     return plan
 
 
+_CONFIG_FLOW_PATH = REPO_ROOT / "custom_components" / "ha_mcp_tools" / "config_flow.py"
+_SELECTOR_LABEL_RE = re.compile(r'label="([^"]+)"')
+# English sources quote with straight or typographic marks — both already occur
+# in the shipped catalogs — and the label check has to see the quoted text
+# either way, or the spelling of a quote silently decides whether it applies.
+_QUOTED_RE = re.compile(r'["“”«»„]([^"“”«»„]+)["“”«»„]')
+
+
+@lru_cache(maxsize=1)
+def _hardcoded_option_labels() -> tuple[str, ...]:
+    """Config-flow selector labels, which read English on every reader's form.
+
+    Quoting alone does not say whether a string may be translated: catalogs
+    correctly translate quoted cross-references to their own option labels,
+    and Home Assistant translates its own buttons ("Add entry"). What must
+    survive verbatim is the narrower class this returns — labels our config
+    flow hardcodes in Python, so no catalog can localise them and a reader
+    told to pick a translated one goes looking for an option that is not on
+    the form. Read from the source instead of listed here so a rename cannot
+    strand a stale copy; ``test_connect_local_lan_quotes_the_bind_host_option``
+    guards the rename against the catalogs.
+    """
+    labels: list[str] = _SELECTOR_LABEL_RE.findall(_CONFIG_FLOW_PATH.read_text("utf-8"))
+    return tuple(labels)
+
+
+def _untranslatable_label_dropped(english: str, translated: str) -> str | None:
+    """The hardcoded label this translation localised away, if any."""
+    quoted_texts: list[str] = _QUOTED_RE.findall(english)
+    for quoted in quoted_texts:
+        for label in _hardcoded_option_labels():
+            if (
+                label == quoted or label.startswith(f"{quoted} ")
+            ) and quoted not in translated:
+                return quoted
+    return None
+
+
 def _validate(item: WorkItem, translated: Any) -> str | None:
     """The reason a translation is unusable for this item, or None."""
     if not isinstance(translated, str) or not translated.strip():
         return "empty or non-string translation"
+    dropped = _untranslatable_label_dropped(item.english, translated)
+    if dropped is not None:
+        return (
+            f"the on-screen option {dropped!r} is hardcoded in the config flow "
+            "and has to stay untranslated"
+        )
     if set(_PLACEHOLDER_RE.findall(item.english)) != set(
         _PLACEHOLDER_RE.findall(translated)
     ):

tests/src/unit/test_translate_locales.py

@@ -118,6 +118,48 @@ def test_rejects_panel_link_target_drift(self) -> None:
         assert _validate(_item(english=english), wrong) is not None
 
 
+class TestHardcodedOptionLabels:
+    """The config flow hardcodes a couple of selector labels in Python, so
+    Home Assistant shows them in English whatever the reader's language is.
+    A catalog that localises one sends the reader looking for an option that
+    is not on the form — the failure that stopped a whole sync run, since the
+    engine only had a prose rule telling it not to."""
+
+    def test_the_label_set_is_read_from_the_config_flow(self) -> None:
+        # Without this the check degrades silently: an empty label set accepts
+        # every translation and still reports a clean run.
+        labels = translate_locales._hardcoded_option_labels()
+        assert labels, "no selector labels found — the config flow was restructured"
+        assert any(label.startswith("Local network") for label in labels)
+
+    def test_rejects_a_localised_hardcoded_label(self) -> None:
+        english = 'Local/LAN (when Network access is "Local network"): {url}'
+        localised = 'Lokaal/LAN (wanneer Netwerktoegang "Lokaal netwerk" is): {url}'
+        kept = 'Lokaal/LAN (wanneer Netwerktoegang "Local network" is): {url}'
+        assert _validate(_item(section="component", english=english), localised)
+        assert _validate(_item(section="component", english=english), kept) is None
+
+    def test_reads_the_label_through_typographic_quotes(self) -> None:
+        # Shipped English already quotes both ways, so which mark an author
+        # reached for must not decide whether the label is protected.
+        english = "Local/LAN (when Network access is “Local network”): {url}"
+        localised = 'Lokaal/LAN (wanneer Netwerktoegang "Lokaal netwerk" is): {url}'
+        assert _validate(_item(section="component", english=english), localised)
+
+    def test_leaves_other_quoted_text_translatable(self) -> None:
+        # "Add entry" is Home Assistant's own button: HA translates it, so
+        # every shipped catalog translates the quote too. Only labels the
+        # config flow hardcodes are pinned to English.
+        english = 'Not installed — press "Add entry" on this integration\'s page'
+        assert (
+            _validate(
+                _item(section="component", english=english),
+                'Nicht installiert — klicke auf "Eintrag hinzufügen"',
+            )
+            is None
+        )
+
+
 class TestChunk:
     def test_splits_on_the_character_budget(self) -> None:
         big = "x" * (translate_locales._MAX_CHARS_PER_REQUEST - 10)