Go 的 i18n 需组合 golang.org/x/text 与自定义 Localizer，解析 Accept-Language 要用 language.ParseAcceptLanguage，优先级应为 Cookie → URL query → Accept-Language → Default，YAML key 必须 ASCII 且全语言对齐，加载失败必须显式检查 error，模板函数 tr 应从 context 提取语言标签。

Go 的 golang.org/x/text 包不是开箱即用的 i18n 解决方案

直接用 golang.org/x/text 里的 message.printer 或 localizer，你会卡在“怎么动态加载翻译、怎么绑定 http 请求语言、怎么 fallback”上。它只提供底层翻译能力，不处理上下文、路由、http 头解析这些 web 场景刚需。

真正能落地的方案是组合：用 golang.org/x/text 做翻译核心，自己封装一层请求感知的 Localizer 结构体，并配合 http.Request 的 Accept-Language 解析（别信 req.Header.Get("Accept-Language") 直接切分——浏览器发来的值像 zh-CN,zh;q=0.9,en;q=0.8，得用 language.ParseAcceptLanguage 才能正确排序和权重处理）。

实操建议：

Golang Uber Dig

使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等

下载

• 定义一个全局 *localize.Localizer（来自 github.com/nicksnyder/go-i18n/v2/i18n 更省事，但若坚持原生，就自己 wrap x/text）
• 每个 HTTP handler 入口调用 parseAcceptLanguage(req) 得到最匹配的 language.Tag
• 把 tag 存进 context.WithValue(req.Context(), ctxKeyLang, tag)，后续中间件或 handler 可安全取用
• 避免在 init() 里硬编码语言列表；从文件加载时检查 en-US.yaml 和 zh-Hans.yaml 是否存在，缺失则 panic，别静默忽略

i18n.MustLoadMessageFile 加载失败不会报错，但后续 Localize 会 panic

用 github.com/nicksnyder/go-i18n/v2/i18n 时，i18n.MustLoadMessageFile 在文件不存在或 YAML 格式错误时直接 os.Exit(1)，适合启动期校验；但如果你用 i18n.LoadMessageFile（返回 error），却忘了检查 error，后续调用 localizer.Localize(&i18n.LocalizeConfig{...}) 就会 panic：“no message found for key”。

常见错误现象：panic: no message found for key "login.title" in language "zh-Hans"，其实是因为 zh-Hans.yaml 根本没加载成功，但代码没做 error 判断。

立即学习“go语言免费学习笔记（深入）”；

实操建议：

• 所有 i18n.LoadMessageFile 调用后必须 if err != nil { log.Fatal(err) }，不要吞掉
• YAML 文件里 key 必须是纯 ASCII 字符串（如 login.title），别用中文或空格作 key；value 可以是中文，但 key 是程序引用入口
• 不同语言文件结构必须严格一致：同一组 key 在 en-US.yaml 和 ja-JP.yaml 中都要存在，缺一个就会触发 fallback 到默认语言——但 fallback 行为依赖 localizer 初始化时传入的 DefaultLanguage，不是自动选 en

模板中嵌入翻译要避免重复传参，用 template.FuncMap 注入 tr 函数

如果每个 html/template 的 {{.Title}} 都改成 {{$.Tr "page.home.title"}}，就得在每次 tmpl.Execute(w, struct{ Tr func(string) string }) 里手动塞函数，耦合重、易漏。

更自然的做法是注册全局 template function：

func newTemplate() *template.Template {
	tmpl := template.New("").Funcs(template.FuncMap{
		"tr": func(key string, args ...interface{}) string {
			// 从 http.Request.Context() 提取 language.Tag
			// 调用 localizer.Localize(...)
			// 返回翻译后字符串
		},
	})
	return tmpl.ParseGlob("templates/*.html")
}

注意点：

• tr 函数内部不能直接访问 http.Request，必须从 template.Execute 传入的 data 中提取 context 或 tag；推荐把 *http.Request 作为 data 字段传入，再从中取 .Context
• 支持带参数的翻译，比如 {{ tr "user.welcome" .UserName }}，对应 YAML 里写 user.welcome: "欢迎 {{.Name}}！"，args 会自动注入到 LocalizeConfig.PluralCount 或 LocalizeConfig.TemplateData
• 别在 tr 里做语言解析——解析应前置到 middleware，tr 只负责查表和渲染

HTTP 中间件里设置语言时，Cookie 优先级应高于 Accept-Language

用户手动切换语言（如点击「中文」按钮）应该持久化，靠 Set-Cookie: lang=zh-Hans; Path=/ 实现。但很多实现把 Cookie 和 Accept-Language 当成互斥选项，导致用户点了中文后刷新页面又变回英文——因为中间件只读了 Accept-Language，没检查 Cookie。

正确顺序是：Cookie → URL query（如 ?lang=ja）→ Accept-Language → Default。其中 Cookie 和 query 用于显式覆盖，Accept-Language 是兜底自动识别。

实操建议：

• 中间件里先调 req.Cookie("lang")，若存在且是合法 tag（用 language.Parse 验证），就用它；否则再 parse Accept-Language
• URL query 参数（如 /login?lang=zh-Hans）应在中间件里统一处理并设回 Cookie，避免每次请求都带 query
• 别把语言信息存在 session（如 gorilla/sessions），增加存储依赖；Cookie 签名即可（http.SetCookie + secure/httpOnly 标志）
• 对 API 请求（Content-Type: application/json），可额外检查 X-App-Language header，方便移动端控制

语言切换不是加个下拉框就完事。真正麻烦的是 fallback 链路是否完整、模板函数能否拿到当前请求的语言上下文、YAML 键名是否全语言对齐、以及 Cookie 和 header 冲突时谁说了算——这些地方一漏，用户看到的就是英文 key 或 panic 页面。