项目背景
本项目采用基于JSON配置的多语言国际化（i18n）解决方案，支持多种语言的无缝切换和本地化。
目录结构
manifest/
└── i18n/
├── zh.json # 简体中文
├── zh-tw.json # 繁体中文
├── en.json # 英语
├── es.json # 西班牙语
├── fr.json # 法语
├── de.json # 德语
├── it.json # 意大利语
├── ja.json # 日语
├── ko.json # 韩语
├── th.json # 泰语
├── vi.json # 越南语
└── ar.json # 阿拉伯语
实现方法
1. 语言文件管理
- 每种语言使用独立的JSON文件
- 键值对格式：
"key": "翻译内容" - 保持所有语言文件的键名一致
2. 模板语言替换
在模板中使用动态语言替换：
<!-- 示例 -->
<h2>${.i18nConfig.base_info}</h2>
<label>${.i18nConfig.mobile_phone}</label>
3. 添加新语言/键的流程
- 在
manifest/i18n/目录下创建新的语言JSON文件 - 复制现有语言文件的结构
- 翻译所有现有键值
- 在模板中使用
${.i18nConfig.key}引用
最佳实践
翻译建议
- 保持翻译简洁明了
- 考虑目标语言的文化差异
- 避免使用过于口语化的表达
维护建议
- 定期review和更新翻译
- 使用专业翻译或本地化服务
- 收集用户反馈以改进翻译质量
技术细节
关键实现
- 使用Go模板引擎动态渲染
- JSON配置提供灵活的语言管理
- 支持运行时语言切换
性能优化
- 语言文件采用轻量级JSON格式
- 缓存语言配置
- 最小化语言切换开销
扩展性
添加新语言步骤
- 创建新的
.json文件 - 翻译所有现有键
- 在语言选择逻辑中添加新语言支持
常见场景
- 添加新的翻译键
- 修改现有翻译
- 支持新的语言
注意事项
- 保持所有语言文件的结构一致
- 避免在代码中硬编码文本
- 使用
${.i18nConfig.key}进行文本替换
语言选择和配置加载机制
语言选择优先级
- URL查询参数
lang - Cookie中保存的语言
- 默认语言（英语）
代码实现示例
// 语言选择逻辑
lang := r.GetQuery("lang").String()
currentLang := r.Cookie.Get("lang").String()
if lang != "" {
// 如果查询参数有语言，优先使用并更新Cookie
r.Cookie.SetHttpCookie(&http.Cookie{
Name: "lang",
Value: lang,
MaxAge: 30 * 24 * 3600,
Path: "/",
})
currentLang = lang
} else if currentLang == "" {
// 如果Cookie和查询参数都没有语言，使用默认值
lang = "en"
currentLang = "en"
r.Cookie.SetHttpCookie(&http.Cookie{
Name: "lang",
Value: lang,
MaxAge: 30 * 24 * 3600,
Path: "/",
})
} else {
// 使用Cookie中的语言
lang = currentLang
}
配置文件加载
// 读取并解析i18n配置文件
var i18nConfig map[string]string
i18nFilePath := filepath.Join("manifest", "i18n", lang+".json")
configBytes, err := os.ReadFile(i18nFilePath)
if err != nil {
// 如果读取失败，使用默认语言（英语）
i18nFilePath = filepath.Join("manifest", "i18n", "en.json")
configBytes, err = os.ReadFile(i18nFilePath)
if err != nil {
// 如果仍然读取失败，返回空配置
i18nConfig = make(map[string]string)
} else {
err = json.Unmarshal(configBytes, &i18nConfig)
}
} else {
err = json.Unmarshal(configBytes, &i18nConfig)
}
调试和日志
// 打印所有配置（调试用）
if err == nil {
for key, value := range i18nConfig {
g.Log().Debug(r.GetCtx(), "I18n Config:", "Key:", key, "Value:", value)
}
}
高级特性
动态语言切换
- 通过URL参数
?lang=zh可以立即切换语言 - Cookie保存语言偏好，提供持久的用户体验
- 默认回退到英语，确保用户始终能看到内容
性能考虑
- 使用文件缓存减少重复读取开销
- JSON解析速度快
- 日志记录可在生产环境关闭
安全性建议
- 验证
lang参数，防止读取非预期文件 - 限制可用语言列表
- 使用白名单机制
扩展建议
- 考虑使用更高性能的缓存机制
- 实现语言文件的热重载
- 支持语言包的在线更新
示例
添加新键
// en.json
{
"welcome": "Welcome",
"new_feature": "New Feature Description"
}
// zh.json
{
"welcome": "欢迎",
"new_feature": "新功能描述"
}
常见问题
Q: 如何添加一个新的语言？
A: 在 manifest/i18n/ 目录下创建新的 .json 文件，如 ru.json，复制并翻译现有语言文件的内容。
Q: 如何处理缺失的翻译？
A: 建议提供一个默认语言（通常是英语），并在缺少翻译时回退到默认语言。
结论
通过这种方法，我们实现了一个灵活、可扩展的多语言国际化解决方案，能够轻松支持多种语言和快速添加新的语言支持。
