Go x/text/language Match 返回的标签为什么带有扩展字段

如果 golang.org/x/text/language 的 Matcher.Match 返回了类似 en-GB-u-rg-auzzzz 的标签，不要把它当成匹配失败，也不要急着把 -u-rg-auzzzz 删除。这个扩展字段是 Matcher 把用户偏好中的地区设置带到匹配结果里的表现：语言服务可以继续使用英式英语的基础匹配，同时根据澳大利亚地区覆盖选择货币、日期或度量系统。

官方地址：https://pkg.go.dev/golang.org/x/text/language

真正需要稳定关联业务资源时，应使用 Match 返回的 index；真正需要初始化本地化服务时，再使用返回的 Tag。这两个返回值解决的是不同问题。

先区分支持标签、用户偏好和返回 Tag

NewMatcher 的参数是应用明确支持的语言集合，例如 en、en-GB 和 zh-Hans。用户传入的 en-AU 则表示偏好。Matcher 会在支持集合中找最合适的项，但返回值不一定逐字等于支持项，因为它还可能保留用户标签里的配置。

package main

import (
    "fmt"

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

func main() {
    supported := []language.Tag{
        language.English,        // 作为没有更好匹配时的回退语言
        language.BritishEnglish, // 提供英式英语的本地化资源
        language.Chinese,        // 提供中文资源
    }
    matcher := language.NewMatcher(supported)

    tag, index, confidence := matcher.Match(language.Make("en-AU"))
    // tag 可能带用户地区设置，index 才指向 supported 中的稳定位置。
    fmt.Printf("tag=%s index=%d confidence=%s\\n", tag, index, confidence)
}

这个场景中，基础匹配通常落在 en-GB，但返回 Tag 可能是 en-GB-u-rg-auzzzz。其中 en-GB 是匹配到的支持语言，u-rg-auzzzz 是 Unicode locale extension 形式的地区覆盖。不要通过比较 tag.String() 是否等于某个支持字符串来判断命中了哪一项。

理解 -u-rg- 扩展如何携带地区覆盖

官方示例把 en-AU 与支持列表中的 en-GB 进行匹配时，返回 en-GB-u-rg-auzzzz。这样设计的重点是把“使用哪套语言资源”和“用户希望采用哪个地区的本地化约定”同时表达出来。

如果后续调用 x/text/message、x/text/number、x/text/collate 等本地化组件，优先传入同一个匹配得到的 Tag，避免界面语言、数字格式和排序规则各自使用不同上下文。Matcher 已经负责语言等价关系，应用层无需先把所有标签强行规范成同一种字符串。

用 Matcher.Match 的 index 绑定业务资源

返回值中的 index 是 Matcher 为被选中的支持标签提供的唯一索引。比如应用的翻译目录、模板集合或功能开关与支持语言一一对应，就应通过索引取资源；Tag 则负责传给本地化服务。

package main

import (
    "fmt"

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

type localeResource struct {
    // messages 与 Matcher 的支持标签按同一顺序建立对应关系。
    messages map[string]string
}

func main() {
    supported := []language.Tag{
        language.English,
        language.BritishEnglish,
        language.Chinese,
    }
    resources := []localeResource{
        {messages: map[string]string{"title": "English"}},
        {messages: map[string]string{"title": "British English"}},
        {messages: map[string]string{"title": "中文"}},
    }
    matcher := language.NewMatcher(supported)
    tag, index, confidence := matcher.Match(language.Make("en-AU"))
    if index = len(resources) {
        // 防御性处理索引，避免异常输入导致资源数组越界。
        panic("language matcher returned an invalid index")
    }
    // tag 交给本地化服务，index 用于读取应用自己的资源。
    fmt.Println(tag, confidence, resources[index].messages["title"])
}

示例中的资源顺序必须和传给 NewMatcher 的支持标签顺序保持一致。如果资源由 map 或数据库维护，也可以把索引转换成应用自己的枚举，但不要把返回 Tag 的字符串当作数据库主键。

按用途决定是否做字符串规范化

“扩展字段要不要去掉”没有统一答案，取决于字符串的用途：

• 传给本地化服务：保留 Match 返回的 Tag，尤其是要让地区覆盖参与数字、日期、货币或排序行为时。
• 展示给日志或诊断：可以输出 tag.String()，它能帮助定位用户设置是否被带入结果。
• 绑定翻译资源：使用 index，不要用字符串相等比较。
• 生成对外协议值：先明确协议需要完整 BCP 47 标签还是仅语言基础值，再选择 Tag.Base()、Tag.Region() 或专门的规范化策略。

language 包默认会做有限的规范化，保留尽可能多的信息；Canonicalize 和 CanonType 可以改变规范化形式，但不应把规范化误当成 Matcher 的必要前置步骤。匹配器本身会识别不同标签之间的等价关系。

package main

import (
    "fmt"

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

func main() {
    raw := language.Raw.Make("iw-Latn-fonipa-u-cu-usd")
    defaultTag := language.Make(raw.String())
    allTag, err := language.All.Canonicalize(raw)
    if err != nil {
        // 规范化失败时保留原 Tag，避免静默丢掉用户设置。
        fmt.Println("canonicalize failed:", err)
        return
    }
    fmt.Println(defaultTag, allTag)
}

处理空输入、低置信度和不匹配

Matcher.Match 会返回匹配 Tag、索引和置信度。空输入时会回退到传给 NewMatcher 的第一个支持标签，所以第一项应该是应用真正的默认语言。低置信度并不等于返回值不可用，它只是提示应用对语言或脚本的判断不够确定。

业务代码可以记录 confidence，但不应该仅凭低置信度就丢弃 Tag；更稳妥的做法是保留返回 Tag，同时让业务层决定是否显示语言选择器或采用更保守的默认资源。

func chooseLanguage(m language.Matcher, preferred []language.Tag) language.Tag {
    tag, index, confidence := m.Match(preferred...)
    // index 只用于查支持列表，confidence 用于记录或业务策略。
    _ = index
    _ = confidence
    return tag
}

最后可以用下面的判断记住这套契约：返回 Tag 解决“后续本地化服务使用什么上下文”，返回 index 解决“应用自己的资源选哪一项”。看到 -u- 扩展字段时，先检查你正在处理的是哪一种用途，而不是简单删除字段。

常见问题

为什么返回 Tag 不等于支持列表里的 Tag？

因为 Matcher 可能把用户标签中的地区或其他 BCP 47 配置带入结果，以便后续本地化服务继续使用。

-u-rg-auzzzz 是不是错误值？

不是。它表示地区覆盖信息。是否保留取决于后续服务是否需要地区相关的格式规则。

如何知道实际匹配了支持列表的哪一项？

使用 Match 返回的 index，再按支持标签的同序资源表读取配置。

能不能直接比较 tag.String()？

不建议用它做支持项选择或业务主键。字符串可能包含用户设置，业务绑定应该依赖索引或明确的应用枚举。