设计说明: 多语言处理

在 OneAdmin 的分层架构中，多语言处理作为基础能力模块存在，负责提供统一的国际化支持。它通过加载语言文件、在请求中传递语言信息，并提供统一的调用方法，实现系统文本与错误信息的多语言输出。

核心设计#

多语言相关实现全部集中在 internal/i18n 目录中，整体设计分为三部分：

1. 语言加载：读取语言文件并解析为内存结构
2. 语言传递：通过中间件将语言写入请求上下文
3. 语言获取：在任意位置根据上下文获取对应语言内容

语言文件结构#

所有语言文件存放在：

internal/i18n/locales

文件格式为 .yml，示例如下：

error:
  0: 操作成功
  10001: 请求参数不合法

gender:
  female: 女
  male: 男

key1:
  key2:
    key3: 'K3'

no: 否
yes: 是

解析规则：

• error 节点：用于定义错误码与错误信息的映射（errorsMap）
• 其他节点：用于定义普通文本（keysMap）

数据结构说明#

语言文件加载后会拆分为两部分：

1. errorsMap

   • key：错误码（int）
   • value：错误信息（string）

2. keysMap

   • key：字符串路径（通过 . 拼接）
   • value：对应文本内容

多语言加载#

项目内置多语言（i18n）支持，语言文件采用 YAML 格式进行管理，默认存放于：

internal/i18n/locales/

例如：

zh.yaml
en.yaml

初始化方式#

项目统一通过以下方法完成多语言加载：

i18n.InitLocales()

当前项目已在 internal/bootstrap/app.go 中自动调用该方法，无需额外配置。

加载策略说明#

​InitLocales 会根据运行环境自动选择加载方式：

开发环境（debug / test）#

从本地文件系统加载

• 扫描 internal/i18n/locales 目录
• 自动加载所有 .yaml / .yml 文件
• 支持热更新（修改文件无需重新编译）

生产环境（release）#

从 embed 内嵌文件加载

• 语言文件在编译时已打包进二进制
• 运行时无需依赖本地文件
• 部署更简单、安全性更高

请求中的语言传递#

在请求进入系统后，会经过中间件：

internal/middleware/language.go

该中间件负责：

• 获取用户请求中的语言标识
• 将语言信息写入 context.Context

之后在任意需要使用多语言的地方，都可以通过：

lang := i18n.GetLang(ctx)

获取当前请求的语言。

文本获取方式#

系统提供两个核心方法用于获取多语言内容：

1. 获取普通文本#

T(lang string, key string, args ...string) string

• 从 keysMap 中获取内容
• 支持通过 . 访问嵌套结构

示例：

i18n.T("en", "no")
i18n.T("en", "gender.female")
i18n.T("en", "key1", "key2", "key3")

2. 获取错误信息#

E(lang string, code int) string

• 从 errorsMap 中获取错误信息
• 根据错误码返回对应语言文本

具体错误码设计与使用方式，可参考「错误处理机制」章节。

使用约定#

在实际开发中，建议遵循以下约定：

• 所有用户可见文本尽量通过 i18n 获取
• 错误信息统一通过错误码 + i18n 返回
• 不在业务代码中写死文本内容
• 使用 context 传递语言，避免全局变量污染