推荐使用 github.com/nicksnyder/go-i18n/v2，因其支持按请求新建 Localizer、热加载 JSON、CLDR 复数、RTL 适配及严格资源校验；而 gin-gonic/contrib/i18n 依赖静态注册、无标准化解析、无 fallback 机制且仅支持 INI 格式，生产中易失效。
github.com/gin-gonic/contrib/i18n 或更现代的替代方案（如 github.com/nicksnyder/go-i18n/v2 + 自定义中间件），直接用 i18n.Handler() 会遇到语言切换失效、locale 丢失、热加载不支持等实际问题。
为什么 i18n.Handler() 在生产中容易失效
该中间件依赖全局 i18n.SetMessage 静态注册，所有语言文件在启动时一次性加载进内存，无法动态增删语言；更关键的是它从请求头 Accept-Language 解析 locale 时，未做标准化（比如把 zh 映射为 zh-CN），也未提供 fallback 机制。一旦客户端发来 Accept-Language: zh，而你只注册了 zh-CN.ini，i18n.Locale(c) 就返回空字符串，后续 i18n.GetMessage 直接 panic。
- 它不校验 locale 是否已注册，失败时静默返回空，而不是 fallback 到默认语言
- 所有消息文件必须是 INI 格式，不支持 JSON/TOML，维护成本高
- 无上下文绑定，无法按用户 session 或 token 指定语言（仅限 header）
- 无法在 handler 中临时覆盖 locale，比如管理后台强制切英文
go-i18n/v2 + Gin 上下文注入的推荐做法
用 go-i18n/v2 替代老旧的 contrib/i18n，它支持多格式、热重载、fallback chain 和强类型 message ID。核心是把 *i18n.Localizer 注入到 *gin.Context，而非依赖中间件全局挂载。
- 初始化时用
i18n.NewBundle(language.English)创建 bundle，再调用bundle.RegisterUnmarshalFunc("yaml", yaml.Unmarshal) - 按需加载语言资源：
bundle.MustLoadMessageFile("locales/en-US.yaml")，支持子目录和通配符 - 写一个轻量中间件，在
c.Request.Header.Get("Accept-Language")解析后，调用bundle.Localize(&i18n.LocalizeConfig{...})得到*i18n.Localizer，存入c.Set("localizer", loc) - handler 中统一用
loc := c.MustGet("localizer").(*i18n.Localizer)，再调loc.Localize(&i18n.LocalizeConfig{MessageID: "user_not_found"})
这样既保留 Gin 的 context 生命周期控制，又避免全局状态污染，还能在特定接口里手动指定 locale：loc := bundle.NewLocalizer(lang)。
语言标识如何可靠提取与 fallback
不能只信 Accept-Language 原值。真实场景中，iOS 客户端可能发 zh-Hans-CN，Web 前端可能带 lang=ja 查询参数，管理后台需要 X-Admin-Lang: en 头。应按优先级链提取：
立即学习“go语言免费学习笔记（深入）”；
- 先查
c.GetHeader("X-App-Lang")（App 约定头） - 再查
c.DefaultQuery("lang", "")（兼容旧 H5） - 最后 fallback 到
accept-language解析，用language.ParseAcceptLanguage（来自golang.org/x/text/language）做标准化匹配 - 所有结果都过一遍
bundle.FindAvailableLocale，找不到就硬 fallback 到en-US
别用字符串 strings.Contains 匹配 locale，language 包的 Match 方法才真正支持 BCP 47 语义（比如 zh 能匹配 zh-CN、zh-TW）。
模板渲染与 API 响应的多语言分离处理
HTML 模板里用 {{.T "page_title"}} 这类自定义 func 很方便，但 JSON API 必须结构化返回错误/提示。不要在响应体里拼接翻译后的字符串，而应返回 machine-readable code + args：
{
"code": "USER_NOT_FOUND",
"args": {"id": "123"},
"message": "User not found"
}
前端或 SDK 根据 code 查本地化资源。后端只负责在 message 字段填当前 locale 下的兜底文案（用于日志、调试、降级）。这样前后端解耦，翻译更新无需发版。
最易被忽略的一点：HTTP 状态码不该随语言变。无论返回中文还是英文提示，404 Not Found 的 status code 和 reason phrase 必须保持标准，否则代理、CDN、监控系统会误判。
