i18n

package module
v0.2.8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 27, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

README

go-i18n

功能强大的 Go 国际化（i18n）库，支持多种消息格式、语言回退和灵活的消息加载方式

特性

  • 多种消息格式：fmt.Sprintf 风格、{key}、{{key}}、{{.key}}
  • 语言回退：自动回退到默认语言
  • 灵活加载：Map、JSON、YAML、文件等多种来源
  • 线程安全：使用互斥锁保证并发安全
  • 可扩展：支持自定义格式化器和消息加载器

框架图

graph TB
    subgraph Core
        M[Manager]
        F[Formatter]
        T[Translator]
        C[Context]
    end
    subgraph Loaders
        L[Loader]
        ML[MapLoader]
        FL[FileLoader]
        JL[JSONLoader]
        YL[YAMLLoader]
    end
    subgraph Utils
        TF[T/TWithMap]
    end
    M --> T
    M --> F
    C --> T
    TF --> C
    L --> M
    ML --> L
    FL --> L
    JL --> L
    YL --> L

核心组件

组件 文件 说明
Manager manager.go 国际化管理器，负责消息加载、语言解析和翻译
Formatter format.go 消息格式化器，支持多种占位符格式
Translator context.go 翻译器接口，解耦 Context 与 Manager
Context context.go 国际化上下文，支持链式翻译操作
Loader loader.go 消息加载器接口
MapLoader loader_map.go 内存 Map 加载器
FileLoader loader_file.go JSON 文件加载器
JSONLoader loader_json.go JSON 字符串加载器
YAMLLoader loader_yaml.go YAML 文件/字符串加载器

安装

go get github.com/kamalyes/go-i18n

基本用法

1. MapLoader 示例
loader := i18n.NewMapLoader(map[string]map[string]string{
    "en": {"hello": "Hello", "greeting": "Hello {name}"},
    "zh": {"hello": "你好", "greeting": "你好 {name}"},
})

config := &gci18n.I18N{
    Enable: true, DefaultLanguage: "en",
    SupportedLanguages: []string{"en", "zh"},
    MessageLoader: loader, EnableFallback: true,
}

manager, _ := i18n.NewManager(config)

manager.GetMessage("en", "hello")                                    // "Hello"
manager.GetMessage("zh", "hello")                                    // "你好"
manager.GetMessage("en", "greeting", "John")                        // "Hello John"
manager.GetMessageWithMap("en", "greeting", map[string]any{"name": "John"}) // "Hello John"
2. FileLoader 示例
// 假设存在 i18n 目录，包含 en.json 和 zh.json 文件
loader := i18n.NewFileLoader("i18n")

config := &gci18n.I18N{
    Enable: true, DefaultLanguage: "en",
    SupportedLanguages: []string{"en", "zh"},
    MessageLoader: loader, EnableFallback: true,
}

manager, _ := i18n.NewManager(config)
3. JSONLoader 示例
jsonContent := `{
    "en": {"hello": "Hello", "greeting": "Hello {name}"},
    "zh": {"hello": "你好", "greeting": "你好 {name}"}
}`

loader := i18n.NewJSONLoader(jsonContent)

config := &gci18n.I18N{
    Enable: true, DefaultLanguage: "en",
    SupportedLanguages: []string{"en", "zh"},
    MessageLoader: loader, EnableFallback: true,
}

manager, _ := i18n.NewManager(config)
4. YAMLLoader 示例
yamlContent := `
en:
  hello: "Hello"
  greeting: "Hello {name}"
zh:
  hello: "你好"
  greeting: "你好 {name}"
`

loader := i18n.NewYAMLLoader(yamlContent)

config := &gci18n.I18N{
    Enable: true, DefaultLanguage: "en",
    SupportedLanguages: []string{"en", "zh"},
    MessageLoader: loader, EnableFallback: true,
}

manager, _ := i18n.NewManager(config)
5. 不同消息格式示例
// fmt.Sprintf 风格
manager.GetMessage("en", "greeting", "John") // "Hello John"

// {key} 风格
manager.GetMessageWithMap("en", "greeting", map[string]any{"name": "John"}) // "Hello John"

// {{key}} 风格（需要在消息中使用 {{name}} 格式）
// {{.key}} 风格（需要在消息中使用 {{.name}} 格式）
6. 语言回退示例
// 当请求的语言不存在时，会回退到默认语言
manager.GetMessage("fr", "hello") // 回退到 "Hello"（默认语言 en）

// 当请求的消息键不存在时，会返回原始键
manager.GetMessage("en", "non_existent_key") // "non_existent_key"
7. 链式翻译操作
// 创建上下文
ctx := manager.NewContext("en")

// 链式调用
result := ctx.T("greeting").WithMap(map[string]any{"name": "John"}).String() // "Hello John"

// 或者使用 TWithMap 直接传参
result := ctx.TWithMap("greeting", map[string]any{"name": "John"}).String() // "Hello John"
8. 错误处理
manager, err := i18n.NewManager(config)
if err != nil {
    log.Fatalf("Failed to create manager: %v", err)
}

// 检查消息是否存在
if !manager.HasMessage("en", "hello") {
    log.Println("Message 'hello' not found in English")
}

测试

# 测试所有组件并生成覆盖率报告
go test -cover ./... -v

文档

文档 说明
docs/API.md API 参考
docs/Loaders.md 消息加载器

Documentation

Index

Constants

View Source 
const (
	// ErrTypeLanguageLoadFailed 语言加载失败
	ErrTypeLanguageLoadFailed errorx.ErrorType = 6000 + iota
	// ErrTypeLanguageNotFound 语言未找到
	ErrTypeLanguageNotFound
	// ErrTypeJSONParseFailed JSON 解析失败
	ErrTypeJSONParseFailed
	// ErrTypeMessageLoaderRequired 消息加载器未设置
	ErrTypeMessageLoaderRequired
	// ErrTypeConfigInvalid 配置无效
	ErrTypeConfigInvalid
	// ErrTypeTranslationFailed 翻译失败
	ErrTypeTranslationFailed
)
View Source 
const (
	// ErrTypeLoaderFileNotFound 加载器文件未找到
	ErrTypeLoaderFileNotFound errorx.ErrorType = 6100 + iota
	// ErrTypeLoaderReadFailed 加载器读取失败
	ErrTypeLoaderReadFailed
	// ErrTypeLoaderParseFailed 加载器解析失败
	ErrTypeLoaderParseFailed
	// ErrTypeLoaderLanguageNotFound 加载器语言未找到
	ErrTypeLoaderLanguageNotFound
)
View Source 
const (
	// ContextKey i18n 上下文键
	ContextKey contextKey = "i18n"
)

Variables

This section is empty.

Functions

func AsMessageLoader 

func AsMessageLoader(l Loader) goi18n.MessageLoader

AsMessageLoader 将 Loader 转换为 go-config 的 MessageLoader 接口 由于 Loader 接口与 MessageLoader 接口签名一致，直接类型断言即可 如果转换失败返回 nil

func ExtractLanguage 

func ExtractLanguage(r interface{}) string

ExtractLanguage 从 HTTP 请求中提取语言信息 使用 metadata.LanguageExtractor 的默认配置 优先级：Query(lang/language) → Header(X-Language) → Cookie(language) → Accept-Language → "en"

func FlattenToMessages 

func FlattenToMessages(data map[string]any) map[string]string

FlattenToMessages 将嵌套 JSON 扁平化为点号格式的消息映射 基于 mathx.FlattenMap 实现嵌套结构扁平化，再通过 TransformMapValues 将值转为字符串 例如: {"error": {"internal": "错误"}} -> {"error.internal": "错误"}

func FormatMessage 

func FormatMessage(message string, args []any, templateData map[string]any) string

FormatMessage 便捷函数：使用默认格式化器格式化消息

func FormatWithTemplateData 

func FormatWithTemplateData(message string, templateData map[string]any) string

FormatWithTemplateData 使用模板数据格式化消息 支持多种占位符格式，按优先级依次替换

func GetLanguage 

func GetLanguage(ctx context.Context) string

GetLanguage 全局获取语言函数

func GetMsgByKey 

func GetMsgByKey(ctx context.Context, key string) string

GetMsgByKey 通过键获取消息（业务层级函数）

func GetMsgWithMap 

func GetMsgWithMap(ctx context.Context, key string, data map[string]any) string

GetMsgWithMap 使用 map 模板数据获取消息（业务层级函数）

func NewContext 

func NewContext(ctx stdcontext.Context, language string, translator Translator) stdcontext.Context

NewContext 创建带有 i18n 上下文的新 stdlib context.Context

func NormalizeLanguage 

func NormalizeLanguage(lang string) string

NormalizeLanguage 标准化语言代码 委托给 metadata.NormalizeLanguage 实现 例如: "zh-cn" -> "zh-CN", "zh_CN" -> "zh-CN", "EN" -> "en"

func ParseAcceptLanguage 

func ParseAcceptLanguage(acceptLang string) (language, region, fullTag string)

ParseAcceptLanguage 解析 Accept-Language 头获取主要语言和地区代码 委托给 metadata.ParseAcceptLanguage 实现 返回: 语言代码(如 "zh"), 地区代码(如 "CN"), 完整标签(如 "zh-CN")

func SetLanguage 

func SetLanguage(ctx context.Context, language string) context.Context

SetLanguage 全局设置语言函数

func T 

func T(ctx context.Context, key string, args ...any) string

T 全局翻译函数（位置参数）

func TWithMap 

func TWithMap(ctx context.Context, key string, templateData map[string]any) string

TWithMap 全局翻译函数（命名模板数据）

Types

type Context 

type Context struct {
	// Language 当前语言代码
	Language string
	// Translator 翻译器实例
	Translator Translator
}

Context 国际化上下文 携带当前语言和翻译器，支持链式翻译操作

func FromContext 

func FromContext(ctx stdcontext.Context) *Context

FromContext 从 stdlib context.Context 中获取 i18n 上下文

func (*Context) GetLanguage 

func (ctx *Context) GetLanguage() string

GetLanguage 获取当前语言

func (*Context) SetLanguage 

func (ctx *Context) SetLanguage(language string)

SetLanguage 设置当前语言（仅支持已注册的语言）

func (*Context) T 

func (ctx *Context) T(key string, args ...any) string

T 翻译函数（简化调用）

func (*Context) TWithMap 

func (ctx *Context) TWithMap(key string, templateData map[string]any) string

TWithMap 使用 map 模板数据翻译

type DefaultFormatter 

type DefaultFormatter struct{}

DefaultFormatter 默认消息格式化器 支持三种占位符格式：

  • fmt.Sprintf 风格（%s, %d 等）→ 位置参数
  • {key} → stringx.Format 风格（推荐命名参数）
  • {{key}} → 简化模板风格
  • {{.key}} → Go template 风格

func (*DefaultFormatter) Format 

func (f *DefaultFormatter) Format(message string, args []any, templateData map[string]any) string

Format 格式化消息，优先使用 templateData（命名参数），其次使用 args（位置参数）

type FileLoader 

type FileLoader struct {
	// contains filtered or unexported fields
}

FileLoader 文件系统消息加载器 从指定目录下的 JSON 文件加载翻译消息，支持嵌套 JSON 自动扁平化 文件命名规则: {localesPath}/{language}.json，如 ./locales/zh.json

func NewFileLoader 

func NewFileLoader(localesPath string) *FileLoader

NewFileLoader 创建文件系统消息加载器 localesPath: 翻译文件所在目录路径，如 "./locales" 或 "resources/locales"

func (*FileLoader) LoadMessages 

func (f *FileLoader) LoadMessages(language string) (map[string]string, error)

LoadMessages 加载指定语言的消息 读取 {localesPath}/{language}.json 文件，支持嵌套 JSON 自动扁平化为点号格式 language: 语言代码，如 "zh", "en", "ja" 等

type Formatter 

type Formatter interface {
	// Format 格式化消息
	// message: 消息模板
	// args: 位置参数（如 fmt.Sprintf 风格）
	// templateData: 命名模板数据（如 {key} 风格）
	Format(message string, args []any, templateData map[string]any) string
}

Formatter 消息格式化器接口 定义消息格式化的标准契约，支持位置参数和命名模板数据

type JSONLoader 

type JSONLoader struct {
	// contains filtered or unexported fields
}

JSONLoader JSON 消息加载器 从 JSON 字符串直接解析翻译消息，适用于配置文件内嵌或动态生成的场景 JSON 格式为: {"zh": {"key": "值"}, "en": {"key": "value"}}

func NewJSONLoader 

func NewJSONLoader(messagesJSON string) (*JSONLoader, error)

NewJSONLoader 创建 JSON 消息加载器 messagesJSON: JSON 格式的翻译消息字符串 格式示例: {"zh": {"hello": "你好"}, "en": {"hello": "Hello"}}

func (*JSONLoader) LoadMessages 

func (j *JSONLoader) LoadMessages(language string) (map[string]string, error)

LoadMessages 加载指定语言的消息

type Loader 

type Loader interface {
	// LoadMessages 加载指定语言的翻译消息
	// language: 语言代码，如 "zh", "en", "ja" 等
	// 返回该语言的消息映射（键为消息标识，值为翻译文本）
	LoadMessages(language string) (map[string]string, error)
}

Loader 消息加载器接口 定义从不同数据源加载国际化翻译消息的标准契约 与 go-config/pkg/i18n.MessageLoader 接口兼容，所有实现均同时满足两个接口

type Manager 

type Manager struct {
	// contains filtered or unexported fields
}

Manager 国际化管理器 核心翻译引擎，负责消息加载、语言解析和翻译

func NewManager 

func NewManager(config *gci18n.I18N) (*Manager, error)

NewManager 创建国际化管理器 config: go-config 的 i18n 配置，如果为 nil 则使用默认配置

func NewManagerWithFormatter 

func NewManagerWithFormatter(config *gci18n.I18N, formatter Formatter) (*Manager, error)

NewManagerWithFormatter 创建带自定义格式化器的国际化管理器

func NewManagerWithLogger 

func NewManagerWithLogger(config *gci18n.I18N, log logger.ILogger) (*Manager, error)

NewManagerWithLogger 创建带自定义日志的国际化管理器

func (*Manager) GetConfig 

func (m *Manager) GetConfig() *gci18n.I18N

GetConfig 获取当前配置

func (*Manager) GetDefaultLanguage 

func (m *Manager) GetDefaultLanguage() string

GetDefaultLanguage 获取默认语言

func (*Manager) GetLoadedLanguages 

func (m *Manager) GetLoadedLanguages() []string

GetLoadedLanguages 获取已加载的语言列表

func (*Manager) GetMessage 

func (m *Manager) GetMessage(language, key string, args ...any) string

GetMessage 获取翻译消息（实现 Translator 接口）

func (*Manager) GetMessageKeys 

func (m *Manager) GetMessageKeys(language string) []string

GetMessageKeys 获取指定语言的所有消息键

func (*Manager) GetMessageWithMap 

func (m *Manager) GetMessageWithMap(language, key string, templateData map[string]any) string

GetMessageWithMap 使用 map 模板数据获取翻译消息（实现 Translator 接口）

func (*Manager) GetSupportedLanguages 

func (m *Manager) GetSupportedLanguages() []string

GetSupportedLanguages 获取支持的语言列表

func (*Manager) HasLanguage 

func (m *Manager) HasLanguage(language string) bool

HasLanguage 检查指定语言的消息是否已加载

func (*Manager) IsEnabled 

func (m *Manager) IsEnabled() bool

IsEnabled 检查国际化是否启用

func (*Manager) IsLanguageSupported 

func (m *Manager) IsLanguageSupported(language string) bool

IsLanguageSupported 检查语言是否被支持（实现 Translator 接口）

func (*Manager) ReloadLanguage 

func (m *Manager) ReloadLanguage(language string) error

ReloadLanguage 重新加载指定语言的消息

func (*Manager) ResolveLanguage 

func (m *Manager) ResolveLanguage(lang string) string

ResolveLanguage 解析语言代码（委托给 go-config 的 ResolveLanguage）

type MapLoader 

type MapLoader struct {
	// contains filtered or unexported fields
}

MapLoader 内存 Map 消息加载器 直接从内存中的 map 数据结构加载翻译消息 适用于程序启动时硬编码或动态构建的翻译数据

func NewMapLoader 

func NewMapLoader(messages map[string]map[string]string) *MapLoader

NewMapLoader 创建内存 Map 消息加载器 messages: 语言消息映射，格式为 map[语言代码]map[消息键]翻译文本 示例: map[string]map[string]string{"zh": {"hello": "你好"}, "en": {"hello": "Hello"}}

func (*MapLoader) LoadMessages 

func (m *MapLoader) LoadMessages(language string) (map[string]string, error)

LoadMessages 加载指定语言的消息

type Translator 

type Translator interface {
	// GetMessage 获取翻译消息（位置参数）
	GetMessage(language, key string, args ...any) string
	// GetMessageWithMap 获取翻译消息（命名模板数据）
	GetMessageWithMap(language, key string, templateData map[string]any) string
	// IsLanguageSupported 检查语言是否被支持
	IsLanguageSupported(language string) bool
}

Translator 翻译器接口 解耦 Context 与具体 Manager 实现，避免循环依赖

type YAMLLoader 

type YAMLLoader struct {
	// contains filtered or unexported fields
}

YAMLLoader YAML 文件消息加载器 从指定目录下的 YAML 文件加载翻译消息，支持嵌套 YAML 自动扁平化 文件命名规则: {localesPath}/{language}.yaml 或 {localesPath}/{language}.yml

func NewYAMLLoader 

func NewYAMLLoader(localesPath string) *YAMLLoader

NewYAMLLoader 创建 YAML 文件消息加载器 localesPath: 翻译文件所在目录路径，如 "./locales" 或 "resources/locales"

func (*YAMLLoader) LoadMessages 

func (y *YAMLLoader) LoadMessages(language string) (map[string]string, error)

LoadMessages 加载指定语言的消息 依次尝试 {language}.yaml 和 {language}.yml 文件 支持嵌套 YAML 自动扁平化为点号格式 language: 语言代码，如 "zh", "en", "ja" 等

type YAMLStringLoader 

type YAMLStringLoader struct {
	// contains filtered or unexported fields
}

YAMLStringLoader YAML 字符串消息加载器 从 YAML 格式字符串直接解析翻译消息，适用于配置文件内嵌或动态生成的场景 YAML 格式为: zh: key: 值 en: key: value

func NewYAMLStringLoader 

func NewYAMLStringLoader(yamlStr string) (*YAMLStringLoader, error)

NewYAMLStringLoader 创建 YAML 字符串消息加载器 yamlStr: YAML 格式的翻译消息字符串 格式示例: 

zh:
  hello: 你好
en:
  hello: Hello

func (*YAMLStringLoader) LoadMessages 

func (y *YAMLStringLoader) LoadMessages(language string) (map[string]string, error)

LoadMessages 加载指定语言的消息

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.