fix(locales): salvage invalid runtime entries

Author: kingpanther13

src/ha_mcp/settings_ui/_i18n.py

@@ -92,7 +92,86 @@ def _validate_tools(value: Any, *, context: str) -> dict[str, dict[str, str]]:
     return result
 
 
-def _load_catalog_file(path: Path) -> dict[str, Any]:
+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 _warn_best_effort_entry(locale: str, entry: str, exc: Exception) -> None:
+    _LOGGER.warning(
+        "Ignoring invalid best-effort locale %s %s; using English fallback: %s",
+        locale,
+        entry,
+        exc,
+    )
+
+
+def _validate_best_effort_string_map(
+    value: Any,
+    *,
+    locale: str,
+    context: str,
+    entry_kind: str,
+) -> dict[str, str]:
+    """Drop invalid best-effort strings while preserving valid siblings."""
+    if value is None:
+        return {}
+    if not isinstance(value, dict):
+        raise ValueError(f"{context} must be an object")
+
+    result: dict[str, str] = {}
+    for key, text in value.items():
+        try:
+            result.update(_validate_string_map({key: text}, context=context))
+        except ValueError as exc:
+            _warn_best_effort_entry(locale, f"{entry_kind} {key!r}", exc)
+    return result
+
+
+def _validate_best_effort_tools(
+    value: Any, *, locale: str, context: str
+) -> dict[str, dict[str, str]]:
+    """Drop invalid best-effort tool fields while preserving valid siblings."""
+    if value is None:
+        return {}
+    if not isinstance(value, dict):
+        raise ValueError(f"{context} must be an object")
+
+    result: dict[str, dict[str, str]] = {}
+    for tool_name, tool_values in value.items():
+        if not isinstance(tool_name, str) or not isinstance(tool_values, dict):
+            exc = ValueError(f"{context} entries must be objects keyed by tool name")
+            _warn_best_effort_entry(locale, f"tool {tool_name!r}", exc)
+            continue
+
+        translated: dict[str, str] = {}
+        for field, field_value in tool_values.items():
+            if field not in ("title", "description"):
+                exc = ValueError(
+                    f"{context}.{tool_name} has unsupported field: {field!r}"
+                )
+                _warn_best_effort_entry(
+                    locale, f"tool {tool_name!r} field {field!r}", exc
+                )
+                continue
+            try:
+                validated = _validate_tools(
+                    {tool_name: {field: field_value}}, context=context
+                )
+            except ValueError as exc:
+                _warn_best_effort_entry(
+                    locale, f"tool {tool_name!r} field {field!r}", exc
+                )
+                continue
+            if field in validated[tool_name]:
+                translated[field] = validated[tool_name][field]
+        if translated:
+            result[tool_name] = translated
+    return result
+
+
+def _load_catalog_file(
+    path: Path, *, best_effort_locale: str | None = None
+) -> dict[str, Any]:
     """Load and validate one catalog without coupling it to its siblings."""
     try:
         raw = json.loads(path.read_text(encoding="utf-8"))
@@ -118,29 +197,39 @@ def _load_catalog_file(path: Path) -> dict[str, Any]:
             f"{sorted(unknown_sections)}"
         )
 
-    return {
-        "meta": {"native_name": native_name, "dir": direction},
-        "messages": _validate_string_map(
+    if best_effort_locale is None:
+        messages = _validate_string_map(
             raw.get("messages"), context=f"{path.name}.messages"
-        ),
-        "tool_groups": _validate_string_map(
+        )
+        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)
-
+        )
+        tools = _validate_tools(raw.get("tools"), context=f"{path.name}.tools")
+    else:
+        messages = _validate_best_effort_string_map(
+            raw.get("messages"),
+            locale=best_effort_locale,
+            context=f"{path.name}.messages",
+            entry_kind="message",
+        )
+        tool_groups = _validate_best_effort_string_map(
+            raw.get("tool_groups"),
+            locale=best_effort_locale,
+            context=f"{path.name}.tool_groups",
+            entry_kind="tool group",
+        )
+        tools = _validate_best_effort_tools(
+            raw.get("tools"),
+            locale=best_effort_locale,
+            context=f"{path.name}.tools",
+        )
 
-def _warn_best_effort_entry(locale: str, entry: str, exc: Exception) -> None:
-    _LOGGER.warning(
-        "Ignoring invalid best-effort locale %s %s; using English fallback: %s",
-        locale,
-        entry,
-        exc,
-    )
+    return {
+        "meta": {"native_name": native_name, "dir": direction},
+        "messages": messages,
+        "tool_groups": tool_groups,
+        "tools": tools,
+    }
 
 
 def _catalog_fragment(
@@ -236,7 +325,10 @@ def load_catalogs(
     for path in paths:
         locale = path.stem.lower().replace("_", "-")
         try:
-            catalogs[locale] = _load_catalog_file(path)
+            catalogs[locale] = _load_catalog_file(
+                path,
+                best_effort_locale=(locale if is_best_effort_locale(locale) else None),
+            )
         except (ImportError, ValueError) as exc:
             if not is_best_effort_locale(locale):
                 raise

tests/src/unit/test_settings_ui_i18n.py

@@ -234,6 +234,36 @@ def test_invalid_best_effort_message_falls_back_without_dropping_locale(
     assert "tlh message 'saved'" in caplog.text
 
 
+@pytest.mark.parametrize("invalid", ["", 7], ids=["blank", "non-string"])
+def test_invalid_best_effort_message_value_preserves_valid_siblings(
+    tmp_path: Path,
+    caplog: pytest.LogCaptureFixture,
+    invalid: object,
+) -> None:
+    _write_catalog(
+        tmp_path,
+        "en",
+        native_name="English",
+        messages={"invalid": "English fallback", "valid": "Valid"},
+    )
+    _write_catalog(
+        tmp_path,
+        "tlh",
+        native_name="tlhIngan Hol (Klingon)",
+        messages={"invalid": invalid, "valid": "Qapla'"},
+    )
+
+    with caplog.at_level(logging.WARNING, logger="ha_mcp.settings_ui._i18n"):
+        catalogs = load_catalogs(tmp_path)
+
+    assert catalogs["tlh"]["messages"] == {"valid": "Qapla'"}
+    assert build_payload("tlh", catalogs)["messages"] == {
+        "invalid": "English fallback",
+        "valid": "Qapla'",
+    }
+    assert "tlh message 'invalid'" in caplog.text
+
+
 def test_tool_placeholder_mismatch_is_rejected(tmp_path: Path) -> None:
     _write_catalog(
         tmp_path,
@@ -295,6 +325,40 @@ def test_invalid_best_effort_tool_field_falls_back_without_dropping_siblings(
     assert "tlh tool 'ha_example' field 'description'" in caplog.text
 
 
+def test_invalid_best_effort_tool_field_preserves_valid_siblings(
+    tmp_path: Path, caplog: pytest.LogCaptureFixture
+) -> None:
+    _write_catalog(
+        tmp_path,
+        "en",
+        native_name="English",
+        messages={},
+        tools={
+            "ha_example": {
+                "title": "Example",
+                "description": "English fallback",
+            }
+        },
+    )
+    _write_catalog(
+        tmp_path,
+        "tlh",
+        native_name="tlhIngan Hol (Klingon)",
+        messages={},
+        tools={"ha_example": {"title": "ghantoH", "description": 7}},
+    )
+
+    with caplog.at_level(logging.WARNING, logger="ha_mcp.settings_ui._i18n"):
+        catalogs = load_catalogs(tmp_path)
+
+    assert catalogs["tlh"]["tools"] == {"ha_example": {"title": "ghantoH"}}
+    assert build_payload("tlh", catalogs)["tools"]["ha_example"] == {
+        "title": "ghantoH",
+        "description": "English fallback",
+    }
+    assert "tlh tool 'ha_example' field 'description'" in caplog.text
+
+
 def test_unknown_text_direction_is_rejected(tmp_path: Path) -> None:
     """``meta.dir`` reaches the rendered ``<html dir>`` attribute verbatim.