fix(locales): surface best-effort diagnostics

Author: kingpanther13

AGENTS.md

@@ -809,11 +809,12 @@ language code (`cs`, `de`, `eo`, `es`, `fr`, `it`, `ko`, `nl`, `pl`, `ru`, `sv`,
 `tlh` is the deliberate best-effort exception. It is a hand-maintained novelty
 locale, remains available on all four surfaces when its files are valid, and
 uses English per-key fallback when they are incomplete. It is excluded from
-automatic translation planning so it consumes no model quota, and any
-`tlh`-specific catalog, completeness, literal-parity, registration, or
-generated-drift problem is reported as a warning rather than blocking CI or
-locale-sync. Every other locale and every shared, English-side pipeline failure
-remain hard failures.
+automatic translation planning so it consumes no model quota. Catalog parsing,
+surface registration, and generated-drift problems are reported as warnings
+rather than blocking CI or locale-sync. Completeness and literal parity are not
+checked for `tlh`: missing entries fall back to English, and imperfect novelty
+copy is accepted without a diagnostic. Every other locale and every shared,
+English-side pipeline failure remain hard failures.
 
 That list of codes is itself pinned by
 `test_agents_md_lists_every_shipped_locale`: adding a language means adding its

scripts/generate_locales.py

@@ -250,6 +250,7 @@ def _committed_text(path: Path) -> str:
 def check() -> int:
     """Exit 1 naming every derived file that no longer matches the canon."""
     stale: list[str] = []
+    best_effort_stale: list[str] = []
     for path, content in generated_files().items():
         committed = _committed_text(path)
         if committed != content:
@@ -260,6 +261,7 @@ def check() -> int:
                     "out of sync; run python scripts/generate_locales.py to refresh it",
                     file=sys.stderr,
                 )
+                best_effort_stale.append(relative)
             else:
                 stale.append(relative)
             diff = difflib.unified_diff(
@@ -276,6 +278,12 @@ def check() -> int:
             file=sys.stderr,
         )
         return 1
+    if best_effort_stale:
+        print(
+            "strict derived locale catalogs are in sync; best-effort locale "
+            f"drift was reported above for: {best_effort_stale}"
+        )
+        return 0
     print("derived locale catalogs are in sync")
     return 0
 

src/ha_mcp/settings_ui/AGENTS.md

@@ -38,7 +38,7 @@ Any reachable HA instance works for `HOMEASSISTANT_URL` / `HOMEASSISTANT_TOKEN`.
 - `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 near-empty catalog may merge, though not a `meta`-only one: the `Decision` and `PredicateOp` words, the sentence those words are interpolated into, and one reader-addressing key are all 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.
-- `tlh` is the only best-effort locale: it is excluded from machine translation and its locale-specific validation is warning-only. Invalid Klingon is skipped or falls back to English; every other locale remains strict. Keep this exception centralized in `_locale_policy.py`.
+- `tlh` is the only best-effort locale: it is excluded from machine translation; catalog, registration, and generated-drift problems warn, while completeness and literal parity are intentionally not checked. Invalid Klingon is skipped or falls back to English; every other locale remains strict. Keep this exception centralized in `_locale_policy.py`.
 
 ## Gotchas (read before editing)
 

tests/addon/test_addon_structure.py

@@ -5,6 +5,7 @@
 import re
 import stat
 import sys
+import warnings
 from pathlib import Path
 
 import pytest
@@ -34,9 +35,10 @@ def _report_translation_issues(path: Path, issues: list[str]) -> None:
         return
     message = "; ".join(issues)
     if is_best_effort_locale(path.stem):
-        print(
-            f"::warning file={path}::best-effort locale {path.stem}: {message}",
-            file=sys.stderr,
+        warnings.warn(
+            f"best-effort locale {path.stem} in {path}: {message}",
+            pytest.PytestWarning,
+            stacklevel=2,
         )
         return
     raise AssertionError(message)
@@ -50,12 +52,13 @@ def _report_translation_issues(path: Path, issues: list[str]) -> None:
 )
 
 
-def test_best_effort_addon_translation_issues_warn_instead_of_fail(
-    capsys: pytest.CaptureFixture[str],
-) -> None:
+def test_best_effort_addon_translation_issues_warn_instead_of_fail() -> None:
     issues = ["missing configuration.example"]
-    _report_translation_issues(Path("translations/tlh.yaml"), issues)
-    assert "::warning file=translations/tlh.yaml" in capsys.readouterr().err
+    with pytest.warns(
+        pytest.PytestWarning,
+        match=r"best-effort locale tlh.*missing configuration\.example",
+    ):
+        _report_translation_issues(Path("translations/tlh.yaml"), issues)
 
     with pytest.raises(AssertionError, match=r"missing configuration\.example"):
         _report_translation_issues(Path("translations/de.yaml"), issues)

tests/src/unit/test_generate_locales.py

@@ -137,7 +137,9 @@ def test_check_warns_for_stale_best_effort_output(
         )
 
         assert generate_locales.check() == 0
-        assert "warning" in capsys.readouterr().err.lower()
+        captured = capsys.readouterr()
+        assert "warning" in captured.err.lower()
+        assert "best-effort locale drift was reported" in captured.out
 
     def test_check_keeps_invalid_strict_output_hard(
         self,

tests/src/unit/test_settings_ui_js_behavior.py

@@ -2309,14 +2309,6 @@ def _already_decided_cases() -> list[tuple[str, str]]:
     return [(locale, outcome) for locale in locales for outcome in outcomes]
 
 
-def test_best_effort_locales_are_outside_hard_js_copy_cases() -> None:
-    from ha_mcp.settings_ui._locale_policy import BEST_EFFORT_LOCALES
-
-    assert BEST_EFFORT_LOCALES.isdisjoint(
-        locale for locale, _ in _already_decided_cases()
-    )
-
-
 class TestAlreadyDecidedCopy:
     """The 409 alert must read as one translated sentence.