511 lines
13 KiB
Markdown
511 lines
13 KiB
Markdown
# 国际化工具文档
|
||
|
||
## 概述
|
||
|
||
国际化工具（i18n）提供多语言内容管理功能，支持从文件加载语言内容，通过语言代码和消息代码获取对应语言的内容。
|
||
|
||
## 功能特性
|
||
|
||
- **多语言支持**：支持加载多个语言文件
|
||
- **文件加载**：支持从目录或单个文件加载语言内容
|
||
- **语言回退**：当指定语言不存在时，自动回退到默认语言
|
||
- **参数替换**：支持在消息中使用格式化参数（类似 fmt.Sprintf）
|
||
- **并发安全**：使用读写锁保证并发安全
|
||
- **动态加载**：支持重新加载语言文件
|
||
|
||
## 快速开始
|
||
|
||
### 1. 创建语言文件
|
||
|
||
创建语言文件目录 `locales/`，并创建对应的语言文件：
|
||
|
||
**locales/zh-CN.json**：
|
||
```json
|
||
{
|
||
"user.not_found": {
|
||
"code": 100002,
|
||
"message": "用户不存在"
|
||
},
|
||
"user.login_success": {
|
||
"code": 0,
|
||
"message": "登录成功"
|
||
},
|
||
"user.welcome": {
|
||
"code": 0,
|
||
"message": "欢迎，%s"
|
||
},
|
||
"error.invalid_params": {
|
||
"code": 100001,
|
||
"message": "参数无效"
|
||
}
|
||
}
|
||
```
|
||
|
||
**locales/en-US.json**：
|
||
```json
|
||
{
|
||
"user.not_found": {
|
||
"code": 100002,
|
||
"message": "User not found"
|
||
},
|
||
"user.login_success": {
|
||
"code": 0,
|
||
"message": "Login successful"
|
||
},
|
||
"user.welcome": {
|
||
"code": 0,
|
||
"message": "Welcome, %s"
|
||
},
|
||
"error.invalid_params": {
|
||
"code": 100001,
|
||
"message": "Invalid parameters"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 初始化并使用
|
||
|
||
```go
|
||
package main
|
||
|
||
import (
|
||
"git.toowon.com/jimmy/go-common/factory"
|
||
)
|
||
|
||
func main() {
|
||
// 创建工厂实例
|
||
fac, _ := factory.NewFactoryFromFile("config.json")
|
||
|
||
// 初始化国际化工具，设置默认语言为中文
|
||
fac.InitI18n("zh-CN")
|
||
|
||
// 从目录加载所有语言文件
|
||
fac.LoadI18nFromDir("locales")
|
||
|
||
// 获取消息
|
||
msg := fac.GetMessage("zh-CN", "user.not_found")
|
||
// 返回: "用户不存在"
|
||
|
||
// 带参数的消息
|
||
msg = fac.GetMessage("zh-CN", "user.welcome", "Alice")
|
||
// 返回: "欢迎，Alice"
|
||
|
||
// 在HTTP handler中使用Error方法（推荐）
|
||
// fac.Error(w, r, 0, "user.not_found")
|
||
// 会自动从语言文件获取业务code和国际化消息
|
||
// 返回: {"code": 100002, "message": "用户不存在"}
|
||
}
|
||
```
|
||
|
||
## API 文档
|
||
|
||
### 初始化方法
|
||
|
||
#### InitI18n
|
||
|
||
初始化国际化工具，设置默认语言。
|
||
|
||
```go
|
||
fac.InitI18n(defaultLang string)
|
||
```
|
||
|
||
**参数**：
|
||
- `defaultLang`: 默认语言代码（如 "zh-CN", "en-US"）
|
||
|
||
**示例**：
|
||
```go
|
||
fac.InitI18n("zh-CN")
|
||
```
|
||
|
||
### 加载方法
|
||
|
||
#### LoadI18nFromDir
|
||
|
||
从目录加载多个语言文件（推荐方式）。
|
||
|
||
```go
|
||
fac.LoadI18nFromDir(dirPath string) error
|
||
```
|
||
|
||
**参数**：
|
||
- `dirPath`: 语言文件目录路径
|
||
|
||
**文件命名规则**：
|
||
- 文件必须以 `.json` 结尾
|
||
- 文件名（去掉 `.json` 后缀）作为语言代码
|
||
- 例如：`zh-CN.json` 对应语言代码 `zh-CN`
|
||
|
||
**示例**：
|
||
```go
|
||
fac.LoadI18nFromDir("locales")
|
||
```
|
||
|
||
#### LoadI18nFromFile
|
||
|
||
从单个语言文件加载内容。
|
||
|
||
```go
|
||
fac.LoadI18nFromFile(filePath, lang string) error
|
||
```
|
||
|
||
**参数**：
|
||
- `filePath`: 语言文件路径（JSON格式）
|
||
- `lang`: 语言代码（如 "zh-CN", "en-US"）
|
||
|
||
**示例**：
|
||
```go
|
||
fac.LoadI18nFromFile("locales/zh-CN.json", "zh-CN")
|
||
fac.LoadI18nFromFile("locales/en-US.json", "en-US")
|
||
```
|
||
|
||
### 错误响应方法
|
||
|
||
#### Error
|
||
|
||
错误响应（自动国际化，推荐使用）。
|
||
|
||
```go
|
||
fac.Error(w, r, code int, message string, args ...interface{})
|
||
```
|
||
|
||
**参数**：
|
||
- `w`: ResponseWriter
|
||
- `r`: HTTP请求（用于获取语言信息）
|
||
- `code`: 业务错误码（如果message是消息代码，此参数会被语言文件中的code覆盖）
|
||
- `message`: 错误消息或消息代码（如果i18n已初始化且message是消息代码格式，会自动获取国际化消息和业务code）
|
||
- `args`: 可选参数，用于格式化消息（类似 fmt.Sprintf，仅在message是消息代码时使用）
|
||
|
||
**使用逻辑**：
|
||
1. 如果i18n已初始化，且message看起来是消息代码（包含点号，如 "user.not_found"），
|
||
则从请求context中获取语言，并尝试从语言文件中获取国际化消息和业务code
|
||
2. 如果获取到国际化消息，使用语言文件中的code作为响应code，使用国际化消息作为响应message
|
||
3. 如果未获取到或i18n未初始化，使用传入的code和message
|
||
|
||
**示例**：
|
||
```go
|
||
// 方式1：传入消息代码（推荐，自动获取业务code和国际化消息）
|
||
fac.Error(w, r, 0, "user.not_found")
|
||
// 如果请求语言是 zh-CN，且语言文件中 "user.not_found" 的 code 是 100002，
|
||
// 返回: {"code": 100002, "message": "用户不存在"}
|
||
// 如果请求语言是 en-US，返回: {"code": 100002, "message": "User not found"}
|
||
// 注意：业务code在所有语言中保持一致
|
||
|
||
// 方式2：带参数的消息代码
|
||
fac.Error(w, r, 0, "user.welcome", "Alice")
|
||
// 如果消息内容是 "欢迎，%s"，返回: {"code": 0, "message": "欢迎，Alice"}
|
||
|
||
// 方式3：直接传入消息文本（不使用国际化）
|
||
fac.Error(w, r, 500, "系统错误")
|
||
// 返回: {"code": 500, "message": "系统错误"}
|
||
```
|
||
|
||
### 获取消息方法
|
||
|
||
#### GetMessage
|
||
|
||
获取指定语言和代码的消息内容（推荐使用）。
|
||
|
||
```go
|
||
fac.GetMessage(lang, code string, args ...interface{}) string
|
||
```
|
||
|
||
**参数**：
|
||
- `lang`: 语言代码（如 "zh-CN", "en-US"）
|
||
- `code`: 消息代码（如 "user.not_found"）
|
||
- `args`: 可选参数，用于格式化消息（类似 fmt.Sprintf）
|
||
|
||
**返回逻辑**：
|
||
1. 如果指定语言存在该code，返回对应内容
|
||
2. 如果指定语言不存在，尝试使用默认语言
|
||
3. 如果默认语言也不存在，返回code本身（作为fallback）
|
||
|
||
**示例**：
|
||
```go
|
||
// 简单消息
|
||
msg := fac.GetMessage("zh-CN", "user.not_found")
|
||
// 返回: "用户不存在"
|
||
|
||
// 带参数的消息
|
||
msg := fac.GetMessage("zh-CN", "user.welcome", "Alice")
|
||
// 如果消息内容是 "欢迎，%s"，返回: "欢迎，Alice"
|
||
```
|
||
|
||
### GetLanguage
|
||
|
||
从请求的context中获取语言代码（推荐使用）。
|
||
|
||
```go
|
||
fac.GetLanguage(r *http.Request) string
|
||
```
|
||
|
||
**参数**：
|
||
- `r`: HTTP请求
|
||
|
||
**返回逻辑**：
|
||
1. 从请求context中获取语言（由middleware.Language中间件设置）
|
||
2. 如果未设置，返回默认语言 zh-CN
|
||
|
||
**示例**：
|
||
```go
|
||
lang := fac.GetLanguage(r)
|
||
// 可能返回: "zh-CN", "en-US" 等
|
||
```
|
||
|
||
### 高级功能
|
||
|
||
#### GetI18n
|
||
|
||
获取国际化工具对象（仅在需要高级功能时使用）。
|
||
|
||
```go
|
||
fac.GetI18n() (*i18n.I18n, error)
|
||
```
|
||
|
||
**返回**：国际化工具对象
|
||
|
||
**高级功能示例**：
|
||
```go
|
||
i18n, _ := fac.GetI18n()
|
||
|
||
// 检查语言是否存在
|
||
hasLang := i18n.HasLang("en-US")
|
||
|
||
// 获取所有支持的语言
|
||
langs := i18n.GetSupportedLangs()
|
||
|
||
// 重新加载语言文件
|
||
i18n.ReloadFromFile("locales/zh-CN.json", "zh-CN")
|
||
|
||
// 动态设置默认语言
|
||
i18n.SetDefaultLang("en-US")
|
||
```
|
||
|
||
## 使用场景
|
||
|
||
### 场景1：HTTP API 响应消息（推荐使用 Error 方法）
|
||
|
||
**推荐方式**：使用 `Error` 方法，自动从请求中获取语言并返回国际化消息和业务code：
|
||
|
||
```go
|
||
func handleLogin(w http.ResponseWriter, r *http.Request) {
|
||
fac, _ := factory.NewFactoryFromFile("config.json")
|
||
|
||
// 验证用户
|
||
user, err := validateUser(r)
|
||
if err != nil {
|
||
// 直接传入消息代码，自动获取业务code和国际化消息（推荐）
|
||
// 会自动从请求context获取语言（由middleware.Language中间件设置）
|
||
fac.Error(w, r, 0, "user.not_found")
|
||
// 返回: {"code": 100002, "message": "用户不存在"} 或 {"code": 100002, "message": "User not found"}
|
||
return
|
||
}
|
||
|
||
// 成功消息
|
||
lang := fac.GetLanguage(r)
|
||
msg := fac.GetMessage(lang, "user.login_success")
|
||
fac.Success(w, user, msg)
|
||
}
|
||
```
|
||
|
||
### 场景2：带参数的消息
|
||
|
||
```go
|
||
func handleWelcome(w http.ResponseWriter, r *http.Request) {
|
||
fac, _ := factory.NewFactoryFromFile("config.json")
|
||
lang := getLangFromRequest(r)
|
||
|
||
username := "Alice"
|
||
// 消息内容: "欢迎，%s"
|
||
msg := fac.GetMessage(lang, "user.welcome", username)
|
||
// 返回: "欢迎，Alice" 或 "Welcome, Alice"
|
||
|
||
fac.Success(w, nil, msg)
|
||
}
|
||
```
|
||
|
||
### 场景3：错误消息国际化（推荐使用 Error 方法）
|
||
|
||
**推荐方式**：使用 `Error` 方法，自动获取业务code和国际化消息：
|
||
|
||
```go
|
||
func handleError(w http.ResponseWriter, r *http.Request, messageCode string) {
|
||
fac, _ := factory.NewFactoryFromFile("config.json")
|
||
|
||
// 直接传入消息代码，自动获取业务code和国际化消息（推荐）
|
||
// 会自动从请求context获取语言并查找对应的国际化消息和业务code
|
||
fac.Error(w, r, 0, "error."+messageCode)
|
||
// 例如：fac.Error(w, r, 0, "error.invalid_params")
|
||
// 返回: {"code": 100001, "message": "参数无效"} 或 {"code": 100001, "message": "Invalid parameters"}
|
||
}
|
||
```
|
||
|
||
## 语言文件格式
|
||
|
||
语言文件必须是 JSON 格式，每个消息包含业务code和消息内容：
|
||
|
||
```json
|
||
{
|
||
"user.not_found": {
|
||
"code": 100002,
|
||
"message": "用户不存在"
|
||
},
|
||
"user.login_success": {
|
||
"code": 0,
|
||
"message": "登录成功"
|
||
},
|
||
"user.welcome": {
|
||
"code": 0,
|
||
"message": "欢迎，%s"
|
||
},
|
||
"error.invalid_params": {
|
||
"code": 100001,
|
||
"message": "参数无效"
|
||
}
|
||
}
|
||
```
|
||
|
||
**注意事项**：
|
||
- key（消息代码）建议使用点号分隔的层级结构（如 `user.not_found`）
|
||
- value 是一个对象，包含：
|
||
- `code`: 业务错误码（整数），用于业务逻辑判断，所有语言的同一消息代码应使用相同的code
|
||
- `message`: 消息内容（字符串），支持格式化占位符（如 `%s`, `%d`）
|
||
- 所有语言文件应该包含相同的 key，确保所有语言都有对应的翻译
|
||
- **重要**：同一消息代码在所有语言文件中的 `code` 必须保持一致，只有 `message` 会根据语言变化
|
||
|
||
## 最佳实践
|
||
|
||
### 1. 消息代码命名规范
|
||
|
||
建议使用层级结构，便于管理和查找：
|
||
|
||
```
|
||
模块.功能.状态
|
||
例如：
|
||
- user.not_found
|
||
- user.login_success
|
||
- order.created
|
||
- order.paid
|
||
- error.invalid_params
|
||
- error.server_error
|
||
```
|
||
|
||
### 2. 默认语言设置
|
||
|
||
建议将最常用的语言设置为默认语言，确保在语言不存在时有合理的回退：
|
||
|
||
```go
|
||
fac.InitI18n("zh-CN") // 中文作为默认语言
|
||
```
|
||
|
||
### 3. 语言代码规范
|
||
|
||
建议使用标准的语言代码格式：
|
||
- `zh-CN`: 简体中文
|
||
- `zh-TW`: 繁体中文
|
||
- `en-US`: 美式英语
|
||
- `en-GB`: 英式英语
|
||
- `ja-JP`: 日语
|
||
- `ko-KR`: 韩语
|
||
|
||
### 4. 文件组织
|
||
|
||
建议将所有语言文件放在统一的目录下：
|
||
|
||
```
|
||
project/
|
||
locales/
|
||
zh-CN.json
|
||
en-US.json
|
||
ja-JP.json
|
||
```
|
||
|
||
### 5. 参数使用
|
||
|
||
对于需要动态内容的消息，使用格式化参数：
|
||
|
||
```json
|
||
{
|
||
"user.welcome": {
|
||
"code": 0,
|
||
"message": "欢迎，%s"
|
||
},
|
||
"order.total": {
|
||
"code": 0,
|
||
"message": "订单总额：%.2f 元"
|
||
},
|
||
"message.count": {
|
||
"code": 0,
|
||
"message": "您有 %d 条新消息"
|
||
}
|
||
}
|
||
```
|
||
|
||
使用方式：
|
||
```go
|
||
// 使用 GetMessage
|
||
msg := fac.GetMessage("zh-CN", "user.welcome", "Alice")
|
||
msg := fac.GetMessage("zh-CN", "order.total", 99.99)
|
||
msg := fac.GetMessage("zh-CN", "message.count", 5)
|
||
|
||
// 使用 Error 方法（推荐）
|
||
fac.Error(w, r, 0, "user.welcome", "Alice")
|
||
fac.Error(w, r, 0, "message.count", 5)
|
||
```
|
||
|
||
### 6. 业务Code管理
|
||
|
||
**重要原则**：同一消息代码在所有语言文件中的业务code必须保持一致。
|
||
|
||
```json
|
||
// zh-CN.json
|
||
{
|
||
"user.not_found": {
|
||
"code": 100002, // 业务code
|
||
"message": "用户不存在"
|
||
}
|
||
}
|
||
|
||
// en-US.json
|
||
{
|
||
"user.not_found": {
|
||
"code": 100002, // 必须与zh-CN.json中的code相同
|
||
"message": "User not found" // 只有message会根据语言变化
|
||
}
|
||
}
|
||
```
|
||
|
||
这样设计的好处：
|
||
- 调用端可以根据返回的 `code` 进行业务逻辑判断，不受语言影响
|
||
- 所有语言的同一错误使用相同的业务code，便于统一管理
|
||
|
||
## 常见问题
|
||
|
||
### Q1: 如果语言文件不存在会怎样？
|
||
|
||
A: 如果语言文件不存在，`LoadI18nFromFile` 或 `LoadI18nFromDir` 会返回错误。建议在初始化时检查错误。
|
||
|
||
### Q2: 如果消息代码不存在会怎样？
|
||
|
||
A: `GetMessage` 和 `Error` 会按以下顺序查找：
|
||
1. 指定语言的消息
|
||
2. 默认语言的消息
|
||
3. 如果都不存在：
|
||
- `GetMessage` 返回消息代码本身（作为fallback）
|
||
- `Error` 使用传入的code参数和消息代码作为message
|
||
|
||
### Q5: 业务code在不同语言中必须相同吗？
|
||
|
||
A: **是的，必须相同**。同一消息代码在所有语言文件中的业务code必须保持一致，只有message内容会根据语言变化。这样调用端可以根据code进行业务逻辑判断，不受语言影响。
|
||
|
||
### Q3: 如何支持动态加载语言文件？
|
||
|
||
A: 可以使用 `GetI18n()` 获取对象，然后调用 `ReloadFromFile()` 或 `ReloadFromDir()` 方法。
|
||
|
||
### Q4: 是否支持嵌套的消息结构？
|
||
|
||
A: 当前版本只支持扁平结构（key-value），不支持嵌套。如果需要嵌套结构，建议使用点号分隔的层级命名（如 `user.profile.name`）。
|
||
|
||
## 完整示例
|
||
|
||
参考 [examples/i18n_example.go](../examples/i18n_example.go)
|