ha-mcp-dev 7.13.0.dev1968__tar.gz → 7.13.0.dev1971__tar.gz

{ha_mcp_dev-7.13.0.dev1968 → ha_mcp_dev-7.13.0.dev1971}/MANIFEST.in

@@ -3,4 +3,5 @@ include LICENSE
 include src/ha_mcp/settings_ui/settings.html
 include src/ha_mcp/settings_ui/settings.js
 include src/ha_mcp/settings_ui/settings.css
+recursive-include src/ha_mcp/settings_ui/locales *.json README.md
 recursive-include src/ha_mcp/resources *.md *.json

{ha_mcp_dev-7.13.0.dev1968/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.13.0.dev1971}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.13.0.dev1968
+Version: 7.13.0.dev1971
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT

{ha_mcp_dev-7.13.0.dev1968 → ha_mcp_dev-7.13.0.dev1971}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.13.0.dev1968"
+version = "7.13.0.dev1971"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's
@@ -65,7 +65,7 @@ package-dir = {"" = "src", "tests" = "tests"}
 packages = { find = { where = ["src", "."], include = ["ha_mcp*", "tests"] } }
 
 [tool.setuptools.package-data]
-ha_mcp = ["py.typed", "_pypi_marker", "settings_ui/settings.html", "settings_ui/settings.js", "settings_ui/settings.css", "resources/skills-vendor/**/*"]
+ha_mcp = ["py.typed", "_pypi_marker", "settings_ui/settings.html", "settings_ui/settings.js", "settings_ui/settings.css", "settings_ui/locales/*.json", "settings_ui/locales/README.md", "resources/skills-vendor/**/*"]
 
 [tool.mypy]
 python_version = "3.13"

{ha_mcp_dev-7.13.0.dev1968 → ha_mcp_dev-7.13.0.dev1971}/src/ha_mcp/settings_ui/__init__.py

@@ -33,6 +33,12 @@ from ._handlers_server import (
 )
 from ._handlers_theme import build_theme_handlers
 from ._handlers_tools import build_tools_handlers
+from ._i18n import (
+    LOCALE_COOKIE,
+    build_payload,
+    select_locale,
+    serialize_payload,
+)
 from ._persistence import (
     _atomic_write_json,
     _get_backup_settings_override_path,
@@ -136,11 +142,14 @@ except OSError as exc:  # pragma: no cover - packaging guard
 
 # The settings page HTML lives in settings.html, extracted the same way as
 # settings.js / settings.css (a real file for editor/HTML tooling). It carries
-# three substitution markers — two filled once at import, one per request:
+# six substitution markers — two filled once at import, four per request:
 #   __HA_MCP_CSS__         -> settings.css contents (inside <style>)
 #   __HA_MCP_JS__          -> settings.js contents (inside <script>)
 #   __HA_MCP_THEME_PREFS__ -> per-request server-seeded theme prefs JSON,
 #                             substituted in _render_settings_html()
+#   __HA_MCP_I18N__        -> selected merged translation catalog JSON
+#   __HA_MCP_LANG__        -> selected locale code for the html lang attribute
+#   __HA_MCP_DIR__         -> selected catalog text direction (ltr / rtl)
 # Same import-time packaging dependency as settings.js/css (wheel package-data,
 # MANIFEST.in, PyInstaller datas) and the same OSError guard -- but this loader
 # raises RuntimeError, not the ImportError that settings.js/css raise.
@@ -158,7 +167,14 @@ except OSError as exc:  # pragma: no cover - packaging guard
 # versa) — str.replace() silently no-ops on an absent token, which would ship a
 # page missing its CSS, JS, or server-seeded theme prefs. Assert all three
 # markers are present.
-for _sentinel in ("__HA_MCP_CSS__", "__HA_MCP_JS__", "__HA_MCP_THEME_PREFS__"):
+for _sentinel in (
+    "__HA_MCP_CSS__",
+    "__HA_MCP_JS__",
+    "__HA_MCP_THEME_PREFS__",
+    "__HA_MCP_I18N__",
+    "__HA_MCP_LANG__",
+    "__HA_MCP_DIR__",
+):
     if _sentinel not in _settings_html_template:
         raise RuntimeError(
             f"settings.html is out of sync: sentinel {_sentinel} not found. "
@@ -307,8 +323,8 @@ def _build_visibility_handlers(*, data_dir: Path) -> dict[str, Any]:
     }
 
 
-def _render_settings_html() -> str:
-    """Substitute the persisted theme prefs into the served settings page.
+def _render_settings_html(request: Request | None = None) -> str:
+    """Substitute theme preferences and the request-selected locale.
 
     The ``server-prefs`` head script carries a ``data-prefs`` attribute
     with a placeholder token; request-time substitution keeps
@@ -316,19 +332,44 @@ def _render_settings_html() -> str:
     body itself parseable at rest for the script-surface tests). Values
     are sanitized enums / vetted hex colors and the JSON is HTML-escaped,
     so the attribute cannot break out of its quoting context.
+
+    Locale priority is a user-selected cookie, the Home Assistant language
+    hint supplied by the embedded panel, the browser's Accept-Language header,
+    then English. Only the selected merged catalog is embedded in the page.
     """
-    payload = html.escape(
+    theme_payload = html.escape(
         json.dumps(_load_theme_prefs(), separators=(",", ":")), quote=True
     )
-    rendered = _SETTINGS_HTML.replace("__HA_MCP_THEME_PREFS__", payload, 1)
-    if "__HA_MCP_THEME_PREFS__" in rendered:
+    locale = select_locale(
+        cookie_locale=request.cookies.get(LOCALE_COOKIE) if request else None,
+        ha_language=request.query_params.get("ha_lang") if request else None,
+        accept_language=request.headers.get("accept-language") if request else None,
+    )
+    locale_payload = build_payload(locale)
+    i18n_payload = serialize_payload(locale_payload)
+    direction = locale_payload["dir"]
+    rendered = (
+        _SETTINGS_HTML.replace("__HA_MCP_THEME_PREFS__", theme_payload, 1)
+        .replace("__HA_MCP_I18N__", i18n_payload, 1)
+        .replace("__HA_MCP_LANG__", locale, 1)
+        .replace("__HA_MCP_DIR__", direction, 1)
+    )
+    if any(
+        sentinel in rendered
+        for sentinel in (
+            "__HA_MCP_THEME_PREFS__",
+            "__HA_MCP_I18N__",
+            "__HA_MCP_LANG__",
+            "__HA_MCP_DIR__",
+        )
+    ):
         # str.replace silently no-ops when the placeholder vanishes in a
         # refactor; the unit contract test catches that in CI, this line
-        # catches it loudly in a live deployment instead of quietly
-        # serving a page without server-side prefs.
+        # catches it loudly in a live deployment instead of quietly serving a
+        # page without server-side preferences or translations.
         logger.error(
-            "server-prefs placeholder was not substituted; theme prefs "
-            "will not survive fresh origins"
+            "settings-page request placeholder was not substituted; theme "
+            "preferences or translations may be unavailable"
         )
     return rendered
 
@@ -363,11 +404,11 @@ def build_settings_handlers(
     so the served page is identical regardless of transport.
     """
 
-    async def _root_page(_: Request) -> HTMLResponse:
-        return HTMLResponse(_render_settings_html())
+    async def _root_page(request: Request) -> HTMLResponse:
+        return HTMLResponse(_render_settings_html(request))
 
-    async def _settings_page(_: Request) -> HTMLResponse:
-        return HTMLResponse(_render_settings_html())
+    async def _settings_page(request: Request) -> HTMLResponse:
+        return HTMLResponse(_render_settings_html(request))
 
     handlers: dict[str, Any] = {
         "root_page": _root_page,

ha_mcp_dev-7.13.0.dev1971/src/ha_mcp/settings_ui/_i18n.py

@@ -0,0 +1,244 @@
+"""Translation catalog loading and locale selection for the settings UI.
+
+Catalogs are discovered from ``locales/*.json`` so adding a language does not
+require Python or JavaScript changes.  English is the canonical fallback;
+individual translations may be incomplete and safely inherit missing values.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+DEFAULT_LOCALE = "en"
+LOCALE_COOKIE = "ha_mcp_locale"
+LOCALES_DIR = Path(__file__).parent / "locales"
+
+_PLACEHOLDER_RE = re.compile(r"\{([a-zA-Z_][a-zA-Z0-9_]*)\}")
+
+
+def _validate_string_map(value: Any, *, context: str) -> dict[str, str]:
+    """Return a validated ``str -> str`` catalog section."""
+    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():
+        if not isinstance(key, str) or not isinstance(text, str):
+            raise ValueError(f"{context} must contain only string keys and values")
+        result[key] = text
+    return result
+
+
+def _validate_tools(value: Any, *, context: str) -> dict[str, dict[str, str]]:
+    """Return validated optional per-tool UI translations."""
+    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):
+            raise ValueError(f"{context} entries must be objects keyed by tool name")
+        translated: dict[str, str] = {}
+        for field in ("title", "description"):
+            field_value = tool_values.get(field)
+            if field_value is None:
+                continue
+            if not isinstance(field_value, str):
+                raise ValueError(f"{context}.{tool_name}.{field} must be a string")
+            translated[field] = field_value
+        unknown = set(tool_values) - {"title", "description"}
+        if unknown:
+            raise ValueError(
+                f"{context}.{tool_name} has unsupported fields: {sorted(unknown)}"
+            )
+        result[tool_name] = translated
+    return result
+
+
+def load_catalogs(directory: Path = LOCALES_DIR) -> dict[str, dict[str, Any]]:
+    """Load and validate every JSON translation catalog in ``directory``."""
+    catalogs: dict[str, dict[str, Any]] = {}
+    try:
+        paths = sorted(directory.glob("*.json"))
+    except OSError as exc:  # pragma: no cover - packaging guard
+        raise ImportError(
+            f"Unable to enumerate settings UI locales at {directory}"
+        ) from exc
+
+    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"),
+        }
+
+    if DEFAULT_LOCALE not in catalogs:
+        raise ImportError(
+            f"The settings UI requires {DEFAULT_LOCALE}.json in {directory}"
+        )
+    _validate_placeholder_parity(catalogs)
+    return catalogs
+
+
+def _validate_placeholder_parity(catalogs: dict[str, dict[str, Any]]) -> None:
+    """Reject translations that drop or invent ``{name}`` placeholders."""
+    english_messages = catalogs[DEFAULT_LOCALE]["messages"]
+    english_tools = catalogs[DEFAULT_LOCALE]["tools"]
+    for locale, catalog in catalogs.items():
+        if locale == DEFAULT_LOCALE:
+            continue
+        for key, translated in catalog["messages"].items():
+            source = english_messages.get(key)
+            if source is None:
+                continue
+            source_fields = set(_PLACEHOLDER_RE.findall(source))
+            translated_fields = set(_PLACEHOLDER_RE.findall(translated))
+            if source_fields != translated_fields:
+                raise ValueError(
+                    f"Locale {locale} message {key!r} has placeholders "
+                    f"{sorted(translated_fields)}, expected {sorted(source_fields)}"
+                )
+        for tool_name, translated_tool in catalog["tools"].items():
+            source_tool = english_tools.get(tool_name, {})
+            for field, translated in translated_tool.items():
+                source = source_tool.get(field)
+                if source is None:
+                    continue
+                source_fields = set(_PLACEHOLDER_RE.findall(source))
+                translated_fields = set(_PLACEHOLDER_RE.findall(translated))
+                if source_fields != translated_fields:
+                    raise ValueError(
+                        f"Locale {locale} tool {tool_name!r} field {field!r} "
+                        f"has placeholders {sorted(translated_fields)}, expected "
+                        f"{sorted(source_fields)}"
+                    )
+
+
+CATALOGS = load_catalogs()
+
+
+def normalize_locale(
+    value: str | None, catalogs: dict[str, dict[str, Any]] = CATALOGS
+) -> str | None:
+    """Resolve a locale or regional locale to a supported catalog code."""
+    if not value:
+        return None
+    candidate = value.strip().lower().replace("_", "-")
+    if candidate in catalogs:
+        return candidate
+    base = candidate.split("-", 1)[0]
+    return base if base in catalogs else None
+
+
+def _accept_language_candidates(header: str | None) -> list[str]:
+    """Return Accept-Language values ordered by descending quality."""
+    if not header:
+        return []
+    candidates: list[tuple[float, int, str]] = []
+    for index, item in enumerate(header.split(",")):
+        parts = [part.strip() for part in item.split(";")]
+        language = parts[0]
+        quality = 1.0
+        for part in parts[1:]:
+            if part.startswith("q="):
+                try:
+                    quality = float(part[2:])
+                except ValueError:
+                    quality = 0.0
+        if language and language != "*" and quality > 0:
+            candidates.append((quality, -index, language))
+    candidates.sort(reverse=True)
+    return [language for _, _, language in candidates]
+
+
+def select_locale(
+    *,
+    cookie_locale: str | None = None,
+    ha_language: str | None = None,
+    accept_language: str | None = None,
+    catalogs: dict[str, dict[str, Any]] = CATALOGS,
+) -> str:
+    """Choose locale: explicit cookie, HA hint, browser header, then English."""
+    for value in (cookie_locale, ha_language):
+        if selected := normalize_locale(value, catalogs):
+            return selected
+    for value in _accept_language_candidates(accept_language):
+        if selected := normalize_locale(value, catalogs):
+            return selected
+    return DEFAULT_LOCALE
+
+
+def build_payload(
+    locale: str, catalogs: dict[str, dict[str, Any]] = CATALOGS
+) -> dict[str, Any]:
+    """Build a single merged catalog payload for the rendered page."""
+    selected_locale = normalize_locale(locale, catalogs) or DEFAULT_LOCALE
+    english = catalogs[DEFAULT_LOCALE]
+    selected = catalogs[selected_locale]
+
+    tools: dict[str, dict[str, str]] = {
+        name: dict(values) for name, values in english["tools"].items()
+    }
+    for name, values in selected["tools"].items():
+        tools.setdefault(name, {}).update(values)
+
+    return {
+        "locale": selected_locale,
+        "dir": selected["meta"]["dir"],
+        "messages": {**english["messages"], **selected["messages"]},
+        "tool_groups": {**english["tool_groups"], **selected["tool_groups"]},
+        "tools": tools,
+        "languages": [
+            {
+                "code": code,
+                "native_name": catalog["meta"]["native_name"],
+                "dir": catalog["meta"]["dir"],
+            }
+            for code, catalog in sorted(catalogs.items())
+        ],
+    }
+
+
+def serialize_payload(payload: dict[str, Any]) -> str:
+    """Serialize JSON safely for an inline ``application/json`` script."""
+    return (
+        json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
+        .replace("&", "\\u0026")
+        .replace("<", "\\u003c")
+        .replace(">", "\\u003e")
+    )

ha_mcp_dev-7.13.0.dev1971/src/ha_mcp/settings_ui/locales/README.md

@@ -0,0 +1,18 @@
+# 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.