Go x/text/message SetString 怎样登记翻译消息

我第一次把 Go 服务的提示语做成多语言时，最容易混淆的是“登记翻译”和“读取翻译”其实是两件事。message.SetString 负责把某个语言标签、消息键和翻译文本登记进默认 catalog；真正输出时，再用 message.NewPrinter 按请求语言取出它。把这条边界拆开，代码就不会变成到处拼接字符串。

官方文档：https://pkg.go.dev/golang.org/x/text/message

最稳妥的写法是：先用稳定的消息键登记每种语言的文本，检查 SetString 返回的 error；请求到来后创建对应语言的 Printer，并给原文保留可用的回退路径。

我先把 SetString 当成登记入口

SetString 的签名是 SetString(tag language.Tag, key string, msg string) error。三个参数分别是目标语言、消息键和该语言的文本。它写入的是 message.DefaultCatalog，所以不需要先手动创建一个 catalog 才能开始试用。

消息键建议表达稳定含义，不要直接把中文句子当成唯一身份。这样文案变动时，调用方仍然只依赖同一个键；同一个英文单词在名词、动词场景下含义不同，也可以用 archive(noun)、archive(verb) 这样的键拆开。

package main

import (
    "fmt"

    "golang.org/x/text/language"
    "golang.org/x/text/message"
)

func registerMessages() error {
    // 用稳定键登记不同语言的同一条业务消息，避免调用处散落硬编码文本。
    entries := []struct {
        tag language.Tag
        key string
        msg string
    }{
        {language.Chinese, "welcome.message", "欢迎回来，%s"},
        {language.English, "welcome.message", "Welcome back, %s"},
    }

    for _, entry := range entries {
        // SetString 写入默认 catalog；返回错误时让启动阶段尽早暴露配置问题。
        if err := message.SetString(entry.tag, entry.key, entry.msg); err != nil {
            return fmt.Errorf("登记翻译 %q: %w", entry.key, err)
        }
    }
    return nil
}

这里的经验是把登记动作集中在启动阶段或专门的初始化模块里。虽然 API 允许调用方随时登记，但运行期间修改共享目录会让问题定位变得困难；如果翻译来自外部资源，最好先解析和整理，再统一调用登记函数。

消息键比原文更适合作为长期接口

登记时的 key 会参与后续查找。若调用处直接写中文原文，文案调整、标点改变或同词异义都会同时改变查找键。工程上更容易维护的做法是用 account.welcome、order.pending 这类稳定键，并在需要保留原文时用 message.Key 提供独立的 fallback。

还要注意，SetString 只登记字符串模板，它不是参数渲染器。模板里可以保留类似 %s 的格式占位符，输出时交给 Printer 的 Printf 或 Sprintf 处理。登记阶段负责“这个语言对应哪段文本”，请求阶段负责“把参数放进去”。

func registerOrderMessages() error {
    // 名词和动作使用不同键，防止同一个英文词在不同语境中共用翻译。
    messages := []struct {
        tag language.Tag
        key string
        msg string
    }{
        {language.Chinese, "archive(noun)", "归档"},
        {language.English, "archive(noun)", "archive"},
        {language.Chinese, "archive(verb)", "归档订单"},
        {language.English, "archive(verb)", "archive order"},
    }

    for _, item := range messages {
        // 任何一条登记失败都返回，避免目录只完成一半却继续提供服务。
        if err := message.SetString(item.tag, item.key, item.msg); err != nil {
            return err
        }
    }
    return nil
}

用 Printer 按语言读取，并保留原文回退

读取时先把用户偏好或请求头整理成 language.Tag，再创建 Printer。官方文档中的 Printer 是面向语言的格式化 I/O，接口形态接近 fmt；格式字符串会作为键查找翻译。因此，登记时使用的键必须和输出时传入的键保持一致。

func welcome(tag language.Tag, name string) string {
    // Printer 绑定本次请求的语言，避免把语言选择散落到每一次格式化调用里。
    printer := message.NewPrinter(tag)

    // Key 的第一个参数用于查找翻译，第二个参数是找不到时使用的原文。
    return printer.Sprintf(message.Key("welcome.message", "Welcome back, %s"), name)
}

对照关系可以这样记：SetString 写目录，NewPrinter 选语言，Key 提供可读的查找键和回退文本。某个语言没有登记对应消息时，不应该把空字符串当成成功结果；把原文作为 fallback，至少能让页面继续表达业务含义。

我会把全局登记和请求读取分成两层

一个小程序可以直接使用默认 catalog，但在长期运行的服务里，我通常把流程分成两层：启动层加载固定翻译并检查错误，请求层只根据语言创建 Printer 并格式化。这样既保留了 SetString 的简洁入口，又避免每个请求重复修改共享目录。

如果项目需要多个独立 catalog，可以进一步使用 message.Catalog 选项把自定义目录交给 Printer；不过这已经是资源装载和目录隔离问题，不必为了一个简单的 SetString 用例提前引入复杂抽象。先把消息键、语言标签和 fallback 约定清楚，通常比堆叠更多加载器更重要。

• 登记失败：在启动阶段返回错误，禁止带着半套翻译继续运行。
• 查找不到：给 message.Key 传入可读 fallback，不让用户看到空白。
• 语言选择：把请求头、Cookie 或用户设置统一转换成 language.Tag，不要在业务模板里判断语言。

常见问题

SetString 登记后为什么还显示原文？

先检查 Printer 使用的语言标签是否和登记时一致，再检查输出时的 key 是否完全相同。若使用了 message.Key，第二个参数本来就是回退文本，缺少对应翻译时显示原文属于预期行为。

SetString 适合放在每次请求里吗？

不建议。它修改默认 catalog，动态请求里反复登记会引入共享状态和时序问题。把翻译资源在初始化阶段集中登记，请求阶段只创建 Printer 并读取消息，更容易复查。

最后的取舍

如果只记住一件事，就是把 SetString 当作“写入翻译目录”的动作，而不是“立刻翻译一句话”的函数。稳定消息键负责长期接口，language.Tag 负责选择语言，Printer 负责格式化输出，Key 的 fallback 负责缺失时的可用性。这个拆分足以覆盖大多数轻量本地化场景；当资源数量和团队协作继续增长，再考虑独立 catalog 或外部资源加载。