Golang 支持上下文感知 i18n 国际化与复数处理的插件库 ctxi18n 的使用

介绍

ctxi18n 是一个受 Ruby on Rails 国际化功能启发的 Go 语言国际化库，旨在让 Go 应用的国际化变得简单直接。

主要特性：

• 加载 YAML 或 JSON 格式的翻译文件
• 轻松将 locale 对象添加到上下文中
• 支持 fs.FS 加载数据
• 提供简短的方法名如 i18n.T() 和 i18n.N()
• 支持简单的键值插值
• 支持复数处理规则
• 当翻译缺失时提供默认值

使用示例

基本使用

import "github.com/invopop/ctxi18n"

// 加载翻译文件
if err := ctxi18n.Load(assets.Content); err != nil {
    panic(err)
}

// 设置默认语言
if err := ctxi18n.LoadWithDefault(assets.Content, "en"); err != nil {
    panic(err)
}

// 在上下文中设置语言
ctx = ctxi18n.WithLocale(ctx, "en")
ctx = ctxi18n.WithLocale(ctx, "en-US,en;q=0.9,es;q=0.8")

翻译文件示例 (YAML)

en:
  welcome:
    title: "Welcome to our application!"
    login: "Log in"
    signup: "Sign up"
    forgot-password: "Forgot Password?"
es:
  welcome:
    title: "¡Bienvenido a nuestra aplicación!"
    login: "Ingresarse"
    signup: "Registrarse"
    forgot-password: "¿Olvidaste tu contraseña?"

获取翻译

有两种方式获取翻译：

1. 直接使用包方法：

import "github.com/invopop/ctxi18n/i18n"

fmt.Println(i18n.T(ctx, "welcome.title"))

1. 从上下文中提取 locale 对象：

l := ctxi18n.Locale(ctx)
fmt.Println(l.T("welcome.title"))

默认值处理

当翻译缺失时：

fmt.Println(l.T("welcome.no.text"))
// 输出: !(MISSING welcome.no.text)

// 使用默认值
fmt.Println(i18n.T(ctx, "welcome.question", i18n.Default("Just ask!")))
// 输出: "Just ask!"

// 检查翻译是否存在
if !i18n.Has(ctx, "welcome.question") {
  fmt.Println("Just ask!")
}

插值

en:
  welcome:
    title: "Hi %{name}, welcome to our App!"

i18n.T(ctx, "welcome.title", i18n.M{"name":"Sam"})

// 带默认值的插值
i18n.T(ctx, "welcome.title", i18n.Default("Hi %{name}"), i18n.M{"name":"Sam"})

复数处理

en:
  inbox:
    emails:
      zero: "You have no emails."
      one: "You have %{count} email."
      other: "You have %{count} emails."

count := 2
fmt.Println(i18n.N(ctx, "inbox.emails", count, i18n.M{"count": count}))
// 输出: "You have 2 emails."

作用域

ctx := i18n.WithScope(ctx, "welcome")
i18n.T(ctx, ".title", i18n.M{"name":"Sam"})

与 Templ 集成

en:
  welcome:
    hello: "Hello, %{name}"

package main

import "github.com/invopop/ctxi18n/i18n"

templ Hello(name string) {
  <span class="hello">
    { i18n.T(ctx, "welcome.hello", i18n.M{"name": name}) }
  </span>
}

templ Greeting(person Person) {
  <div class="greeting">
    @Hello(person.Name)
  </div>
}

完整示例

package main

import (
	"context"
	"fmt"
	"log"
	
	"github.com/invopop/ctxi18n"
	"github.com/invopop/ctxi18n/i18n"
)

func main() {
	// 初始化上下文
	ctx := context.Background()
	
	// 加载翻译文件 (假设已嵌入到 assets.Content)
	if err := ctxi18n.LoadWithDefault(assets.Content, "en"); err != nil {
		log.Fatal(err)
	}
	
	// 设置语言
	ctx = ctxi18n.WithLocale(ctx, "en")
	
	// 简单翻译
	fmt.Println(i18n.T(ctx, "welcome.title"))
	
	// 插值
	fmt.Println(i18n.T(ctx, "welcome.greeting", i18n.M{"name": "Alice"}))
	
	// 复数处理
	fmt.Println(i18n.N(ctx, "inbox.emails", 1, i18n.M{"count": 1}))
	fmt.Println(i18n.N(ctx, "inbox.emails", 5, i18n.M{"count": 5}))
	
	// 使用作用域
	ctx = i18n.WithScope(ctx, "welcome")
	fmt.Println(i18n.T(ctx, ".login"))
}

这个库提供了灵活的国际化解决方案，可以根据项目需求选择最适合的使用方式。