datai/docs/archive/api-docs/system/2026-01-21-002-02-api-后端国际化.md

API 文档：后端国际化接口

元数据

• 需求编号：2026-01-21-002-02
• 创建时间：2026-01-26
• 创建人：SSOT 架构师
• 父需求：2026-01-21-002-项目国际化需求

API 概述

后端国际化接口提供了国际化资源管理、语言偏好管理等功能，支持错误消息、日志消息、验证消息、通知消息的国际化。系统支持中文和英文两种语言，可根据用户语言偏好返回对应语言的消息。

接口列表

---

接口 1：刷新国际化资源

功能描述

刷新系统内的国际化资源缓存（MessageSource），使最新的资源变更立即生效，无需重启应用。该接口主要用于在修改国际化资源文件后，使变更立即生效。

请求方式

POST

请求路径

/system/i18n/refresh

权限要求

• system:i18n:refresh

请求参数

无

请求示例

curl -X POST 'http://localhost:8080/system/i18n/refresh' \
  -H 'Authorization: Bearer {token}'

响应数据结构

参数名	类型	说明
code	Integer	状态码（200 成功，500 失败）
msg	String	提示信息
data	Object	数据对象（通常为 null）

响应示例

成功响应：

{
  "code": 200,
  "msg": "国际化资源刷新成功",
  "data": null
}

失败响应：

{
  "code": 500,
  "msg": "国际化资源刷新失败",
  "data": null
}

不支持动态刷新：

{
  "code": 500,
  "msg": "当前 MessageSource 不支持动态刷新",
  "data": null
}

错误码说明

错误码	说明
200	刷新成功
500	刷新失败或 MessageSource 不支持动态刷新

---

接口 2：获取当前语言偏好

功能描述

获取当前登录用户的语言偏好信息，包括语言代码、语言名称和国家名称。该接口用于前端初始化时获取用户的语言设置。

请求方式

GET

请求路径

/system/i18n/currentLocale

权限要求

• system:i18n:query

请求参数

无

请求示例

curl -X GET 'http://localhost:8080/system/i18n/currentLocale' \
  -H 'Authorization: Bearer {token}'

响应数据结构

参数名	类型	说明
code	Integer	状态码（200 成功，500 失败）
msg	String	提示信息
data	Object	语言偏好信息
data.langCode	String	语言代码（如 zh_CN、en_US）
data.language	String	语言名称（如 中文、English）
data.country	String	国家名称（如 中国、United States）

响应示例

成功响应（中文）：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "langCode": "zh_CN",
    "language": "中文",
    "country": "中国"
  }
}

成功响应（英文）：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "langCode": "en_US",
    "language": "English",
    "country": "United States"
  }
}

失败响应：

{
  "code": 500,
  "msg": "未找到用户信息",
  "data": null
}

错误码说明

错误码	说明
200	获取成功
500	获取失败或未找到用户信息

---

接口 3：更新用户语言偏好

功能描述

更新当前登录用户的语言偏好设置，将语言偏好持久化到数据库（sys_user 表的 lang_code 字段）。更新后，系统将根据新的语言偏好返回对应语言的消息。

请求方式

PUT

请求路径

/system/i18n/updateLocale

权限要求

• system:i18n:update

请求参数

参数名	类型	必选	说明
langCode	String	是	目标语言代码（支持 zh_CN、en_US）

请求示例

curl -X PUT 'http://localhost:8080/system/i18n/updateLocale' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "langCode": "en_US"
  }'

响应数据结构

参数名	类型	说明
code	Integer	状态码（200 成功，400/500 失败）
msg	String	提示信息
data	Object	数据对象（通常为 null）

响应示例

成功响应：

{
  "code": 200,
  "msg": "语言偏好更新成功",
  "data": null
}

失败响应（不支持的语言代码）：

{
  "code": 400,
  "msg": "不支持的语言代码",
  "data": null
}

失败响应（未找到用户信息）：

{
  "code": 500,
  "msg": "未找到用户信息",
  "data": null
}

错误码说明

错误码	说明
200	更新成功
400	不支持的语言代码
500	更新失败或未找到用户信息

业务规则

1. 支持的语言代码：zh_CN（简体中文）、en_US（美式英语）
2. 语言代码不能为空
3. 更新后，用户需要重新登录或刷新页面才能看到语言切换效果
4. 语言偏好保存在 sys_user 表的 lang_code 字段

---

国际化资源说明

资源文件位置

国际化资源文件位于：datai-admin/src/main/resources/i18n/

资源文件列表

• messages.properties - 默认资源（中文）
• messages_en_US.properties - 英文资源

资源命名规范

• 错误消息：error.{module}.{specific}
• 验证消息：validation.{field}.{rule}
• 日志消息：log.{module}.{action}
• 通知消息：notification.{type}.{template}

资源示例

错误消息（messages.properties）：

error.user.not.found=用户不存在
error.user.password.incorrect=密码错误
error.user.permission.denied=权限不足

错误消息（messages_en_US.properties）：

error.user.not.found=User not found
error.user.password.incorrect=Incorrect password
error.user.permission.denied=Permission denied

验证消息（messages.properties）：

validation.username.required=用户名不能为空
validation.username.length=用户名长度必须在{min}到{max}之间
validation.email.format=邮箱格式不正确

验证消息（messages_en_US.properties）：

validation.username.required=Username is required
validation.username.length=Username length must be between {min} and {max}
validation.email.format=Invalid email format

日志消息（messages.properties）：

log.user.login.success=用户登录成功
log.user.logout.success=用户登出成功
log.user.update.success=用户信息更新成功

日志消息（messages_en_US.properties）：

log.user.login.success=User logged in successfully
log.user.logout.success=User logged out successfully
log.user.update.success=User information updated successfully

通知消息（messages.properties）：

notification.email.register.subject=注册成功
notification.email.register.content=欢迎注册{appName}，您的账号已创建成功
notification.sms.verify.code=您的验证码是{code}，有效期{minutes}分钟
notification.platform.system=系统通知

通知消息（messages_en_US.properties）：

notification.email.register.subject=Registration Successful
notification.email.register.content=Welcome to {appName}, your account has been created successfully
notification.sms.verify.code=Your verification code is {code}, valid for {minutes} minutes
notification.platform.system=System Notification

---

语言偏好优先级

系统按以下优先级获取语言偏好：

1. 用户登录信息（sys_user.lang_code）- 最高优先级
2. 请求参数（?lang=zh_CN）
3. 请求头（Accept-Language: zh-CN）
4. 系统默认语言（Constants.DEFAULT_LOCALE = Locale.SIMPLIFIED_CHINESE）- 最低优先级

---

国际化消息获取流程

错误消息国际化

1. 捕获异常（ServiceException、RuntimeException 等）
2. 获取错误码（ServiceException.code）
3. 根据错误码查找对应的国际化资源键（ErrorCode 枚举）
4. 使用 MessageUtils 获取对应语言的错误消息
5. 返回国际化的错误消息

日志消息国际化

1. 拦截方法调用（LogAspect）
2. 获取 @Log 注解的 title 属性
3. 判断 title 是否为国际化资源键（以 log. 开头）
4. 使用 MessageUtils 获取对应语言的日志消息
5. 记录国际化的日志消息

验证消息国际化

1. 执行参数校验（Spring Validation）
2. 捕获校验异常（MethodArgumentNotValidException 等）
3. 使用 MessageUtils 获取对应语言的验证消息
4. 返回国际化的验证消息

通知消息国际化

1. 准备发送通知
2. 获取接收者的语言偏好（从 sys_user 表）
3. 使用 MessageUtils 获取对应语言的通知消息
4. 发送国际化的通知消息

---

注意事项

1. 资源刷新：修改国际化资源文件后，需要调用刷新接口使变更生效
2. 语言代码：使用标准的语言代码格式（如 zh_CN、en_US）
3. 参数占位符：资源消息支持参数占位符（如 {appName}、{code}），使用 MessageUtils 传入参数值
4. 资源缺失：如果某个语言的资源缺失，系统会返回默认语言（中文）的资源
5. 缓存策略：国际化资源默认缓存 3600 秒，可通过配置调整
6. 权限控制：所有接口都需要相应的权限才能访问
7. 用户登录：获取和更新语言偏好需要用户已登录

---

相关文档

• 需求文档
• 设计文档
• 实现文档
• 通用国际化接口