Skip to main content

Go 国际化完整指南

从消息文件到可确保 goroutine 安全的区域设置解析：使用 go-i18n 在 Go 应用中设置 i18n，再通过 AI 自动翻译。

1

安装 go-i18n

go-i18n 是最受欢迎的 Go 国际化库。它使用 CLDR 复数规则和 Go 模板进行变量插值，并支持 JSON、TOML 和 YAML 消息文件。您还需要 golang.org/x/text 来匹配语言标签。

go-i18n v2 需要 Go 1.16 或更高版本。golang.org/x/text 软件包提供 BCP 47 语言标签解析和匹配功能，go-i18n 在内部使用它来选择复数规则。
Terminal
go get -u github.com/nicksnyder/go-i18n/v2/i18n
go get -u golang.org/x/text/language
2

创建消息文件

在 locales 目录中为每种语言创建一个 JSON 文件。每条消息包含一个 ID 和一种或多种复数形式。Go-i18n 使用 Go 模板语法（带点号前缀的双花括号）进行变量插值。

locales/en.json
{
  "HelloWorld": { "other": "Hello, World!" },
  "Greeting": { "other": "Hello, {{.Name}}!" },
  "ItemCount": {
    "one": "{{.Count}} item",
    "other": "{{.Count}} items"
  },
  "WelcomeBack": {
    "other": "Welcome back, {{.Name}}. You have {{.Count}} messages."
  }
}
使用 'ItemCount' 或 'WelcomeBack' 等描述性消息 ID，而不是以点分隔的路径。go-i18n 使用扁平 ID，不使用嵌套键。ID 应采用 PascalCase，以符合 Go 约定。
3

加载 Bundle

Bundle 是 go-i18n 的中央注册表。启动时创建一个 Bundle，注册文件格式并加载所有消息文件。Bundle 可确保 goroutine 安全，只需创建一次并在整个应用中共享。

main.go
package main

import (
    "encoding/json"
    "fmt"
    "github.com/nicksnyder/go-i18n/v2/i18n"
    "golang.org/x/text/language"
)

func main() {
    // 1. Create a bundle with a default language
    bundle := i18n.NewBundle(language.English)
    // 2. Register the unmarshal function for your file format
    bundle.RegisterUnmarshalFunc("json", json.Unmarshal)
    // 3. Load message files
    bundle.MustLoadMessageFile("locales/en.json")
    bundle.MustLoadMessageFile("locales/ja.json")
    bundle.MustLoadMessageFile("locales/de.json")
    // 4. Create a localizer and localize a message
    localizer := i18n.NewLocalizer(bundle, "ja")
    msg := localizer.MustLocalize(&i18n.LocalizeConfig{
        MessageID: "HelloWorld",
    })
    fmt.Println(msg) // "こんにちは、世界！"
}
如果看到 'message not found'，请检查三项内容：1）消息文件是否已通过 LoadMessageFile 或 MustLoadMessageFile 加载；2）文件扩展名是否与已注册的反序列化函数匹配；3）LocalizeConfig 中的 MessageID 是否与 JSON 文件中的键完全匹配（区分大小写）。
4

使用 Localizer

使用用户的首选语言为每个请求创建一个 Localizer。Localizer 从 Bundle 解析消息，通过 Go 的 text/template 引擎处理模板呈现，并根据 PluralCount 选择正确的复数形式。

Using the Localizer
// Simple message
msg := localizer.MustLocalize(&i18n.LocalizeConfig{
    MessageID: "HelloWorld",
})

// Message with template data
msg := localizer.MustLocalize(&i18n.LocalizeConfig{
    MessageID: "Greeting",
    TemplateData: map[string]interface{}{
        "Name": "Alice",
    },
})
// "Hello, Alice!" (en) or "こんにちは、Aliceさん！" (ja)

// Plural + template data
msg := localizer.MustLocalize(&i18n.LocalizeConfig{
    MessageID: "ItemCount",
    PluralCount: 5,
    TemplateData: map[string]interface{}{
        "Count": 5,
    },
})
// "5 items" (en) or "5個のアイテム" (ja)

// Combined: plurals + multiple variables
msg := localizer.MustLocalize(&i18n.LocalizeConfig{
    MessageID: "WelcomeBack",
    TemplateData: map[string]interface{}{
        "Name":  "Alice",
        "Count": 3,
    },
})
HTTP handler with locale detection
func handler(w http.ResponseWriter, r *http.Request) {
    // Accept-Language: ja,en;q=0.9,de;q=0.8
    accept := r.Header.Get("Accept-Language")

    // NewLocalizer accepts multiple languages — first match wins
    localizer := i18n.NewLocalizer(bundle, accept)

    msg := localizer.MustLocalize(&i18n.LocalizeConfig{
        MessageID: "HelloWorld",
    })

    w.Header().Set("Content-Type", "text/plain; charset=utf-8")
    w.Write([]byte(msg))
}
NewLocalizer 接收多个语言字符串，并按顺序尝试。直接传入 Accept-Language 标头：i18n.NewLocalizer(bundle, r.Header.Get("Accept-Language"))。go-i18n 会自动解析标头，并与可用翻译进行匹配。
5

处理复数规则

go-i18n 为所有语言实现 CLDR 复数规则。英语有 2 种形式（one、other），阿拉伯语有 6 种（zero、one、two、few、many、other），日语有 1 种（other）。请在消息文件中定义所有必需形式，go-i18n 会根据 PluralCount 选择正确形式。

Plural forms by language
// English: 2 forms (one, other)
{
  "ItemCount": {
    "one": "{{.Count}} item",
    "other": "{{.Count}} items"
  }
}

// Arabic: 6 forms (zero, one, two, few, many, other)
{
  "ItemCount": {
    "zero": "لا عناصر",
    "one": "عنصر واحد",
    "two": "عنصران",
    "few": "{{.Count}} عناصر",
    "many": "{{.Count}} عنصرًا",
    "other": "{{.Count}} عنصر"
  }
}

// Japanese: 1 form (other)
{
  "ItemCount": {
    "other": "{{.Count}}個のアイテム"
  }
}
Using plural rules
// go-i18n selects the correct plural form based on PluralCount
localizer := i18n.NewLocalizer(bundle, "ar")

msg := localizer.MustLocalize(&i18n.LocalizeConfig{
    MessageID:   "ItemCount",
    PluralCount: 3,
    TemplateData: map[string]interface{}{
        "Count": 3,
    },
})
// Arabic "few" form: "3 عناصر"

msg = localizer.MustLocalize(&i18n.LocalizeConfig{
    MessageID:   "ItemCount",
    PluralCount: 1,
    TemplateData: map[string]interface{}{
        "Count": 1,
    },
})
// Arabic "one" form: "عنصر واحد"
PluralCount 与 TemplateData 相互独立。PluralCount 选择复数形式，TemplateData 为模板呈现提供值。如果消息文本中需要显示数量，请同时传入两者：PluralCount: n 和 TemplateData: map[string]interface{'}'{"Count": n}。
6

区域设置检测

在 Web 应用中，从多个来源检测用户的首选语言：查询参数、Cookie、Accept-Language 标头或 URL 路径段。使用 golang.org/x/text/language.Matcher 进行符合 BCP 47 的语言协商。

Locale detection middleware
// detectLocale resolves the user's preferred language.
// Priority: query param > cookie > Accept-Language header > default
func detectLocale(r *http.Request, matcher language.Matcher) string {
    // 1. Explicit query parameter: ?lang=ja
    if lang := r.URL.Query().Get("lang"); lang != "" {
        tag, _, _ := matcher.Match(language.Make(lang))
        return tag.String()
    }
    // 2. Cookie from previous selection
    if cookie, err := r.Cookie("lang"); err == nil {
        tag, _, _ := matcher.Match(language.Make(cookie.Value))
        return tag.String()
    }
    // 3. Accept-Language header
    accept := r.Header.Get("Accept-Language")
    if accept != "" {
        tags, _, _ := language.ParseAcceptLanguage(accept)
        if len(tags) > 0 {
            tag, _, _ := matcher.Match(tags...)
            return tag.String()
        }
    }
    return "en" // 4. Default
}

// Usage:
matcher := language.NewMatcher([]language.Tag{
    language.English, language.Japanese,
    language.German, language.Spanish,
})

http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
    locale := detectLocale(r, matcher)
    localizer := i18n.NewLocalizer(bundle, locale)
    // ... use localizer
})
language.NewMatcher 返回与支持语言最匹配的结果，而非原始用户偏好。如果用户请求 'pt-BR' 而您只支持 'pt'，匹配器会正确返回 'pt'。若没有匹配器，您需要为每个地区变体手动实现回退逻辑。
7

使用 go-locale-chain 修复按键回退

go-i18n 存在一个已知限制：区域设置一旦匹配（已加载任何翻译），缺失键就不会继续回退到链中的下一个区域设置。如果 pt-BR 文件只完成了部分翻译，pt-BR 用户会得到空字符串，而不会回退到 pt-PT 或 pt。go-locale-chain 通过 75 条内置区域设置链进行按键回退解析，解决此问题。

Terminal
go get github.com/i18n-agent/go-locale-chain
go-locale-chain with go-i18n
package main

import (
    "encoding/json"
    "fmt"

    "github.com/nicksnyder/go-i18n/v2/i18n"
    localechain "github.com/i18n-agent/go-locale-chain"
    "golang.org/x/text/language"
)

func main() {
    // 1. Configure fallback chains (call once at startup)
    localechain.Configure()

    // 2. Set up go-i18n bundle as usual
    bundle := i18n.NewBundle(language.English)
    bundle.RegisterUnmarshalFunc("json", json.Unmarshal)
    bundle.MustLoadMessageFile("locales/en.json")
    bundle.MustLoadMessageFile("locales/pt.json")
    bundle.MustLoadMessageFile("locales/pt-PT.json")
    bundle.MustLoadMessageFile("locales/pt-BR.json")

    // 3. Resolve with per-key fallback
    result, _ := localechain.ResolveWithLoader("pt-BR", func(locale string) (map[string]string, error) {
        localizer := i18n.NewLocalizer(bundle, locale)
        messages := make(map[string]string)
        for _, id := range []string{"hello", "goodbye", "thanks"} {
            msg, err := localizer.Localize(&i18n.LocalizeConfig{MessageID: id})
            if err == nil {
                messages[id] = msg
            }
        }
        return messages, nil
    })

    fmt.Println(result["hello"])   // "Olá (BR)"   — from pt-BR
    fmt.Println(result["goodbye"]) // "Adeus (PT)" — fallback to pt-PT
    fmt.Println(result["thanks"])  // "Obrigado"   — fallback to pt
}
go-locale-chain 是一个零外部依赖的开源 Go 软件包。它与 go-i18n 互为补充：使用 go-i18n 加载消息、处理复数和呈现模板，使用 go-locale-chain 正确解析回退链。
Standalone usage (no go-i18n)
// Standalone: zero external dependencies, works with any format
localechain.Configure()

result, _ := localechain.ResolveWithLoader("es-MX", func(locale string) (map[string]string, error) {
    data, err := os.ReadFile(fmt.Sprintf("locales/%s.json", locale))
    if err != nil {
        return nil, err // Locale file doesn't exist — skip
    }
    var msgs map[string]string
    json.Unmarshal(data, &msgs)
    return msgs, nil
})
// es-MX -> es-419 -> es: each key resolved from most specific locale
使用 ConfigureWithOverrides() 自定义特定链，同时保留默认值。例如，可将 pt-BR 简化为仅回退到 pt，或为默认设置中没有的 sv-FI -> sv 等区域设置添加回退链。
8

自动翻译

完成 i18n 设置后，使用 AI 翻译区域设置文件。直接从 IDE 或 CI/CD 管线，根据英语源文件生成所有目标语言的翻译。

Terminal
# In your IDE, ask your AI assistant:
> Translate locales/en.json to German, Japanese, and Spanish

✓ locales/de.json created (1.2s)
✓ locales/ja.json created (1.5s)
✓ locales/es.json created (1.1s)

# Or use the CLI in CI/CD:
npx i18n-agent translate locales/en.json --lang de,ja,es
采用渐进式翻译——向源文件添加新消息 ID 时，只翻译新增键，不要重新生成所有文件。这样可保留经人工审核的翻译。

自动保证翻译质量

使用 i18n-validate 在发布前发现缺失键和损坏的占位符。真实译文完成前，可使用 i18n-pseudo 生成伪译文来测试 UI。

常见问题

PluralCount 与 TemplateData 不匹配

PluralCount 选择复数形式，但不会将值注入模板。您还必须在 TemplateData 中传入数量，才能在呈现的消息中显示它。如果没有 TemplateData，'{'{.Count}'}' 会呈现为 '<no value>'。

缺少 RegisterUnmarshalFunc

如果忘记针对文件格式调用 bundle.RegisterUnmarshalFunc()，LoadMessageFile 会静默返回空消息。加载文件前，务必注册 json.Unmarshal（或 toml/yaml）。

按键回退不起作用

go-i18n 的 NewLocalizer 接收多种语言，但一旦某个区域设置匹配一个键，缺失键就会返回空字符串而不会回退。使用 go-locale-chain，通过正确的按键逐级回退解决此问题。

模板语法：{'{.Var}'}，而不是 {'{Var}'}

go-i18n 使用 Go 的 text/template 语法。变量必须带点号前缀：{'{.Name}'}，而不是 {'{Name}'}。点号指向 TemplateData 映射。缺少点号会导致模板执行错误。

推荐的文件结构

Project Structure
my-go-app/
├── locales/
│   ├── en.json           # Source language (English)
│   ├── de.json           # German translations
│   ├── ja.json           # Japanese translations
│   ├── es.json           # Spanish translations
│   ├── pt.json           # Portuguese (base)
│   ├── pt-PT.json        # Portuguese (Portugal)
│   └── pt-BR.json        # Portuguese (Brazil)
├── i18n/
│   ├── bundle.go         # Bundle initialization
│   ├── detect.go         # Locale detection logic
│   └── middleware.go      # HTTP middleware for locale
├── main.go
├── go.mod
└── go.sum

还可翻译：

立即试用 i18n Agent

将翻译文件拖放到此处

JSON, YAML, PO, XML, CSV, Markdown, Properties

或点击选择文件

目标语言

无需注册即时估价

使用 go-locale-chain 实现区域设置回退

当 pt-BR 等地区区域设置缺少翻译键时，go-i18n 会直接跳到默认语言，而不会先检查父级区域设置 pt。

Terminal
go get github.com/i18n-agent/go-locale-chain
Configuration
import localechain "github.com/i18n-agent/go-locale-chain"

chain := localechain.New(localechain.Config{
    Fallbacks: map[string][]string{
        "pt-BR":      {"pt", "en"},
        "zh-Hant-HK": {"zh-Hant", "zh", "en"},
    },
})

查看语言回退指南，了解受支持框架的完整列表和 75 条内置回退链。 Learn more →

Go i18n 常见问题