| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281 |
- """Lightweight i18n for Hermes' static user-facing strings (approval prompts, gateway replies, CLI, tips).
- Catalogs are flat dotted-key mappings resolved through layers, top first:
- 1. plugin language packs (``PluginContext.register_locale``; last registered wins) — ``agent.i18n_layers``
- 2. the user overlay ``$HERMES_HOME/locales/<lang>.yaml`` of the current profile home
- 3. the bundled ``locales/<lang>.yaml``
- 4. the same chain for ``en``
- 5. the bare key
- Every layer may be partial. Language resolution: explicit ``lang=`` > ``HERMES_LANGUAGE`` >
- ``display.language`` > ``en``; any id that some layer supplies is accepted, so a pack-only language
- (``pl``) works the moment its plugin loads. ``t()`` is a hot path: one cached merged dict per
- ``(home, lang)``, invalidated by :func:`reset_language_cache` (which every pack registration calls).
- """
- from __future__ import annotations
- import logging
- import os
- import threading
- from functools import lru_cache
- from pathlib import Path
- from typing import Any
- from agent import i18n_layers
- from agent.i18n_languages import language_options
- logger = logging.getLogger(__name__)
- # Bundled catalogs (compat: tests and the parity check iterate this). ``supported_languages()`` is the
- # live set including overlay and pack languages.
- SUPPORTED_LANGUAGES: tuple[str, ...] = (
- "en", "zh", "zh-hant", "ja", "de", "es", "fr", "tr", "uk",
- "af", "ko", "it", "ga", "pt", "ru", "hu", "ar",
- )
- DEFAULT_LANGUAGE = "en"
- # Natural aliases so "chinese" / "zh-CN" / "jp" hit the right catalog instead of
- # silently falling back to English. Bare "chinese" defaults to Simplified;
- # Taiwan/HK/Macau tags route to the distinct Traditional catalog. pt-br shares
- # the pt catalog unless a pack supplies a real pt-br one (a supplied id always wins over an alias).
- _LANGUAGE_ALIASES: dict[str, str] = {
- "english": "en", "en-us": "en", "en-gb": "en",
- "chinese": "zh", "mandarin": "zh", "zh-cn": "zh", "zh-hans": "zh", "zh-sg": "zh",
- "traditional-chinese": "zh-hant", "traditional_chinese": "zh-hant",
- "zh-tw": "zh-hant", "zh-hk": "zh-hant", "zh-mo": "zh-hant",
- "japanese": "ja", "jp": "ja", "ja-jp": "ja",
- "german": "de", "deutsch": "de", "de-de": "de", "de-at": "de", "de-ch": "de",
- "spanish": "es", "español": "es", "espanol": "es", "es-es": "es", "es-mx": "es", "es-ar": "es",
- "french": "fr", "français": "fr", "france": "fr", "fr-fr": "fr", "fr-be": "fr", "fr-ca": "fr", "fr-ch": "fr",
- "ukrainian": "uk", "ukrainisch": "uk", "українська": "uk", "uk-ua": "uk", "ua": "uk",
- "turkish": "tr", "türkçe": "tr", "tr-tr": "tr",
- "afrikaans": "af", "af-za": "af",
- "korean": "ko", "한국어": "ko", "ko-kr": "ko",
- "italian": "it", "italiano": "it", "it-it": "it", "it-ch": "it",
- "irish": "ga", "gaeilge": "ga", "ga-ie": "ga",
- "portuguese": "pt", "português": "pt", "portugues": "pt",
- "pt-pt": "pt", "pt-br": "pt", "brazilian": "pt", "brasileiro": "pt",
- "russian": "ru", "русский": "ru", "ru-ru": "ru",
- "hungarian": "hu", "magyar": "hu", "hu-hu": "hu",
- "arabic": "ar", "العربية": "ar",
- "ar-sa": "ar", "ar-eg": "ar", "ar-ae": "ar", "ar-ma": "ar", "ar-dz": "ar",
- }
- # (home, lang) -> merged catalog (packs over overlay over bundled). home -> supported tuple.
- _catalog_cache: dict[tuple[str, str], dict[str, str]] = {}
- _supported_cache: dict[str, tuple[str, ...]] = {}
- _catalog_lock = threading.Lock()
- def _locales_dir() -> Path:
- """Locale dir: ``HERMES_BUNDLED_LOCALES`` (sealed packaging, e.g. Nix) if it exists, else ``<repo-root>/locales``.
- The source path is returned even when missing so ``_load_bundled`` can log
- the path it looked at rather than raise.
- """
- override = os.getenv("HERMES_BUNDLED_LOCALES", "").strip()
- if override and Path(override).is_dir():
- return Path(override)
- if override:
- logger.warning(
- "HERMES_BUNDLED_LOCALES points to a non-directory path (%s); "
- "falling back to bundled/source locale resolution", override,
- )
- return Path(__file__).resolve().parent.parent / "locales"
- def _current_home() -> str:
- from hermes_constants import get_hermes_home
- return str(get_hermes_home())
- def supported_languages(home: str | None = None) -> tuple[str, ...]:
- """Every language some layer supplies for the current profile home: bundled ∪ user overlay ∪ plugin
- packs, ``en`` first then sorted. Cached until :func:`reset_language_cache`."""
- home = home or _current_home()
- with _catalog_lock:
- cached = _supported_cache.get(home)
- if cached is not None:
- return cached
- langs = set(SUPPORTED_LANGUAGES) | i18n_layers.layered_languages(home)
- result = (DEFAULT_LANGUAGE, *sorted(langs - {DEFAULT_LANGUAGE}))
- with _catalog_lock:
- _supported_cache[home] = result
- return result
- @lru_cache(maxsize=4)
- def _bundled_surfaces(locales_dir: str) -> frozenset[tuple[str, str]]:
- """``(lang, surface)`` for every bundled ``locales/<lang>[.<surface>].yaml``. Keyed by directory so a
- ``HERMES_BUNDLED_LOCALES`` switch re-scans; cleared with the other layer views by
- :func:`reset_language_cache`."""
- return frozenset((lang, surface) for lang, surface, _path in i18n_layers.scan_locale_dir(Path(locales_dir)))
- def language_surfaces(home: str | None = None) -> dict[str, tuple[str, ...]]:
- """Per language, the surfaces some layer has strings for (bundled ∪ user overlay ∪ plugin packs), in
- ``SURFACES`` order. An overlay file or pack that loaded no strings (empty, comment-only, unparseable)
- does not count. A renderer that bundles its own catalog for a language does not need this; for any
- other language a missing surface means that renderer would show English."""
- home = home or _current_home()
- layered = {(lang, surface) for lang, surface in i18n_layers.overlay_surfaces(home) | i18n_layers.pack_surfaces()
- if i18n_layers.overlay_layer(home, lang, surface) or i18n_layers.pack_layer(lang, surface)}
- pairs = _bundled_surfaces(str(_locales_dir())) | layered
- found: dict[str, set[str]] = {}
- for lang, surface in pairs:
- found.setdefault(lang, set()).add(surface)
- return {lang: tuple(s for s in i18n_layers.SURFACES if s in surfaces) for lang, surfaces in found.items()}
- def resolve_language_id(value: Any, home: str | None = None) -> str | None:
- """Canonical supported id for a user-supplied value (code, alias, regional tag), or ``None`` when no
- layer supplies it — the validation ``hermes config set display.language`` runs."""
- key = i18n_layers.normalize_language_id(value)
- if not key:
- return None
- supported = supported_languages(home)
- if key in supported:
- return key
- alias = _LANGUAGE_ALIASES.get(key)
- if alias in supported:
- return alias
- base = key.split("-", 1)[0] # strip region suffix
- return base if base in supported else None
- def _normalize_lang(value: Any, home: str | None = None) -> str:
- """Map a user-supplied value to a supported code (any layer), else the default."""
- return resolve_language_id(value, home) or DEFAULT_LANGUAGE
- def _load_bundled(lang: str) -> dict[str, str]:
- """One bundled locale YAML flattened to dotted keys (empty dict on any failure — never crashes)."""
- path = _locales_dir() / f"{lang}.yaml"
- if not path.is_file():
- logger.debug("i18n catalog missing for %s at %s", lang, path)
- return {}
- try:
- return i18n_layers.parse_locale_file(path)
- except Exception as exc:
- logger.warning("Failed to load i18n catalog %s: %s", path, exc)
- return {}
- def _flatten_into(node: Any, prefix: str, out: dict[str, str]) -> None:
- """Flatten a nested mapping into ``out`` (text leaves only)."""
- i18n_layers.flatten(node, prefix, out)
- def _load_catalog(lang: str, home: str | None = None) -> dict[str, str]:
- """Merged catalog for ``lang`` in ``home`` (packs > overlay > bundled); cached per (home, lang)."""
- home = home or _current_home()
- key = (home, lang)
- with _catalog_lock:
- cached = _catalog_cache.get(key)
- if cached is not None:
- return cached
- merged = _load_bundled(lang)
- merged.update(i18n_layers.overlay_layer(home, lang))
- merged.update(i18n_layers.pack_layer(lang))
- with _catalog_lock:
- _catalog_cache[key] = merged
- return merged
- def surface_catalog(lang: str, surface: str = i18n_layers.CORE_SURFACE) -> dict[str, str]:
- """What ``i18n.catalog`` serves for one surface: packs > overlay > bundled ``locales/<lang>.<surface>.yaml``.
- The core surface omits the bundled layer (the Python renderer already has it); the TUI ships only an
- English catalog in-tree, so its bundled translations live in ``locales/<lang>.tui.yaml`` and ride
- along here."""
- lang = _normalize_lang(lang)
- merged: dict[str, str] = {}
- if surface != i18n_layers.CORE_SURFACE:
- merged.update(_load_bundled(f"{lang}.{surface}"))
- merged.update(i18n_layers.surface_catalog(_current_home(), lang, surface))
- return merged
- @lru_cache(maxsize=8)
- def _config_language_cached(hermes_home: str) -> str | None:
- """``display.language`` from config.yaml, read once per profile home (``t()`` is a hot path).
- Keyed by home so a multiplexed gateway serving several profiles doesn't freeze the first
- profile's language for every other profile."""
- try:
- from hermes_cli.config import load_config_readonly
- lang = (load_config_readonly().get("display") or {}).get("language")
- return _normalize_lang(lang, hermes_home) if lang else None
- except Exception as exc:
- logger.debug("Could not read display.language from config: %s", exc)
- return None
- def _config_language() -> str | None:
- return _config_language_cached(_current_home())
- def reset_language_cache() -> None:
- """Invalidate cached language resolution, merged catalogs and every layer view (call after
- ``save_config`` changes ``display.language``, after a pack registers/unregisters, or after editing
- an overlay file)."""
- _config_language_cached.cache_clear()
- _bundled_surfaces.cache_clear()
- with _catalog_lock:
- _catalog_cache.clear()
- _supported_cache.clear()
- i18n_layers.clear_cache()
- def _resolve_language(home: str) -> str:
- from agent.secret_scope import UnscopedSecretError, get_secret
- try:
- env_lang = get_secret("HERMES_LANGUAGE")
- except UnscopedSecretError:
- env_lang = os.environ.get("HERMES_LANGUAGE") # unscoped default-profile path: environ IS its own value
- return _normalize_lang(env_lang, home) if env_lang else _config_language_cached(home) or DEFAULT_LANGUAGE
- def get_language() -> str:
- """Resolve the active language using env > config > default order. ``HERMES_LANGUAGE`` is a
- per-profile ``.env`` value, so it is read through the secret scope: under multiplexing a raw
- environ read would impose the default profile's language on every other profile."""
- return _resolve_language(_current_home())
- def t(key: str, lang: str | None = None, **format_kwargs: Any) -> str:
- """Translate a dotted catalog key to the active (or explicit ``lang``) language.
- ``format_kwargs`` are applied with ``str.format``. Falls back to English,
- then to the bare key; a format failure returns the unformatted string.
- """
- home = _current_home()
- target = _normalize_lang(lang, home) if lang else _resolve_language(home)
- value = _load_catalog(target, home).get(key)
- if value is None and target != DEFAULT_LANGUAGE:
- value = _load_catalog(DEFAULT_LANGUAGE, home).get(key)
- if value is None:
- logger.debug("i18n miss: key=%r lang=%r", key, target)
- value = key
- if not format_kwargs:
- return value
- try:
- return value.format(**format_kwargs)
- except (KeyError, IndexError, ValueError) as exc:
- logger.warning("i18n format failed for key=%r lang=%r kwargs=%r: %s", key, target, format_kwargs, exc)
- return value
- __all__ = [
- "DEFAULT_LANGUAGE",
- "SUPPORTED_LANGUAGES",
- "get_language",
- "language_options",
- "language_surfaces",
- "reset_language_cache",
- "resolve_language_id",
- "supported_languages",
- "surface_catalog",
- "t",
- ]
|