Hermes Agent 源码解析 · 第 19 讲
Hermes Agent 源码解析 第 19 讲：国际化与多语言支持 基于 Hermes Agent v0.16.0 源码 · 2026-07-02 一、为什么需要国际化 Hermes Agent 是一个面向全球开发者的工具——从 CLI 到 Telegram/Discord 网关，从 TUI 到桌面应用，用户遍布世界各地。如果所有提示信息都是英文的，非英语用户的使用体验会大打折扣。 但 Hermes 的国际化策略 非常克制 ：它只翻译 Hermes 自身产生的 静态用户界面消息 （如审批提示、网关命令回复），而 不翻译 Agent 生成的回复、日志、工具输出或命令描述。这一设计选择背后有深刻的原因。 💡 设计哲学：薄切片（Thin Slice） 只翻译最高影响的静态字符串——审批提示、网关斜杠命令回复、重启排空通知。Agent 生成的内容、日志、工具输出保持英文。 二、i18n 模块架构总览 Hermes 的国际化系统集中在 agent/i18n.py （302 行），不依赖任何第三方 i18n 框架（如 Babel、gettext），而是用纯 Python + PyYAML 实现了一套轻量级翻译引擎。 用户调用 t("gateway.reset.header_default") 语言解析链 get_language() → 环境 → 配置 → 默认 目录加载 _load_catalog(lang) → YAML → 扁平化 键值查找 + 回退 t(key, lang, **kwargs) → 翻译结果 三、语言解析链：四级优先级 Hermes 的语言解析遵循严格的优先级链，确保测试、开发和生产环境都能正确获取用户语言偏好。 优先级 来源 说明 1（最高） t() 的 lang 参数 显式指定语言，覆盖一切 2 HERMES_LANGUAGE 环境变量 测试/快速切换用 3 config.yaml 的 display.language 用户配置，进程级缓存 4（默认） "en"（英文） 兜底默认值 📄 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 注意 _config_language_cached() 使用了 @lru_cache(maxsize=1) 装饰器——因为 t() 在热路径上调用（每次审批提示、每次网关回复），反复读取 YAML 配置会浪费性能。当配置变更时（如设置向导后），调用 reset_language_cache() 即可刷新。 四、语言别名系统：50+ 种输入映射到 16 种语言 Hermes 支持 16 种语言目录，但用户输入的语言标识可以非常灵活。系统内置了 _LANGUAGE_ALIASES 映射表，将自然语言名、BCP-47 区域标签、甚至非拉丁字符都映射到标准语言代码。 语言 支持别名 目录文件 简体中文 chinese, mandarin, zh-cn, zh-hans zh.yaml 繁体中文 zh-tw, zh-hk, traditional-chinese zh-hant.yaml 日语 japanese, jp, ja-jp ja.yaml 德语 german, deutsch, de-de, de-at de.yaml 西班牙语 spanish, español, es-mx, es-ar es.yaml 法语 french, français, fr-fr, fr-ca fr.yaml 乌克兰语 ukrainian, українська, ua uk.yaml 俄语 russian, русский, ru-ru ru.yaml…