| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112 |
- """``hermes plugins validate`` — language-pack checks (``provides_locales``).
- For every declared id the pack must ship ``locales/<id>.yaml`` that parses and is text-only (a number,
- list or null leaf is an error: ``t()`` would silently drop it). Keys the English catalogs do not have
- are a WARNING naming them — a pack written against a newer or older Hermes still installs, it just
- carries dead keys. Core keys come from the bundled ``locales/en.yaml``; TUI/Desktop keys from
- ``locales/_keys.tui.json`` / ``locales/_keys.desktop.json`` (exported by the TS packages' build
- scripts). When an export is absent the key check for that surface is skipped, never failed.
- """
- from __future__ import annotations
- import json
- import logging
- from pathlib import Path
- from typing import Any, Dict, List, Optional, Set
- from agent.i18n_layers import CORE_SURFACE, flatten, non_text_leaves, scan_locale_dir
- logger = logging.getLogger(__name__)
- _KEY_EXPORTS = {"tui": "_keys.tui.json", "desktop": "_keys.desktop.json"}
- def _bundled_locales_dir() -> Path:
- from agent.i18n import _locales_dir
- return _locales_dir()
- def reference_keys(surface: str) -> Optional[set[str]]:
- """English key set for *surface*: flattened ``en.yaml`` for core, the JSON export for tui/desktop.
- ``None`` when the reference is unavailable (the check is then skipped)."""
- locales = _bundled_locales_dir()
- try:
- if surface == CORE_SURFACE:
- from agent.i18n_layers import parse_locale_file
- return set(parse_locale_file(locales / "en.yaml"))
- export = locales / _KEY_EXPORTS[surface]
- if not export.is_file():
- return None
- data = json.loads(export.read_text(encoding="utf-8-sig"))
- keys = data.get("keys") if isinstance(data, dict) else data
- return {str(k) for k in keys} if isinstance(keys, list) else None
- except Exception as exc: # a broken reference is a Hermes bug, not the pack's
- logger.debug("i18n reference keys for %s unavailable: %s", surface, exc)
- return None
- def _load_document(path: Path) -> Any:
- import hermes_yaml as yaml
- with path.open("r", encoding="utf-8-sig") as handle:
- return yaml.safe_load(handle)
- def check_language_packs(report, manifest: dict, plugin_dir: Path) -> None:
- """Locale-pack admission checks; a no-op (single passing line) when nothing is declared."""
- from hermes_cli.plugins_manifest import parse_provides_locales
- raw = manifest.get("provides_locales")
- declared, _meta = parse_provides_locales(raw, str(manifest.get("name") or plugin_dir.name))
- if raw is None:
- return
- if not declared:
- report.add("locales", False, "provides_locales declares no valid language id (expected e.g. pl, pt-br)")
- return
- locales_dir = plugin_dir / "locales"
- found = scan_locale_dir(locales_dir)
- by_lang: dict[str, list] = {}
- for lang_id, surface, path in found:
- by_lang.setdefault(lang_id, []).append((surface, path))
- for lang_id in declared:
- files = by_lang.get(lang_id, [])
- if not any(surface == CORE_SURFACE for surface, _ in files):
- report.add(f"locale {lang_id}", False, f"provides_locales declares {lang_id!r} but locales/{lang_id}.yaml is missing")
- continue
- for surface, path in files:
- _check_locale_file(report, lang_id, surface, path)
- undeclared = sorted(set(by_lang) - set(declared))
- if undeclared:
- report.warn(f"locales/ ships {', '.join(undeclared)} not listed in provides_locales "
- "(loaded anyway; declare them so users can see the pack's languages)")
- def _check_locale_file(report, lang_id: str, surface: str, path: Path) -> None:
- label = f"locale {lang_id}" if surface == CORE_SURFACE else f"locale {lang_id}.{surface}"
- try:
- document = _load_document(path)
- except Exception as exc:
- report.add(label, False, f"{path.name} failed to parse: {exc}")
- return
- if document is None:
- document = {}
- if not isinstance(document, dict):
- report.add(label, False, f"{path.name} must be a mapping, got {type(document).__name__}")
- return
- bad_leaves = non_text_leaves(document)
- if bad_leaves:
- report.add(label, False, f"{path.name} has non-text value(s) at: {', '.join(sorted(bad_leaves))}")
- return
- flat = flatten(document)
- reference = reference_keys(surface)
- if reference is None:
- report.add(label, True, f"{path.name}: {len(flat)} key(s); no {surface} key reference available, key check skipped")
- return
- unknown = sorted(set(flat) - reference)
- if unknown:
- report.warn(f"{path.name}: {len(unknown)} key(s) not in the English {surface} catalog (ignored at runtime): "
- + ", ".join(unknown))
- report.add(label, True, f"{path.name}: {len(flat)} key(s), {len(flat) - len(unknown)} match the English {surface} catalog")
- __all__ = ["check_language_packs", "reference_keys"]
|