fix(i18n): make Klingon best effort

Author: kingpanther13

.github/workflows/locale-sync.yml

@@ -16,6 +16,11 @@ name: Locale Sync
 # them, or that no locale carries — so a hand translation survives exactly
 # when its PR also repinned the baseline (scripts/update_locale_baseline.py,
 # which is what tells the bot the changed English is already covered).
+# Klingon (`tlh`) is an explicit best-effort/manual locale. The planner skips
+# it, so it consumes no Gemini quota and cannot make a run partial; generated
+# projections use its valid hand-authored strings and English fallback for
+# missing ones. `tlh`-specific drift and validation report warnings only. All
+# other locales, English sources, and shared pipeline failures remain strict.
 #
 # Verification is three layers. (1) Every returned string is validated
 # before it is written (placeholder, markup, formatting-tag and panel-link

AGENTS.md

@@ -805,6 +805,16 @@ language code (`cs`, `de`, `eo`, `es`, `fr`, `it`, `ko`, `nl`, `pl`, `ru`, `sv`,
 `src/ha_mcp/settings_ui/locales/<code>.json`,
 `custom_components/ha_mcp_tools/translations/<code>.json`, and
 `homeassistant-addon{,-dev}/translations/<code>.yaml`.
+
+`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.
+
 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

scripts/generate_locales.py

@@ -21,6 +21,11 @@
 A locale that lacks a key falls back to English, mirroring the settings UI's
 own per-key fallback, so every generated catalog is structurally complete.
 
+Best-effort locales are still generated when their canonical catalog is valid.
+If one is invalid, generation uses an empty override map (therefore English
+fallback), and ``--check`` reports any best-effort output drift as a warning
+instead of returning failure.
+
 ``FEATURE_META`` (the settings UI's English fallback for feature rows, and
 the row order) is generated from ``en.json``'s ``features.*`` keys between
 marker comments in ``settings.js``.
@@ -43,6 +48,7 @@
 import yaml  # type: ignore[import-untyped]
 
 from ha_mcp.settings_ui._i18n import _validate_string_map
+from ha_mcp.settings_ui._locale_policy import is_best_effort_locale
 
 REPO_ROOT = Path(__file__).resolve().parents[1]
 LOCALES_DIR = REPO_ROOT / "src" / "ha_mcp" / "settings_ui" / "locales"
@@ -67,10 +73,22 @@ def load_catalogs() -> dict[str, dict[str, str]]:
     """
     catalogs: dict[str, dict[str, str]] = {}
     for path in sorted(LOCALES_DIR.glob("*.json")):
-        data = json.loads(path.read_text(encoding="utf-8"))
-        catalogs[path.stem] = _validate_string_map(
-            data.get("messages"), context=f"{path.name}.messages"
-        )
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            if not isinstance(data, dict):
+                raise ValueError(f"{path.name} must contain a JSON object")
+            catalogs[path.stem] = _validate_string_map(
+                data.get("messages"), context=f"{path.name}.messages"
+            )
+        except (OSError, json.JSONDecodeError, ValueError) as exc:
+            if not is_best_effort_locale(path.stem):
+                raise
+            print(
+                f"::warning file={path}::Using English fallback for best-effort "
+                f"locale {path.stem} because its catalog is invalid: {exc}",
+                file=sys.stderr,
+            )
+            catalogs[path.stem] = {}
     if "en" not in catalogs:
         raise SystemExit(f"no en.json in {LOCALES_DIR}")
     return catalogs
@@ -211,13 +229,39 @@ def generated_files() -> dict[Path, str]:
     return outputs
 
 
+def _committed_text(path: Path) -> str:
+    """Read generated output, tolerating corrupt best-effort locale bytes."""
+    if not path.exists():
+        return ""
+    try:
+        return path.read_text(encoding="utf-8")
+    except UnicodeError as exc:
+        if not is_best_effort_locale(path.stem):
+            raise
+        relative = path.relative_to(REPO_ROOT)
+        print(
+            f"::warning file={relative}::best-effort locale output is not "
+            f"valid UTF-8 and will be treated as stale: {exc}",
+            file=sys.stderr,
+        )
+        return ""
+
+
 def check() -> int:
     """Exit 1 naming every derived file that no longer matches the canon."""
     stale: list[str] = []
     for path, content in generated_files().items():
-        committed = path.read_text(encoding="utf-8") if path.exists() else ""
+        committed = _committed_text(path)
         if committed != content:
-            stale.append(str(path.relative_to(REPO_ROOT)))
+            relative = str(path.relative_to(REPO_ROOT))
+            if is_best_effort_locale(path.stem):
+                print(
+                    f"::warning file={relative}::best-effort locale output is "
+                    "out of sync; run python scripts/generate_locales.py to refresh it",
+                    file=sys.stderr,
+                )
+            else:
+                stale.append(relative)
             diff = difflib.unified_diff(
                 committed.splitlines()[:20],
                 content.splitlines()[:20],
@@ -239,7 +283,7 @@ def check() -> int:
 def write() -> int:
     changed = 0
     for path, content in generated_files().items():
-        if not path.exists() or path.read_text(encoding="utf-8") != content:
+        if _committed_text(path) != content:
             path.write_text(content, encoding="utf-8", newline="\n")
             changed += 1
             print(f"wrote {path.relative_to(REPO_ROOT)}")

scripts/translate_locales.py

@@ -17,6 +17,10 @@
   from the tool definitions via ``scripts/extract_tools.py``)
 - ``custom_components/ha_mcp_tools/translations/<code>.json``
 
+Locales listed in ``BEST_EFFORT_LOCALES`` are deliberately excluded from both
+authored surfaces. They remain hand-editable and use the normal English
+fallback without consuming translation quota or making this job fail.
+
 The engine is one function (``_call_gemini``): the Gemini API free tier,
 keyed by ``GEMINI_API_KEY``, with ``GEMINI_MODEL`` / ``GEMINI_API_URL``
 overrides for any Gemini-compatible endpoint. The fallback when the engine is
@@ -78,6 +82,7 @@
     _PLACEHOLDER_RE,
     _TAG_LIKE_RE,
 )
+from ha_mcp.settings_ui._locale_policy import is_best_effort_locale  # noqa: E402
 
 LOCALES_DIR = REPO_ROOT / "src" / "ha_mcp" / "settings_ui" / "locales"
 COMPONENT_DIR = REPO_ROOT / "custom_components" / "ha_mcp_tools" / "translations"
@@ -241,7 +246,11 @@ def _changed_keys(module: Any) -> dict[str, set[str]]:
 
 
 def _target_locales() -> list[str]:
-    return sorted(p.stem for p in LOCALES_DIR.glob("*.json") if p.stem != "en")
+    return sorted(
+        p.stem
+        for p in LOCALES_DIR.glob("*.json")
+        if p.stem != "en" and not is_best_effort_locale(p.stem)
+    )
 
 
 def _flatten(value: Any, prefix: str = "") -> dict[str, str]:
@@ -389,7 +398,7 @@ def _plan_component(plan: Plan, changed: dict[str, set[str]]) -> None:
     changed_component = changed.get(COMPONENT_SURFACE, set())
     progress = _progress_load()
     for path in sorted(COMPONENT_DIR.glob("*.json")):
-        if path.stem == "en":
+        if path.stem == "en" or is_best_effort_locale(path.stem):
             continue
         flat = _flatten(_load_json(path))
         loc_changed = {

src/ha_mcp/settings_ui/AGENTS.md

@@ -38,6 +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`.
 
 ## Gotchas (read before editing)
 

src/ha_mcp/settings_ui/_i18n.py

@@ -8,11 +8,16 @@
 from __future__ import annotations
 
 import json
+import logging
 import re
 from collections import Counter
 from pathlib import Path
 from typing import Any
 
+from ._locale_policy import is_best_effort_locale
+
+_LOGGER = logging.getLogger(__name__)
+
 DEFAULT_LOCALE = "en"
 LOCALE_COOKIE = "ha_mcp_locale"
 LOCALES_DIR = Path(__file__).parent / "locales"
@@ -87,6 +92,48 @@ def _validate_tools(value: Any, *, context: str) -> dict[str, dict[str, str]]:
     return result
 
 
+def _load_catalog_file(path: Path) -> dict[str, Any]:
+    """Load and validate one catalog without coupling it to its siblings."""
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise ImportError(f"Invalid settings UI locale catalog: {path}") from exc
+    if not isinstance(raw, dict):
+        raise ValueError(f"Locale catalog {path} must contain a JSON object")
+
+    meta = raw.get("meta")
+    if not isinstance(meta, dict):
+        raise ValueError(f"Locale catalog {path} must define a meta object")
+    native_name = meta.get("native_name")
+    direction = meta.get("dir", "ltr")
+    if not isinstance(native_name, str) or not native_name.strip():
+        raise ValueError(f"Locale catalog {path} needs meta.native_name")
+    if direction not in ("ltr", "rtl"):
+        raise ValueError(f"Locale catalog {path} meta.dir must be ltr or rtl")
+
+    unknown_sections = set(raw) - {"meta", "messages", "tool_groups", "tools"}
+    if unknown_sections:
+        raise ValueError(
+            f"Locale catalog {path} has unsupported sections: "
+            f"{sorted(unknown_sections)}"
+        )
+
+    return {
+        "meta": {"native_name": native_name, "dir": direction},
+        "messages": _validate_string_map(
+            raw.get("messages"), context=f"{path.name}.messages"
+        ),
+        "tool_groups": _validate_string_map(
+            raw.get("tool_groups"), context=f"{path.name}.tool_groups"
+        ),
+        "tools": _validate_tools(raw.get("tools"), context=f"{path.name}.tools"),
+    }
+
+
+def _warn_best_effort_catalog(locale: str, path: Path, exc: Exception) -> None:
+    _LOGGER.warning("Skipping best-effort locale %s from %s: %s", locale, path, exc)
+
+
 def load_catalogs(
     directory: Path = LOCALES_DIR, settings_html: Path = _SETTINGS_HTML
 ) -> dict[str, dict[str, Any]]:
@@ -106,47 +153,38 @@ def load_catalogs(
     for path in paths:
         locale = path.stem.lower().replace("_", "-")
         try:
-            raw = json.loads(path.read_text(encoding="utf-8"))
-        except (OSError, json.JSONDecodeError) as exc:
-            raise ImportError(f"Invalid settings UI locale catalog: {path}") from exc
-        if not isinstance(raw, dict):
-            raise ValueError(f"Locale catalog {path} must contain a JSON object")
-
-        meta = raw.get("meta")
-        if not isinstance(meta, dict):
-            raise ValueError(f"Locale catalog {path} must define a meta object")
-        native_name = meta.get("native_name")
-        direction = meta.get("dir", "ltr")
-        if not isinstance(native_name, str) or not native_name.strip():
-            raise ValueError(f"Locale catalog {path} needs meta.native_name")
-        if direction not in ("ltr", "rtl"):
-            raise ValueError(f"Locale catalog {path} meta.dir must be ltr or rtl")
-
-        unknown_sections = set(raw) - {"meta", "messages", "tool_groups", "tools"}
-        if unknown_sections:
-            raise ValueError(
-                f"Locale catalog {path} has unsupported sections: "
-                f"{sorted(unknown_sections)}"
-            )
-
-        catalogs[locale] = {
-            "meta": {"native_name": native_name, "dir": direction},
-            "messages": _validate_string_map(
-                raw.get("messages"), context=f"{path.name}.messages"
-            ),
-            "tool_groups": _validate_string_map(
-                raw.get("tool_groups"), context=f"{path.name}.tool_groups"
-            ),
-            "tools": _validate_tools(raw.get("tools"), context=f"{path.name}.tools"),
-        }
+            catalogs[locale] = _load_catalog_file(path)
+        except (ImportError, ValueError) as exc:
+            if not is_best_effort_locale(locale):
+                raise
+            _warn_best_effort_catalog(locale, path, exc)
 
     if DEFAULT_LOCALE not in catalogs:
         raise ImportError(
             f"The settings UI requires {DEFAULT_LOCALE}.json in {directory}"
         )
-    _validate_placeholder_parity(catalogs)
-    _validate_inline_markup(catalogs)
-    _validate_panel_links(catalogs, settings_html)
+
+    strict_catalogs = {
+        locale: catalog
+        for locale, catalog in catalogs.items()
+        if not is_best_effort_locale(locale)
+    }
+    _validate_placeholder_parity(strict_catalogs)
+    _validate_inline_markup(strict_catalogs)
+    _validate_panel_links(strict_catalogs, settings_html)
+
+    for locale in sorted(set(catalogs) - set(strict_catalogs)):
+        candidate = {
+            DEFAULT_LOCALE: catalogs[DEFAULT_LOCALE],
+            locale: catalogs[locale],
+        }
+        try:
+            _validate_placeholder_parity(candidate)
+            _validate_inline_markup(candidate)
+            _validate_panel_links(candidate, settings_html)
+        except ValueError as exc:
+            _warn_best_effort_catalog(locale, directory / f"{locale}.json", exc)
+            del catalogs[locale]
     return catalogs
 
 

src/ha_mcp/settings_ui/_locale_policy.py

@@ -0,0 +1,13 @@
+"""Maintenance policy for intentionally best-effort locale catalogs."""
+
+from __future__ import annotations
+
+# Klingon is a novelty translation maintained by hand. It must never consume
+# machine-translation quota or block delivery for supported localizations.
+BEST_EFFORT_LOCALES = frozenset({"tlh"})
+
+
+def is_best_effort_locale(locale: str) -> bool:
+    """Return whether ``locale`` is isolated from hard localization gates."""
+    normalized = locale.lower().replace("_", "-")
+    return normalized in BEST_EFFORT_LOCALES

src/ha_mcp/settings_ui/locales/README.md

@@ -24,6 +24,15 @@ Home Assistant language code names every file:
 - `homeassistant-addon/translations/<code>.yaml` (generated)
 - `homeassistant-addon-dev/translations/<code>.yaml` (generated)
 
+Klingon (`tlh`) is the one best-effort exception. Its catalogs may be edited
+manually and still ship, but the automatic translation planner never queues
+them. Missing strings use English fallback; invalid or stale Klingon catalogs
+produce warnings instead of failing CI or the daily locale sync. The runtime
+loader skips an invalid Klingon settings catalog, and the generator can project
+English into its add-on catalogs, so Klingon cannot prevent any other locale
+from loading or updating. All other language codes remain subject to every
+hard gate below.
+
 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;