Go-i18n 国际化文本本地化处理库使用指南

go-i18n 是一个强大的 Go 语言国际化(i18n)和本地化(l10n)库，它支持基于 JSON 或 TOML 格式的翻译文件，提供了灵活的文本本地化功能。下面我将详细介绍如何使用这个库。

安装

go get github.com/nicksnyder/go-i18n/v2/i18n

基本使用

1. 创建翻译文件

首先创建翻译文件，通常放在 locales 目录下：

locales/en-US.json:

{
  "hello_world": "Hello World",
  "emails": {
    "welcome": {
      "subject": "Welcome to our service",
      "body": "Hello {{.Name}}, thank you for joining us on {{.Date}}"
    }
  }
}

locales/zh-CN.json:

{
  "hello_world": "你好世界",
  "emails": {
    "welcome": {
      "subject": "欢迎使用我们的服务",
      "body": "你好 {{.Name}}，感谢你在 {{.Date}} 加入我们"
    }
  }
}

2. 初始化 i18n Bundle

package main

import (
	"fmt"
	"log"

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

func main() {
	// 创建新的 Bundle
	bundle := i18n.NewBundle(language.English)
	
	// 注册 JSON 解码器
	bundle.RegisterUnmarshalFunc("json", json.Unmarshal)
	
	// 加载翻译文件
	bundle.MustLoadMessageFile("locales/en-US.json")
	bundle.MustLoadMessageFile("locales/zh-CN.json")
	
	// 创建本地化器
	localizer := i18n.NewLocalizer(bundle, "zh-CN")
	
	// 获取简单翻译
	helloMsg, err := localizer.Localize(&i18n.LocalizeConfig{
		MessageID: "hello_world",
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(helloMsg) // 输出: 你好世界
	
	// 获取带参数的翻译
	emailBody, err := localizer.Localize(&i18n.LocalizeConfig{
		MessageID: "emails.welcome.body",
		TemplateData: map[string]interface{}{
			"Name": "张三",
			"Date": "2023-05-20",
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(emailBody) // 输出: 你好 张三，感谢你在 2023-05-20 加入我们
}

高级功能

1. 复数处理

locales/en-US.json:

{
  "unread_notification_count": {
    "one": "You have {{.Count}} unread notification",
    "other": "You have {{.Count}} unread notifications"
  }
}

locales/zh-CN.json:

{
  "unread_notification_count": "您有 {{.Count}} 条未读通知"
}

使用代码：

count := 5
msg, err := localizer.Localize(&i18n.LocalizeConfig{
    MessageID:   "unread_notification_count",
    PluralCount: count,
    TemplateData: map[string]interface{}{
        "Count": count,
    },
})
// en-US: "You have 5 unread notifications"
// zh-CN: "您有 5 条未读通知"

2. 默认消息

msg, err := localizer.Localize(&i18n.LocalizeConfig{
    DefaultMessage: &i18n.Message{
        ID:    "greeting",
        Other: "Hello, {{.Name}}!",
    },
    TemplateData: map[string]interface{}{
        "Name": "John",
    },
})

3. 多语言切换

func getLocalizer(lang string) *i18n.Localizer {
    // 在实际应用中，你可能需要从请求头或cookie中获取语言偏好
    return i18n.NewLocalizer(bundle, lang)
}

func handler(w http.ResponseWriter, r *http.Request) {
    lang := r.URL.Query().Get("lang") // 从URL参数获取语言
    if lang == "" {
        lang = "en-US" // 默认语言
    }
    
    localizer := getLocalizer(lang)
    // 使用localizer进行本地化...
}

最佳实践

1. 组织翻译文件：按功能模块组织翻译内容，而不是全部放在一个文件中
2. 命名规范：使用点分隔的命名方式，如 module.component.message
3. 参数验证：在模板中使用参数前进行验证
4. 错误处理：总是检查 Localize 返回的错误
5. 性能优化：在应用启动时加载所有翻译文件，而不是每次请求时加载

完整示例

package main

import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"

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

var bundle *i18n.Bundle

func initI18n() {
	bundle = i18n.NewBundle(language.English)
	bundle.RegisterUnmarshalFunc("json", json.Unmarshal)
	bundle.MustLoadMessageFile("locales/en-US.json")
	bundle.MustLoadMessageFile("locales/zh-CN.json")
	bundle.MustLoadMessageFile("locales/ja-JP.json")
}

func main() {
	initI18n()
	
	http.HandleFunc("/greet", greetHandler)
	log.Println("Server started on :8080")
	log.Fatal(http.ListenAndServe(":8080", nil))
}

func greetHandler(w http.ResponseWriter, r *http.Request) {
	lang := r.URL.Query().Get("lang")
	if lang == "" {
		lang = "en-US"
	}
	
	localizer := i18n.NewLocalizer(bundle, lang)
	
	name := r.URL.Query().Get("name")
	if name == "" {
		name = "Guest"
	}
	
	greeting, err := localizer.Localize(&i18n.LocalizeConfig{
		MessageID: "greeting.message",
		DefaultMessage: &i18n.Message{
			ID:    "greeting.message",
			Other: "Hello, {{.Name}}!",
		},
		TemplateData: map[string]interface{}{
			"Name": name,
		},
	})
	
	if err != nil {
		http.Error(w, err.Error(), http.StatusInternalServerError)
		return
	}
	
	fmt.Fprintf(w, greeting)
}

总结

go-i18n 提供了强大的国际化支持，包括：

• 多语言翻译文件支持
• 模板变量替换
• 复数处理
• 默认消息回退
• 灵活的本地化配置

通过合理组织翻译文件和正确使用 Localizer，你可以轻松地为 Go 应用程序添加国际化支持。记得根据实际需求选择合适的语言标识符（如 zh-CN、en-US 等）并保持一致。