如何在 Go 中实现结构体校验的国际化提示？

在 Go 语言的世界里，处理结构体校验的国际化，其实有不少容易被忽略的细节。很多项目做到一半，发现错误提示语言混了、字段名显示不对，才回过头来补课。今天咱们把这事儿彻底聊透，直接上干货。

用 go-playground/validator 绑定语言环境

Go 标准库本身不提供结构体字段级别的国际化校验支持，所以基本得靠第三方库来搞定。目前最成熟的组合就是 go-playground/validator 和它的官方翻译器 ut。这里的关键点，不是“怎么加翻译”，而是“怎么保证每一个 validate 调用都能感知到当前请求的语言环境”。

一个很常见的错误是，在全局初始化一个 ut.translator 实例后直接复用，结果在高并发场景下，不同的请求语言混在了一起。原因很简单——ut.translator 实例不是并发安全的，必须按请求进行隔离。

实际操作中，可以这样做：

• 在 HTTP middleware 中解析 Accept-Language 头或者路由参数（比如 /zh-CN/users），拿到语言标签（如 zh-CN、en-US）。
• 从预先注册好的 ut.UniversalTranslator 实例中，调用 GetTranslator(lang) 拿到对应语言的 ut.Translator 实例。
• 把这个实例注入到请求上下文（context.WithValue）里，或者直接传入校验函数。
• 最后，调用 validate.StructCtx(ctx, obj) 时，内部需要从 ctx 中提取 translator，并把它传给 Errs.Translate。

每种语言都需要单独注册翻译规则

同一个校验失败提示，比如 required，在不同语言下的文本内容是截然不同的。但 go-playground/validator 不会自动为你加载任何翻译规则——你得手动注册。一旦漏掉了某一种语言的注册，系统就会静默 fallback 到英文原提示，而且不报错，排查起来相当头疼。

有几个常见的坑需要警惕：

• 只注册了 zh，但请求头带的是 zh-CN，翻译会失败。
• 注册时用了 ut.New() 但没链式调用 .Register...，导致 translator 实例没有绑定翻译规则。
• 翻译模板里误写成 {{.FieldName}}（正确写法是 {{.Field}}），导致字段名无法替换。

这里给一个注册中文提示的示例：

err := ut.RegisterTranslation("zh", validateV10, func(ut ut.Translator) error {
    return ut.Add("required", "{0} 不能为空", true)
}, func(ut ut.Translator, fe validator.FieldError) string {
    t, _ := ut.T("required", fe.Field())
    return t
})

自定义校验器的错误信息也得走 translator

当你用 validate.RegisterValidation 添加自定义规则（比如校验手机号格式）时，它返回的错误默认是硬编码的字符串，不会被 Translate 处理。你必须显式调用 ut.T，并且确保这个 ut.Translator 和结构体校验用的是同一个语言实例。

典型的写法思路：

• 在自定义验证函数中，从 validator.ValidationErrors 的 Translate 方法拿不到自定义错误。所以要么改用 validator.StructLevel，要么直接传入 translator 实例。
• 避免在验证函数里 new 一个新的 ut.Translator，应该从外部传入（例如通过 validator.WithContext 注入）。
• 自定义的错误 key（比如 phone_format）必须和 RegisterTranslation 里注册的 key 严格一致。

HTTP 响应中不要直接返回 err.Error()

结构体校验失败返回的是 validator.ValidationErrors 类型，它虽然实现了 Error() 方法，但这个方法返回的是英文的 debug 信息（包含 struct 字段路径、具体值和 tag），完全不适合直接抛给前端展示。一旦你这么做了，中文用户就会看到英文字段名和英文提示。

正确的做法是：

• 断言类型：if errs, ok := err.(validator.ValidationErrors); ok { ... }
• 调用 errs.Translate(translator)，得到一个 map[string]string，其中 key 是字段名（如 "Name"），value 是翻译后的提示（如 "姓名不能为空"）。
• 如果你需要更细粒度的控制（比如区分 required 和 min=2），可以用 errs.ForEach 遍历每一个 FieldError，再调用 fe.Translate(translator)。

还有一个容易忽略的点：Translate 返回的 map key 默认是 Go 字段名（Name），不是 JSON key（name）。如果前端期望用 name 作为 key，你就得自己映射一次，比如查一下 json:"name" 这个 tag。