universal-translator

项目背景与痛点

在 Go 生态里，只要用过 go-playground/validator，你就会遇到一个很现实的问题：校验逻辑写得再漂亮，最终抛出来的错误信息仍是英文硬编码，例如 Key: 'User.Age' Error:Field validation for 'Age' failed on the 'gte' tag。要把这种信息变成“年龄必须大于等于 18”，开发者通常有三种选择：直接字符串替换，维护一份 JSON 或 YAML 文案表，或者引入 go-i18n 这类重型框架。

前两种做法看似简单，但一旦遇到复数变化，立刻就会变得复杂。英文只需要区分 one 和 other，俄语有 4 种复数形式，阿拉伯语有 6 种，威尔士语甚至按基数与序数分别定义规则。手动维护这些规则，就等于自行搭建一个 CLDR 子集。而 go-i18n 又太重：它要加载文件、处理消息 ID、支持模板与复数语法，还必须绑定一个 bundle 生命周期。

universal-translator 的定位非常明确：它不做完整的 i18n 框架，只做“带 CLDR 复数规则、可回退、可模板化的字符串翻译器”。它把复杂度压在两个点上：从 CLDR 生成的 locale 规则包，以及轻量的模板渲染。剩下的事交给调用方。

核心技术揭秘

整个项目可以拆成三层。

第一层是规则层，来自同组织的 go-playground/locales。每个语言都是一个独立 Go 包（locales/zh、locales/ru……），由 CLDR 数据离线生成。包里固化的是该语言的复数分类集合、CardinalPluralRule、OrdinalPluralRule、PluralRuleIndexes 等函数。这种“一语言一包”的设计很 Go：编译期按需链接，不用为没引入的语言付出体积代价，也不需要运行时解析任何数据文件。

第二层是门面层 UniversalTranslator。它持有主 locale 与一串 fallback locale，负责 GetTranslator(locale)、FindTranslator(acceptLanguage) 这类查找，并在目标语言缺失时沿回退链降级。FindTranslator 对 Accept-Language 头做 q 值排序后逐级匹配：先精确匹配 zh-Hant，再退到主语言 zh，最后落到默认 locale。

第三层是渲染层 translator，内部是一张 map[string]*translation。Add(key, text, override) 把文案编译成 Go text/template，对外暴露的是 {0}、{1} 这样的位置占位符；T(key, params...) 负责普通翻译，C(key, num, params...) 负责基数复数，O、R 分别对应序数与范围表达。

复数的处理机制很直接：拿数字交给 locale 包的规则函数，得到 zero/one/two/few/many/other 中的某一个分类，再把它拼到原 key 后面，形成 apples_one、apples_other，去 map 里找对应模板。所以使用方必须为每种可能的复数分类分别注册文案，缺了哪一类就取不到。

从设计模式看，它把“语言规则”抽象成策略对象注入进来，translator 只依赖 locale.Translator 接口；UniversalTranslator 则是典型的门面加回退链。整体没有全局状态、没有反射黑魔法，读起来几乎就是一段可执行的规格说明。

功能亮点与差异

杀手锏一：复数规则来自 CLDR，而非手写。 与 go-i18n 需要自己在消息文件里写 plural 语法不同，这里的复数判断完全由生成好的语言包完成，调用方只需按分类注册文案。序数和范围复数（R）的支持，在同类轻量库中并不常见。

杀手锏二：零运行时资源文件。 没有 .po、.json、.toml 加载，没有 watcher，没有 bundle 初始化顺序问题。翻译编译进二进制，部署即完成。

杀手锏三：与 validator 的天然耦合。 validator 的翻译包全部基于本库构建，{0}、{1} 的参数顺序就是字段名、参数、比较值。这种约定让“校验错误本地化”变成一次 Add 调用就能搞定的事。

对比 nicksnyder/go-i18n，本库的短板也很清楚：不支持 ICU MessageFormat 的选择分支、嵌套、富文本；没有热更新与外部文案文件；没有对模板缺失的自动纠错。

应用场景与落地建议

它最适合的场景是：服务端 API 的校验错误与固定提示文案本地化，尤其是已经在用 go-playground/validator 的项目；以及 CLI 工具的多语言输出。

生产落地时，有几点值得注意：

• 注册阶段一次性完成。 Add 是写 map 的操作，不应在请求处理中并发调用。建议在 init 或启动装配阶段把所有语言、所有 key 注册完，之后只读。
• key 命名要成体系。 建议直接用 validator 的 tag 作 key，并统一加前缀避免与业务文案冲突；复数场景务必把该语言所有可能的分类都补齐，否则 C 会落空。
• 参数占位符不可随意增删。 文案模板与调用方的参数位置强绑定，改文案时删掉 {0} 是安全的，但插入新占位符会改变语义。
• 回退链的顺序需要设计。 ut.New(primary, fallbacks...) 的第一个参数是默认语言。把 en 放在末尾做兜底，比把它放在首位更符合“用户优先”的预期。
• 别指望它做全局 i18n。 日期、货币、数字格式化本库不负责，交给 golang.org/x/text 更合适。

综合评价

优点：体积极小、无外部资源依赖、复数规则正确且覆盖 CLDR、API 少到一小时内能读完、与 validator 生态无缝衔接。它把一个狭窄问题解决得很干净。

缺点：能力边界窄得几乎锋利——只做字符串模板，遇到 ICU 风格的嵌套复数、性别变化就无能；文案必须编译进二进制，改一句话就要重新构建；文档偏薄，复数 key 的拼接规则藏在源码里；单一维护者、更新节奏慢，长期演进有风险。

一句话总结：它是一个恰到好处的底层库，适合当你只需要“把一句话翻译对，并让复数不出错”时使用；如果你要的是一套完整的本地化体系，它是一个组件，而不是答案。