Go x/text/language ParseAcceptLanguage 怎样读取语言偏好

当 Go 服务需要根据浏览器或客户端的 Accept-Language 头选择界面语言时，不要先手工拆逗号再自己比较 q 值。golang.org/x/text/language 已经提供了 ParseAcceptLanguage：它会返回语言标签列表、对应的质量权重，并把结果按权重从高到低排列。

本文用一个小型 HTTP 语言选择器把这条链路串起来：先读取请求头，再解析偏好，最后交给 language.Matcher 从服务支持的语言中选出稳定结果。

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

ParseAcceptLanguage 返回的三个结果分别是什么

函数签名是 ParseAcceptLanguage(s string) (tag []Tag, q []float32, err error)。tag 和 q 按索引对应：tag[i] 的偏好权重是 q[i]。权重越大，优先级越高；没有显式写 q 的语言默认权重为 1。

函数会丢弃权重为 0 的标签，并按照“权重降序、同权重按首次出现顺序”整理结果。解析器对输入比 RFC 2616 更宽松，但输入确实无法解析时仍会返回错误；即使有错误，也可能保留一部分非空切片，因此业务代码不能只看 tag 是否为空。

先写一个能读出偏好的解析函数

下面的函数只负责解析，不负责决定最终语言。这样拆分后，解析错误、无偏好和语言匹配可以分别处理，后续接入 Cookie 或用户设置时也不会把职责混在一起。

package main

import (
    "fmt"
    "net/http"

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

// parsePreferredLanguages 读取请求头，并保留解析错误供上层决定回退策略。
func parsePreferredLanguages(r *http.Request) ([]language.Tag, []float32, error) {
    // Header.Get 在请求头缺失时返回空字符串，交给解析器统一处理。
    header := r.Header.Get("Accept-Language")
    tags, weights, err := language.ParseAcceptLanguage(header)
    if err != nil {
        // 这里不把部分结果伪装成完整结果，调用方可直接选择默认语言。
        return nil, nil, fmt.Errorf("parse Accept-Language: %w", err)
    }
    return tags, weights, nil
}

这个函数有一个重要取舍：只要解析器报告错误，就返回空结果。对于只做语言展示的服务，这是比较保守的默认策略；如果产品允许“尽量使用合法前缀”，也可以记录错误后继续使用返回切片，但必须把它当作降级路径，而不是完整解析成功。

把解析结果交给 Matcher 选择支持语言

解析得到的是用户偏好，不一定就是应用真的支持的语言。例如客户端可能发送 fr-CA,fr;q=0.8,en;q=0.5，而服务只准备了英文、德文和简体中文。这时需要一个支持语言集合和明确的默认项。

Matcher.Match 接收标签列表，并返回匹配标签、支持列表中的索引和置信度。下面把默认语言放在支持列表第一位，保证没有有效偏好时仍然有可预测结果。

package main

import (
    "fmt"
    "net/http"

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

var supportedLanguages = []language.Tag{
    language.SimplifiedChinese, // 列表第一项作为服务的默认语言。
    language.English,
    language.German,
}

var languageMatcher = language.NewMatcher(supportedLanguages)

// chooseLanguage 将用户偏好映射到服务真正支持的语言。
func chooseLanguage(r *http.Request) language.Tag {
    tags, _, err := language.ParseAcceptLanguage(r.Header.Get("Accept-Language"))
    if err != nil || len(tags) == 0 {
        // 无法解析或没有可用偏好时，显式返回列表中的默认语言。
        return supportedLanguages[0]
    }

    // Matcher 负责处理语言等价关系和支持列表中的回退选择。
    tag, _, _ := languageMatcher.Match(tags...)
    return tag
}

func handler(w http.ResponseWriter, r *http.Request) {
    // 将选择结果写成响应头，实际项目也可以据此初始化翻译服务。
    w.Header().Set("Content-Language", chooseLanguage(r).String())
    w.WriteHeader(http.StatusNoContent)
}

func main() {
    http.HandleFunc("/", handler)
    fmt.Println("language selector is ready")
    _ = http.ListenAndServe(":8080", nil) // 示例省略生产环境的优雅退出处理。
}

这里没有直接拿 tags[0] 作为响应语言，因为第一偏好可能超出服务能力。Matcher 会结合支持语言列表进行匹配；将列表第一项作为默认项，也让回退行为在没有有效头部时保持稳定。

为什么要同时关注 q 权重和原始顺序

质量权重是客户端表达偏好的核心。比如 en-US,en;q=0.8,zh-CN;q=0.4 会先得到英文美国地区标签，再得到英文，最后是简体中文。解析结果的权重列表可用于日志、调试或自定义策略，但一般不建议再次排序，因为函数已经按权重整理过。

func describePreferences(header string) string {
    tags, weights, err := language.ParseAcceptLanguage(header)
    if err != nil {
        // 日志只记录解析失败，不把不完整结果当作可靠偏好。
        return fmt.Sprintf("invalid Accept-Language: %v", err)
    }

    for i, tag := range tags {
        // tags 与 weights 由同一返回结果生成，索引位置保持语义对应。
        fmt.Printf("preference[%d]=%s q=%.2f\n", i, tag, weights[i])
    }
    return "ok"
}

同一个权重下，原始出现更早的标签会排在前面。因此日志中最好同时记录标签和 q，否则只看标签顺序无法解释客户端为何选择了某个语言。

非法头部、空头部和 q=0 怎么处理

实际请求可能没有 Accept-Language，也可能带有拼写错误的标签。服务端建议采用“默认语言兜底、错误可观测”的策略：

• 空头部：把它视为没有用户偏好，直接走支持列表第一项。
• 解析错误：不把部分切片当成完整偏好，可记录结构化日志后回退。
• q=0：该语言明确表示不接受，解析器会把它从返回标签中丢弃。
• 有效但不支持：交给 Matcher 做语言等价和回退，不要把未知标签硬编码成业务语言。

如果服务对语言选择有合规或用户配置要求，Cookie、账户设置等更明确的来源应放在 Accept-Language 之前，并在代码中写清优先级；本文只处理 HTTP 头这一条输入。

把小函数接入项目时的验收清单

完成集成后，可以用几组请求头检查行为是否符合预期。这里的重点是观察返回的 Content-Language 或业务层最终使用的标签，而不是手工猜测解析器内部实现。

常见追问

ParseAcceptLanguage 会返回已经匹配好的语言吗？

不会。它只负责把头部解析为标签与权重。真正从服务支持的语言中选择结果，应继续使用 language.Matcher。

为什么不直接使用 q 最大的标签？

q 最大只代表用户偏好，不代表服务支持。Matcher 能处理语言标签之间的等价关系，并从支持集合中给出回退结果。

解析出错时可以继续使用 tags 吗？

技术上可能存在部分返回切片，但业务上应先定义降级策略。最稳妥的做法是记录错误并回退到默认语言，避免把不完整头部当成成功解析。

总结：读取语言偏好时，让 ParseAcceptLanguage 负责格式与权重，让 Matcher 负责支持集合内的选择。只要保留 error 判断、明确默认语言，并保持 tags 与 q 的索引对应，就能把 Accept-Language 安全地接入 Go HTTP 服务。