💡 设计哲学：薄切片（Thin Slice）

只翻译最高影响的静态字符串——审批提示、网关斜杠命令回复、重启排空通知。Agent 生成的内容、日志、工具输出保持英文。

📄 agent/i18n.py (第 241-249 行)

def get_language() -> str:
    """Resolve the active language using env > config > default order."""
    env_lang = os.environ.get("HERMES_LANGUAGE")
    if env_lang:
        return _normalize_lang(env_lang)
    cfg_lang = _config_language_cached()
    if cfg_lang:
        return cfg_lang
    return DEFAULT_LANGUAGE

📄 agent/i18n.py (第 43-82 行)

SUPPORTED_LANGUAGES: tuple[str, ...] = (
    "en", "zh", "zh-hant", "ja", "de", "es", "fr", "tr", "uk",
    "af", "ko", "it", "ga", "pt", "ru", "hu",
)

_LANGUAGE_ALIASES: dict[str, str] = {
    "english": "en", "en-us": "en", "en-gb": "en",
    "chinese": "zh", "mandarin": "zh", "zh-cn": "zh",
    "zh-tw": "zh-hant", "zh-hk": "zh-hant",
    "japanese": "ja", "jp": "ja", "ja-jp": "ja",
    "german": "de", "deutsch": "de",
    "spanish": "es", "español": "es",
    "french": "fr", "français": "fr",
    "ukrainian": "uk", "українська": "uk",
    "korean": "ko", "한국어": "ko",
    "russian": "ru", "русский": "ru",
    # ... 共 50+ 条映射
}

📄 目录文件结构示例 (locales/en.yaml)

# 嵌套 YAML（人类可读）
approval:
  dangerous_header: "⚠️  DANGEROUS COMMAND: {description}"
  choose_long:     "      [o]nce  |  [s]ession  |  [a]lways  |  [d]eny"

gateway:
  model:
    switched:               "Model switched to `{model}`"
    provider_label:         "Provider: {provider}"
  agents:
    header:                 "🤖 **Active Agents & Tasks**"

📄 agent/i18n.py (第 200-207 行)

def _flatten_into(node: Any, prefix: str, out: dict[str, str]) -> None:
    if isinstance(node, dict):
        for key, value in node.items():
            child_key = f"{prefix}.{key}" if prefix else str(key)
            _flatten_into(value, child_key, out)
    elif isinstance(node, str):
        out[prefix] = node
    # Non-string, non-dict leaves are ignored -- catalogs are text-only.

目录位置解析：三级回退链

_locales_dir() 函数实现了三级回退链，确保在任何安装方式下都能找到语言目录：

📄 agent/i18n.py (第 252-293 行)

def t(key: str, lang: str | None = None, **format_kwargs: Any) -> str:
    target = _normalize_lang(lang) if lang else get_language()
    catalog = _load_catalog(target)
    value = catalog.get(key)

    if value is None and target != DEFAULT_LANGUAGE:
        # Fall through to English rather than showing a key path.
        value = _load_catalog(DEFAULT_LANGUAGE).get(key)

    if value is None:
        # Last-ditch: return the key itself. A broken catalog
        # should not crash anything; it just looks ugly.
        logger.debug("i18n miss: key=%r lang=%r", key, target)
        value = key

    if format_kwargs:
        try:
            return value.format(**format_kwargs)
        except (KeyError, IndexError, ValueError) as exc:
            logger.warning("i18n format failed: %s", exc)
            return value
    return value

📄 tests/agent/test_i18n.py (第 44-74 行)

@pytest.mark.parametrize("lang", [l for l in SUPPORTED_LANGUAGES if l != "en"])
def test_catalog_keys_match_english(lang: str):
    """Every non-English catalog must have exactly the same key set."""
    en_keys = set(_flatten(_load_raw("en")).keys())
    lang_keys = set(_flatten(_load_raw(lang)).keys())
    missing = en_keys - lang_keys
    extra = lang_keys - en_keys
    assert not missing, f"{lang}.yaml missing keys: {sorted(missing)}"
    assert not extra, f"{lang}.yaml has keys not in en.yaml: {sorted(extra)}"

@pytest.mark.parametrize("lang", list(SUPPORTED_LANGUAGES))
def test_catalog_placeholders_match_english(lang: str):
    """Every translated value must use the same {placeholder} tokens."""
    placeholder_re = re.compile(r"\{([a-zA-Z_][a-zA-Z0-9_]*)\}")
    for key, en_value in en_flat.items():
        en_placeholders = set(placeholder_re.findall(en_value))
        lang_placeholders = set(placeholder_re.findall(lang_flat.get(key, "")))
        assert en_placeholders == lang_placeholders

📄 config.yaml 配置示例

display:
  language: zh          # 简体中文
  # 支持: en, zh, zh-hant, ja, de, es, fr, tr, uk,
  #       af, ko, it, ga, pt, ru, hu
  # 未知值回退到 en

📄 环境变量方式

# 临时切换为日语
export HERMES_LANGUAGE=ja
hermes chat

# 或直接指定
HERMES_LANGUAGE=zh hermes tools

亮点

🔹 零外部依赖：不依赖 Babel/gettext，只用 PyYAML，减少安装包体积

🔹 三级回退：目标语言 → 英文 → 原始键，确保永不崩溃

🔹 50+ 别名映射：支持自然语言名、BCP-47 标签、非拉丁字符输入

🔹 进程级缓存：目录和配置都做了缓存，热路径不影响性能

🔹 目录一致性测试：强制所有语言目录与英文保持键一致

🔹 三级安装路径回退：Nix / pip wheel / 源码安装都能正确找到目录

不足

🔹 覆盖范围有限：只翻译静态消息，Agent 生成的内容仍是英文

🔹 无复数形式支持：没有 clDRule 或 nplurals 机制，复数通过占位符手动处理

🔹 无 RTL 支持：没有阿拉伯语/希伯来语等从右到左语言的目录

🔹 手动翻译维护：没有 CI 自动检测新键，需要开发者手动同步所有目录

📦 本讲核心文件

agent/i18n.py（302 行）— i18n 引擎

locales/（16 个 YAML 文件）— 语言目录

tests/agent/test_i18n.py（229 行）— 一致性测试

hermes_cli/config.py（display.language）— 语言配置