Go go-i18n 找不到目标语言消息时怎样回退

我们平常在Go项目里接入go-i18n做多语言国际化的时候，如果找不到目标语言的对应消息，会自动触发内置的回退逻辑，也可以自己调整规则来适配业务的实际需要。

go-i18n 找不到目标语言消息时的回退流程是先按语言标识的前缀逐级匹配更泛的语言版本，再匹配你预先配置的兜底默认语言包，最后兜底返回消息的原始键名，你也可以自定义实现消息查找接口来修改整个回退逻辑。

我第一次把多语言资源接进 Go 服务时，最容易误判的是“没有目标语言文本”和“没有任何可用文本”其实不是一回事。go-i18n 找不到请求语言的 MessageID 时，会先尝试 Bundle 创建时指定的默认语言；如果默认语言也没有，再看 LocalizeConfig.DefaultMessage。关键是：回退出文本时，Localize 仍可能返回 MessageNotFoundErr，所以线上代码要同时处理字符串和 error。

官方地址：https://pkg.go.dev/github.com/nicksnyder/go-i18n/v2/i18n

最稳妥的做法是把英文或产品默认语言作为 Bundle 的兜底，把用户语言和 Accept-Language 交给 Localizer 匹配，再用 Localize 接住“有回退文本但带缺失错误”的状态；只有确认允许直接失败时，才使用 MustLocalize。

先判断 go-i18n 的回退链

这次排查我先把问题拆成三层：请求携带哪些语言偏好，匹配到的语言有没有这条消息，默认语言或显式默认消息是否有可用文本。NewLocalizer(bundle, langs...)只负责保存语言偏好；真正找消息时，go-i18n 会按照语言标签匹配结果查找 MessageID。

如果匹配到的语言缺少该消息，源码会继续查 Bundle 的默认语言。默认语言也没有时，传入 DefaultMessage 才能提供最后一份模板；两层都没有且未提供默认消息，就只能返回找不到消息的错误。这里的“回退”是消息来源回退，不是把任意语言字符串自动翻译成另一种语言。

把 Bundle 的默认语言设成第一层兜底

默认语言要在创建 Bundle 时明确指定，而且对应的消息文件要实际加载。下面的示例把英语作为默认语言，模拟用户偏好为法语；welcome.title只在英语资源中存在时，回退结果才有意义。

package main

import (
    "fmt"

    "github.com/nicksnyder/go-i18n/v2/i18n"
    "golang.org/x/text/language"
)

func main() {
    // English 是 Bundle 的默认语言，必须与已加载的资源保持一致。
    bundle := i18n.NewBundle(language.English)
    bundle.MustAddMessages(language.English, &i18n.Message{
        ID:    "welcome.title",
        Other: "Welcome back",
    })

    // 先按用户偏好查找 French，缺少消息时再回到 English。
    localizer := i18n.NewLocalizer(bundle, "fr-FR")
    text, err := localizer.Localize(&i18n.LocalizeConfig{
        MessageID: "welcome.title",
    })
    if err != nil {
        // 回退文本仍可展示；这里记录缺失，便于补齐翻译资源。
        fmt.Printf("fallback text=%q err=%v\\n", text, err)
    }
    fmt.Println(text)
}

这个结果要按“文本可用、资源不完整”来处理，而不是简单把 error 当成空字符串。实际项目中可以在日志或指标里记录缺失的语言和消息 ID，同时给用户展示默认语言内容。

用 Localize 接住回退文本和错误

官方实现的一个容易被忽略的细节是：目标语言缺少消息、但默认语言命中时，Localize 可以返回默认语言文本，同时携带 MessageNotFoundErr。这正适合运行时降级：页面先有内容，后台再补翻译。

如果默认语言文件也缺少消息，可以把产品默认文案放进 DefaultMessage。它不是“翻译结果”，而是没有任何消息文件命中时的最后模板。

config := &i18n.LocalizeConfig{
    MessageID: "checkout.pay",
    // 资源文件全部缺失时，使用这份稳定的产品默认文案。
    DefaultMessage: &i18n.Message{
        ID:    "checkout.pay",
        Other: "Pay now",
    },
}

text, err := localizer.Localize(config)
if err != nil {
    // 文本可能已经来自 Bundle 默认语言，错误表示目标语言资源仍缺失。
    var missing *i18n.MessageNotFoundErr
    if errors.As(err, &missing) {
        log.Printf("missing translation: language=%s id=%s", missing.Tag, missing.MessageID)
    }
}
render(text)

这里的判断顺序很重要：先决定是否有可展示的 text，再决定是否记录、采样或告警。对于关键业务按钮，还可以把缺失翻译当成发布门禁；对于非关键提示，通常让默认语言继续服务更合适。

两个容易混淆的边界

第一，MustLocalize 不是更强的回退策略。它只是调用 Localize 后在 error 不为空时 panic；如果你希望目标语言缺失时继续显示默认语言，就应该显式处理 Localize 的返回值。

第二，复数模板回退与语言回退是两件事。某个语言已经找到消息，但缺少对应复数形式时，go-i18n 可能尝试该消息的 Other 形式；这不会替你补齐另一种语言的翻译。资源发布时仍要检查每个语言的 MessageID 和需要的复数模板。

我现在会把下面三项放进发布后的观察清单：缺失语言和 MessageID 的计数、回退文本的展示比例、关键页面是否出现可读性下降。这样既不会因为一次非关键翻译缺口让请求失败，也不会让缺失资源长期没人处理。

相关问题

只传 DefaultMessage 就能替代默认语言吗？

不能完全替代。DefaultMessage 是找不到任何已加载消息时的最后模板；Bundle 默认语言仍负责提供真实的默认语言资源和语言规则。

为什么拿到文本还要处理 error？

因为目标语言缺失而回退到 Bundle 默认语言时，Localize 可能返回最佳努力文本并保留 MessageNotFoundErr，error 记录的是资源缺口。