go-i18n/v2是唯一能撑住线上流量的方案,因其支持动态切语言、CLDR复数、JSON热加载、RTL适配,且Bundle全局单例、Localizer每请求新建;手写map或fmt.Sprintf拼接必崩于复数词序RTL,x/text/message不支持运行时切换。

go-i18n/v2 是唯一能撑住线上流量的方案,其他方式(比如手写 map、拼接 fmt.Sprintf、用 golang.org/x/text/message)在复数、词序、RTL 或区域变体上必然出错,且无法热更新。
为什么 localizer.Localize 总返回空或原始 key
这不是 bug,是配置没对齐规范导致的静默失败。常见原因包括:
• 文件名必须是 active.zh-CN.json,zh.json、zh_CN.json、cn.json 全部被忽略
• JSON 结构必须严格为 {"welcome": {"description": "greeting", "translation": "欢迎"}},缺 description 字段或把 translation 写成 msg 都会跳过整条
• bundle.ParseFS 只加载前缀为 active. 的文件,路径错(如用 os.DirFS("./locales") 但文件实际在 ./i18n/active.zh-CN.json)就根本找不到
• 没显式调 bundle.LoadMessageFile 或 bundle.ParseFS:v2 不自动扫描目录,不调等于没加载
• bundle.NewLocalizer 传入的 language.Tag 没在已加载资源里注册,也不会 fallback,直接返回空
Accept-Language 解析不能靠字符串切分
浏览器发来的 Accept-Language: zh-CN,zh;q=0.9,en-US;q=0.8,en;q=0.7 是带权重、可嵌套、需标准化的语言标签序列,不是普通逗号分隔字符串。
• 必须用 language.ParseAcceptLanguage(r.Header.Get("Accept-Language")) 得到有序 []language.Tag
• 白名单要定义为 supported := []language.Tag{language.Chinese, language.English},别用字符串切片
为跨境电子商务生成多语言、SEO 优化的产品描述。支持英语、西班牙语、俄语和阿拉伯语,并针对不同搜索引擎(Google / Bing、Yandex、中东市场)进行专项 SEO 优化。适用于以下场景:用户需为国际市场创建符合 SEO 规范的产品文案、批量生成产品描述,或针对特定搜索引擎及区域用户偏好优化内容。
• 匹配必须用 matcher := language.NewMatcher(supported) 初始化一次,再调 matcher.Match(candidate);zh-Hans 和 zh-CN 语义不同,但 matcher 能归一化识别
• 解析结果建议存进 req.Context(),避免每次 handler 都重复调用——内部有 map 查找开销
Bundle 和 Localizer 的生命周期怎么管
• Bundle 必须全局单例,启动时一次性加载所有 active.*.json 文件,用 i18n.NewBundle(language.English) 创建,再调 ParseFS 或 LoadMessageFile
• Localizer 绝不能复用或缓存:每个 HTTP 请求都应调 bundle.NewLocalizer(langTag),它轻量、线程安全,复用反而会导致并发错译
• 模板渲染时也要为每次调用单独构造 Localizer 实例,别在模板外提前 new 好传进去
• 别用 golang.org/x/text/message 替代:它的 message.NewPrinter 一旦创建,language.Tag 就固化了,改请求头或 context 完全无效
真正容易被忽略的是:所有校验和匹配都发生在运行时,但错误不抛 panic、不打日志、不报错——只静默返回空字符串或原始 key。这意味着你得在启动时就验证文件名、结构、路径、白名单是否全部对齐,而不是等用户访问才发现界面全是英文 key。
golang免费学习笔记(深入):立即使用
在学习笔记中,你将探索golang的核心概念和高级技巧!










