Go x/text/language Matcher 怎样协商站点支持的语言

站点支持多种语言时，不要把 Accept-Language 当成一个可以直接拿来查 map 的字符串。更稳妥的做法是先把站点真正提供的语言列成 []language.Tag，再用 language.NewMatcher 创建匹配器，最后通过 MatchStrings 或 Match 取得匹配到的标签和支持列表索引。

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

最小原则是：支持列表的第一项就是明确的回退语言；返回的 index 用于关联站点资源，返回的 Tag 用于初始化后续本地化服务。

先把站点支持的语言写成有序列表

Matcher 解决的是“用户偏好与站点支持列表怎样匹配”，不是替你生成翻译文件。列表应该只放确实有资源的语言，而且顺序要有意图：官方文档把第一项作为 fallback，也就是没有更合适匹配时使用的语言。

package main

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

var supported = []language.Tag{
	language.English,             // 第一项是站点的明确回退语言
	language.MustParse("en-AU"),  // 单独支持澳大利亚英语时保留区域信息
	language.Danish,              // 站点确实提供丹麦语资源
	language.Chinese,             // 标准中文资源
}

var matcher = language.NewMatcher(supported) // 复用同一个匹配器

不要把“可能支持但没有资源”的标签放进列表。否则匹配器可能选择一个看似合理、实际没有文案或日期格式资源的结果，后面反而更难排查。

用 MatchStrings 处理 Cookie 和 Accept-Language

Web 请求里常见两类偏好：用户主动选择的 Cookie，以及浏览器发送的 Accept-Language。可以把 Cookie 放在前面，把请求头放在后面，让前面的偏好优先参与匹配。

package main

import (
	"net/http"

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

func selectLanguage(r *http.Request, matcher language.Matcher) language.Tag {
	preferred := make([]string, 0, 2)
	if cookie, err := r.Cookie("lang"); err == nil && cookie.Value != "" {
		preferred = append(preferred, cookie.Value) // 用户主动选择优先
	}
	if accept := r.Header.Get("Accept-Language"); accept != "" {
		preferred = append(preferred, accept) // 再交给浏览器偏好兜底
	}

	tag, _ := language.MatchStrings(matcher, preferred...) // 无偏好时使用支持列表第一项
	return tag
}

MatchStrings 接收一个 Matcher 和多个字符串参数。请求头通常是逗号分隔的 BCP 47 标签列表，库会处理其中的语言关系；应用代码不需要自己按字符串前缀拼出“最像”的结果。

如果只处理已经解析好的标签，也可以使用 matcher.Match。两者的区别是输入形式不同：前者适合边界层的字符串，后者适合业务层已经拿到 language.Tag 的场景。

不要忽略返回的 index

匹配结果通常有两个关键信息：一个是匹配后的 Tag，另一个是它对应的支持列表索引。索引不要通过比较字符串猜测，而应直接用来关联菜单、翻译包或资源配置。

package main

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

type LocaleResource struct {
	Messages string // 这里只保存资源标识，实际项目可换成加载器
}

func resourceFor(matcher language.Matcher, resources []LocaleResource, accept string) (language.Tag, LocaleResource) {
	tag, index := language.MatchStrings(matcher, accept) // index 指向原支持列表
	if index = len(resources) {
		return tag, LocaleResource{} // 防御性处理，避免资源数组越界
	}
	return tag, resources[index] // 用同一个 index 绑定匹配到的资源
}

官方文档特别提醒，返回的 Tag 可能和支持列表中的标签不完全相同，因为它可能携带用户标签里的设置；index 才是把结果关联到支持语言资源的稳定入口。

脚本相同但语言不同，怎样调整偏好

某些语言标签的语言、脚本和区域组合会带来多个合理候选。language.NewMatcher 可以接收 language.PreferSameScript 选项，让匹配时更偏好相同书写脚本的候选。

package main

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

var scriptAwareMatcher = language.NewMatcher(
	[]language.Tag{
		language.English,            // 保留明确的 fallback
		language.MustParse("sr-Latn"), // 拉丁脚本候选
		language.MustParse("sr-Cyrl"), // 西里尔脚本候选
	},
	language.PreferSameScript(true), // 有脚本信息时提高同脚本候选偏好
)

这个选项是匹配偏好，不是“强制按脚本返回”。最终仍应以站点实际资源为准，并在测试中覆盖脚本明确、脚本缺失和只有 fallback 的请求。

把同一个 Tag 交给后续本地化服务

语言协商结束后，尽量把同一个 Tag 传给数字、日期、排序或大小写等本地化组件。否则页面文案选成一种语言，数字或排序却使用另一套规则，用户会看到不一致的体验。

package main

import (
	"fmt"

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

func render(tag language.Tag, text string) string {
	title := cases.Title(tag).String(text) // 让后续服务沿用协商得到的 Tag
	return fmt.Sprintf("[%s] %s", tag, title)
}

不要只保存一个展示字符串，例如把 en-US 转成 en 后重新推断。匹配器会处理语言标签之间的等价关系，应用层只需要保留协商结果和资源索引，并让后续服务使用同一个标签。

排查“总是回退到第一项”的检查清单

1. 检查支持列表：第一项是否就是期望的 fallback，列表中是否真的有目标语言资源。
2. 检查输入来源：Cookie 名称和值是否为空，Accept-Language 是否真的进入了请求。
3. 检查标签格式：输入是否是 BCP 47 语言标签，而不是随意的中文名称或内部语言编号。
4. 检查返回索引：是否把 index 错当成 Tag 字符串，或资源数组和支持列表顺序不一致。
5. 检查脚本偏好：需要同脚本优先时是否显式传入 PreferSameScript(true)，但不要把它理解成硬过滤。
6. 检查下游服务：数字、日期、排序和大小写组件是否使用同一个匹配结果。

常见问题

Matcher 会不会修改我的支持语言列表？

使用时应把支持列表视为站点配置。匹配器根据这组标签进行选择，应用层仍需保证列表对应的资源存在，并按返回索引读取资源。

为什么返回的 Tag 和支持列表中的字符串不一样？

匹配结果可能携带用户标签中的设置，所以不能仅靠字符串相等判断是否命中。需要关联站点资源时使用返回的索引，需要初始化本地化服务时使用返回的 Tag。

没有 Cookie 和 Accept-Language 时怎么办？

把支持列表第一项作为明确 fallback 即可。这样无偏好请求仍然有确定结果，不必在业务代码里另写一套默认语言分支。

小结

用 x/text/language.Matcher 做语言协商时，先维护真实的支持列表，再把用户选择和请求头交给 MatchStrings。记住三点：第一项负责回退，index 负责关联资源，Tag 负责贯穿后续本地化服务。脚本偏好只调整匹配倾向，不能替代资源清单和测试。