plugin_validate_locales.py 4.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112
  1. """``hermes plugins validate`` — language-pack checks (``provides_locales``).
  2. For every declared id the pack must ship ``locales/<id>.yaml`` that parses and is text-only (a number,
  3. list or null leaf is an error: ``t()`` would silently drop it). Keys the English catalogs do not have
  4. are a WARNING naming them — a pack written against a newer or older Hermes still installs, it just
  5. carries dead keys. Core keys come from the bundled ``locales/en.yaml``; TUI/Desktop keys from
  6. ``locales/_keys.tui.json`` / ``locales/_keys.desktop.json`` (exported by the TS packages' build
  7. scripts). When an export is absent the key check for that surface is skipped, never failed.
  8. """
  9. from __future__ import annotations
  10. import json
  11. import logging
  12. from pathlib import Path
  13. from typing import Any, Dict, List, Optional, Set
  14. from agent.i18n_layers import CORE_SURFACE, flatten, non_text_leaves, scan_locale_dir
  15. logger = logging.getLogger(__name__)
  16. _KEY_EXPORTS = {"tui": "_keys.tui.json", "desktop": "_keys.desktop.json"}
  17. def _bundled_locales_dir() -> Path:
  18. from agent.i18n import _locales_dir
  19. return _locales_dir()
  20. def reference_keys(surface: str) -> Optional[set[str]]:
  21. """English key set for *surface*: flattened ``en.yaml`` for core, the JSON export for tui/desktop.
  22. ``None`` when the reference is unavailable (the check is then skipped)."""
  23. locales = _bundled_locales_dir()
  24. try:
  25. if surface == CORE_SURFACE:
  26. from agent.i18n_layers import parse_locale_file
  27. return set(parse_locale_file(locales / "en.yaml"))
  28. export = locales / _KEY_EXPORTS[surface]
  29. if not export.is_file():
  30. return None
  31. data = json.loads(export.read_text(encoding="utf-8-sig"))
  32. keys = data.get("keys") if isinstance(data, dict) else data
  33. return {str(k) for k in keys} if isinstance(keys, list) else None
  34. except Exception as exc: # a broken reference is a Hermes bug, not the pack's
  35. logger.debug("i18n reference keys for %s unavailable: %s", surface, exc)
  36. return None
  37. def _load_document(path: Path) -> Any:
  38. import hermes_yaml as yaml
  39. with path.open("r", encoding="utf-8-sig") as handle:
  40. return yaml.safe_load(handle)
  41. def check_language_packs(report, manifest: dict, plugin_dir: Path) -> None:
  42. """Locale-pack admission checks; a no-op (single passing line) when nothing is declared."""
  43. from hermes_cli.plugins_manifest import parse_provides_locales
  44. raw = manifest.get("provides_locales")
  45. declared, _meta = parse_provides_locales(raw, str(manifest.get("name") or plugin_dir.name))
  46. if raw is None:
  47. return
  48. if not declared:
  49. report.add("locales", False, "provides_locales declares no valid language id (expected e.g. pl, pt-br)")
  50. return
  51. locales_dir = plugin_dir / "locales"
  52. found = scan_locale_dir(locales_dir)
  53. by_lang: dict[str, list] = {}
  54. for lang_id, surface, path in found:
  55. by_lang.setdefault(lang_id, []).append((surface, path))
  56. for lang_id in declared:
  57. files = by_lang.get(lang_id, [])
  58. if not any(surface == CORE_SURFACE for surface, _ in files):
  59. report.add(f"locale {lang_id}", False, f"provides_locales declares {lang_id!r} but locales/{lang_id}.yaml is missing")
  60. continue
  61. for surface, path in files:
  62. _check_locale_file(report, lang_id, surface, path)
  63. undeclared = sorted(set(by_lang) - set(declared))
  64. if undeclared:
  65. report.warn(f"locales/ ships {', '.join(undeclared)} not listed in provides_locales "
  66. "(loaded anyway; declare them so users can see the pack's languages)")
  67. def _check_locale_file(report, lang_id: str, surface: str, path: Path) -> None:
  68. label = f"locale {lang_id}" if surface == CORE_SURFACE else f"locale {lang_id}.{surface}"
  69. try:
  70. document = _load_document(path)
  71. except Exception as exc:
  72. report.add(label, False, f"{path.name} failed to parse: {exc}")
  73. return
  74. if document is None:
  75. document = {}
  76. if not isinstance(document, dict):
  77. report.add(label, False, f"{path.name} must be a mapping, got {type(document).__name__}")
  78. return
  79. bad_leaves = non_text_leaves(document)
  80. if bad_leaves:
  81. report.add(label, False, f"{path.name} has non-text value(s) at: {', '.join(sorted(bad_leaves))}")
  82. return
  83. flat = flatten(document)
  84. reference = reference_keys(surface)
  85. if reference is None:
  86. report.add(label, True, f"{path.name}: {len(flat)} key(s); no {surface} key reference available, key check skipped")
  87. return
  88. unknown = sorted(set(flat) - reference)
  89. if unknown:
  90. report.warn(f"{path.name}: {len(unknown)} key(s) not in the English {surface} catalog (ignored at runtime): "
  91. + ", ".join(unknown))
  92. report.add(label, True, f"{path.name}: {len(flat)} key(s), {len(flat) - len(unknown)} match the English {surface} catalog")
  93. __all__ = ["check_language_packs", "reference_keys"]