Golang支持上下文感知国际化并具有简洁API的i18n插件库ctxi18n的使用

介绍

ctxi18n是一个受Ruby on Rails国际化功能启发的Go语言国际化库，旨在为Go应用提供同样简单易用的国际化支持。

该库专注于将i18n数据提供给应用的上下文实例，同时也足够灵活可以直接使用。

主要特性：

• 加载YAML或JSON格式的本地化文件，结构类似Ruby i18n
• 轻松将本地化对象添加到上下文中
• 支持使用fs.FS加载数据
• 简洁的API方法如i18n.T()和i18n.N()
• 支持简单的键值插值，如Some %{key} text
• 支持复数规则
• 翻译缺失时的默认值

使用示例

首先导入库：

import "github.com/invopop/ctxi18n"

加载翻译文件

创建YAML或JSON翻译文件，例如：

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?"

加载翻译文件：

if err := ctxi18n.Load(assets.Content); err != nil {
    panic(err)
}

或设置默认语言：

if err := ctxi18n.LoadWithDefault(assets.Content, "en"); err != nil {
    panic(err)
}

上下文中使用

在HTTP或gRPC请求上下文中设置语言：

ctx = ctxi18n.WithLocale(ctx, "en")

支持RFC9110和Accept-Language头：

ctx = ctxi18n.WithLocale(ctx, "en-US,en;q=0.9,es;q=0.8")

翻译文本

有两种使用方式：

1. 直接使用上下文方法：

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

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

1. 从上下文中获取本地化对象：

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!"

code := "EUR"
fmt.Println(i18n.T(ctx, "currencies."+code, i18n.Default(code)))
// 输出: "EUR"

或检查是否存在：

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集成

与Templ模板引擎结合使用：

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

Templ组件：

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 (
	"fmt"
	"github.com/invopop/ctxi18n"
	"github.com/invopop/ctxi18n/i18n"
	"context"
)

func main() {
	// 模拟加载翻译(实际应用中应使用embed.FS)
	translations := `
en:
  welcome:
    title: "Welcome, %{name}"
    messages:
      zero: "You have no messages"
      one: "You have 1 message"
      other: "You have %{count} messages"
`
	
	// 加载翻译
	if err := ctxi18n.LoadWithDefault([]byte(translations), "en"); err != nil {
		panic(err)
	}
	
	// 创建上下文并设置语言
	ctx := context.Background()
	ctx = ctxi18n.WithLocale(ctx, "en")
	
	// 简单翻译
	fmt.Println(i18n.T(ctx, "welcome.title", i18n.M{"name": "Alice"}))
	// 输出: Welcome, Alice
	
	// 复数翻译
	fmt.Println(i18n.N(ctx, "welcome.messages", 0, nil))
	// 输出: You have no messages
	fmt.Println(i18n.N(ctx, "welcome.messages", 1, nil))
	// 输出: You have 1 message
	fmt.Println(i18n.N(ctx, "welcome.messages", 5, i18n.M{"count": 5}))
	// 输出: You have 5 messages
	
	// 使用作用域
	ctx = i18n.WithScope(ctx, "welcome")
	fmt.Println(i18n.T(ctx, ".title", i18n.M{"name": "Bob"}))
	// 输出: Welcome, Bob
}

这个库提供了灵活且简洁的API来处理Go应用中的国际化需求，特别适合需要上下文感知的Web应用和服务。