Jibber Jabber 语言检测库解析：lazygit 国际化自动识别 UI 语言的底层机制

Jibber Jabber 是 lazygit 仓库中通过 vendor 目录引入的第三方 Go 语言检测库（版本 v0.0.0-20151120183258-bcc4c8345a21，见 go.mod）。它负责在程序启动时探测操作系统当前的语言/区域设置，是 lazygit 在 language: auto 配置下自动切换界面语言的唯一数据源。读完本文，你将理解该库三个核心 API（DetectIETF、DetectLanguage、DetectTerritory）的返回值格式与错误语义、其在 Unix 与 Windows 上的不同探测路径，以及 lazygit 国际化模块如何调用它并完成"检测到语言 → 加载翻译集"的完整链路。

一、库定位：一个极简的操作系统语言探测器

根据 官方 README，Jibber Jabber 的定位一句话概括：

Jibber Jabber is a GoLang Library that can be used to detect an operating system's current language.

它不包含任何翻译内容，也不依赖 golang.org/x/text，只做一件事：从操作系统读取当前 locale，并拆分成标准化的语言码/区域码字符串。这种"零业务逻辑"的设计使其非常适合被 GUI 程序（包括终端 UI 程序）作为启动阶段的轻量依赖引入。

操作系统支持矩阵

README 明确了平台的探测方式，这与仓库中两个按构建标签（build tag）拆分的源文件一一对应：

平台	探测手段	对应源文件
macOS / Linux（含其他 Unix）	LC_ALL、LANG 环境变量	jibber_jabber_unix.go
Windows Vista 及以上	GetUserDefaultLocaleName / GetSystemDefaultLocaleName 系统调用	jibber_jabber_windows.go

Unix 源文件顶部的构建标签 // +build darwin freebsd linux netbsd openbsd 表明其覆盖范围比 README 写的 "OSX and Linux" 更广（FreeBSD/NetBSD/OpenBSD 同样生效）；Windows 侧则用 // +build windows 隔离。

二、三个核心 API 的返回格式

README 定义的三个函数都遵循 (result string, err error) 的双返回值约定，区别只在输出粒度：

• DetectIETF：返回完整 locale，格式为 ISO 639 两位语言码 + 连字符 + ISO 3166 两位国家码，例如 zh-CN、en-US；
• DetectLanguage：只返回 ISO 639 两位语言码，例如 zh；
• DetectTerritory：只返回 ISO 3166 两位国家码，例如 CN。

README 给出的调用示例：

userLocale, err := jibber_jabber.DetectIETF()
println("Locale:", userLocale)

userLanguage, err := jibber_jabber.DetectLanguage()
println("Language:", userLanguage)

localeTerritory, err := jibber_jabber.DetectTerritory()
println("Territory:", localeTerritory)

注意两个容易忽略的行为细节，均可在源码中确认：

1. 语言与区域是"拆分"出来的，而不是分别探测的。三个函数最终都汇入同一份原始 locale 字符串，再由共享工具函数 splitLocale 切分（见 jibber_jabber.go）。
2. 区域码可以为空。若原始 locale 只有语言没有国家（如 LANG=en），DetectTerritory 返回空字符串而非报错；DetectIETF 也相应退化为只含语言码。

splitLocale 的解析规则

splitLocale 的实现揭示了原始 locale 字符串的两种常见形态都会被正确处理：

func splitLocale(locale string) (string, string) {
    formattedLocale := strings.Split(locale, ".")[0]        // 1. 去掉字符集后缀
    formattedLocale = strings.Replace(formattedLocale, "-", "_", -1) // 2. 统一分隔符
    pieces := strings.Split(formattedLocale, "_")
    language := pieces[0]
    territory := ""
    if len(pieces) > 1 {
        territory = strings.Split(formattedLocale, "_")[1]
    }
    return language, territory
}

• 先按 . 截断：en_US.UTF-8 中的字符集部分（UTF-8）被丢弃；
• 再把 IETF 风格的连字符 - 统一替换成 POSIX 风格的下划线 _：zh-CN 与 zh_CN 等价；
• 最后按下划线切分，首段为语言、次段为国家。

也就是说，无论环境变量给的是 en_US.UTF-8、zh_CN 还是 zh-CN，库都能归一化解析。

三、Unix 实现：LC_ALL 优先，LANG 兜底

Unix 侧的探测逻辑集中在 jibber_jabber_unix.go，核心是 getLangFromEnv：

func getLangFromEnv() (locale string) {
    locale = os.Getenv("LC_ALL")
    if locale == "" {
        locale = os.Getenv("LANG")
    }
    return
}

这里遵循了 POSIX locale 分层的标准优先级：LC_ALL 是"覆盖一切"的全局变量，非空时直接决定语言环境；只有它为空时才回退到通用变量 LANG。README 中所说的"standard variables that are used in ALL versions of UNIX for language detection"即指这两者。

getUnixLocale 封装了错误分支：当两个环境变量都为空时，返回库内统一定义的错误消息常量：

const (
    COULD_NOT_DETECT_PACKAGE_ERROR_MESSAGE = "Could not detect Language"
)

因此在完全无 locale 信息的容器或 CI 环境中运行 Unix 版 lazygit，DetectIETF 会返回错误而非空值——这一点直接影响了下游 lazygit 的兜底行为（见第五节）。

三个 Detect* 函数在 Unix 侧是同一模式：先 getUnixLocale()，出错则原样透传错误；成功则调用 splitLocale 取对应字段。以 DetectIETF 为例：

func DetectIETF() (locale string, err error) {
    unix_locale, err := getUnixLocale()
    if err == nil {
        language, territory := splitLocale(unix_locale)
        locale = language
        if territory != "" {
            locale = strings.Join([]string{language, territory}, "-")
        }
    }
    return
}

注意返回时国家码用的是大写原样、连接符统一换成 -，保证输出始终是 IETF（BCP 47 风格）格式。

四、Windows 实现：双路径 Win32 调用与 LCID 回退表

Windows 侧的实现（jibber_jabber_windows.go）比 README 描述得更精细。README 只提到 Vista 起的 GetUserDefaultLocaleName/GetSystemDefaultLocaleName 两个系统调用，源码则按系统版本分成两条路径：

1. Vista 及以上（主路径）

getWindowsLocale 首先调用 kernel32!GetVersion 取主版本号，windowsVersion >= 6 时走基于字符串的 API：

if isVistaOrGreater {
    locale, err = getWindowsLocaleFrom("GetUserDefaultLocaleName")
    if err != nil {
        locale, err = getWindowsLocaleFrom("GetSystemDefaultLocaleName")
    }
}

getWindowsLocaleFrom 通过 syscall.MustLoadDLL("kernel32") 加载动态库，申请 LOCALE_NAME_MAX_LENGTH = 85 长度的 UTF-16 缓冲区，调用成功后用 syscall.UTF16ToString 解码。调用失败时返回带系统错误详情的错误——这就是 README "Errors" 一节所说"Windows 会提供额外的错误信息"的具体来源：

err = errors.New(COULD_NOT_DETECT_PACKAGE_ERROR_MESSAGE + ":\n" + dllError.Error())

2. Vista 以下（兼容路径）

老系统没有字符串版 API，代码退回 GetUserDefaultLCID / GetSystemDefaultLCID（失败再换系统级），拿到的是数值型 LCID。由于 LCID 无法直接解析出语言名，源码内置了一张白名单映射表：

var SUPPORTED_LOCALES = map[uintptr]string{
    0x0407: "de-DE",
    0x0409: "en-US",
    0x0c0a: "es-ES", //or is it 0x040a
    0x040c: "fr-FR",
    0x0410: "it-IT",
    0x0411: "ja-JA",
    0x0412: "ko_KR",
    0x0416: "pt-BR",
    //0x0419: "ru_RU", - Will add support for Russian when nicksnyder/go-i18n supports Russian
    0x0804: "zh-CN",
    0x0c04: "zh-HK",
    0x0404: "zh-TW",
}

两点值得注意：其一，表中条目存在下划线（ko_KR、ru_RU 注释）与连字符混用的历史遗留，但下游 splitLocale 会把两者等价处理，不影响解析；其二，俄语 LCID（0x0419）被显式注释掉，源码注释说明是等待其 i18n 生态支持俄语后才加入——这属于从源码结构可确认的历史决策。若老系统返回的 LCID 不在表中，SUPPORTED_LOCALES[locale] 将得到空字符串，函数返回 ("", nil)，即无错误但语言为空。

五、lazygit 如何消费检测结果：language: auto 的完整链路

lazygit 在仓库中唯一的 jibber_jabber 调用点位于 pkg/i18n/i18n.go。配置项 gui.language（见 docs/Config.md，可选值 auto | en | zh-CN | zh-TW | pl | nl | ja | ko | ru | pt）为 auto 时，启动流程会触发自动检测：

if configLanguage == "auto" {
    language := detectLanguage(jibber_jabber.DetectIETF)
    for _, languageCode := range languageCodes {
        if strings.HasPrefix(language, languageCode) {
            return newTranslationSet(log, languageCode)
        }
    }
    // Detecting a language that we don't have a translation for is not an
    // error, we'll just use English.
    return EnglishTranslationSet(), nil
}

其中 detectLanguage 是一个可注入的检测适配函数，它把"库报错"这一情况收敛成固定哨兵值 "C"（POSIX 默认 locale）：

func detectLanguage(langDetector func() (string, error)) string {
    if userLang, err := langDetector(); err == nil {
        return userLang
    }
    return "C"
}

由此可以归纳出三层兜底策略：

1. 库层错误（Unix 下 LC_ALL/LANG 均为空）→ 归一为 "C"，无法前缀匹配任何翻译码 → 回落到英文；
2. 检测到但无对应翻译（如 LANG=xy_XY）→ 同样回落英文，且注释明确"这不是错误"；
3. 用户显式配置了不支持的语言码 → 这才是真正的错误，返回 Language not found: ...。

支持语言码列表并非硬编码，而是通过 embed 读取内嵌的 pkg/i18n/translations/ 目录（ja.json、ko.json、zh-CN.json 等），去掉 .json 后缀即得。匹配用 strings.HasPrefix，因此 LANG=zh_CN 能命中 zh-CN（"zh_CN" 以 "zh-CN" 开头不成立，但 DetectIETF 会先输出规范化的 zh-CN）。选中的翻译集会经 mergo.Merge 覆盖合并到英文基础翻译集之上，实现"缺失词条自动回退英文"。

这些行为均有测试佐证，见 pkg/i18n/i18n_test.go：

• TestNewTranslationSetFromConfig 覆盖 auto 模式下 LANG 未设置（期望英文）、nl_NL（期望荷兰语）、zh-CN（期望简中）、xy_XY（期望回落英文）等场景，并显式跳过 Windows 运行环境——测试注释指出自动检测依赖 LANG 环境变量，"isn't respected on Windows"，这与第四节 Windows 侧走 Win32 API 而非环境变量的实现事实完全吻合；
• TestDetectLanguage 则用注入的假检测函数验证"检测器报错 → 返回 C"的兜底约定。

六、小结：把"环境探测"做成可测试的边界

Jibber Jabber 的价值在于以极小的代码量（三个平台文件、百余行）把"操作系统语言差异"收敛成统一的 (locale, err) 接口：Unix 侧依赖 LC_ALL/LANG 的标准优先级，Windows 侧按版本分派字符串 API 与 LCID 白名单两条路径，解析细节（字符集剥离、-/_ 归一化）全部由共享的 splitLocale 保证。对 lazygit 而言，这个库恰好提供了国际化启动链路中唯一不可控的外部输入，而 pkg/i18n/i18n.go 通过 detectLanguage 适配函数进一步把该输入变成可注入、可单测的依赖，实现了"检测失败不报错、检测出陌生语言不报错、只有配置了不存在的语言才报错"的稳健降级策略——这正是终端 GUI 程序在多语言环境下自动选择界面语言的完整工程答案。