完成app接口国际化
This commit is contained in:
230
I18N_README.md
Normal file
230
I18N_README.md
Normal file
@@ -0,0 +1,230 @@
|
||||
# CoreWing 国际化使用说明
|
||||
|
||||
## 概述
|
||||
|
||||
CoreWing 项目已完成国际化改造,支持中文(zh_CN)和英文(en_US)两种语言。
|
||||
|
||||
## 客户端使用方式
|
||||
|
||||
### HTTP Header 配置
|
||||
|
||||
客户端通过 HTTP Header 指定语言,支持以下两种方式:
|
||||
|
||||
**方式一:使用 Accept-Language(推荐)**
|
||||
```
|
||||
Accept-Language: zh_CN
|
||||
```
|
||||
|
||||
**方式二:使用自定义 lang header**
|
||||
```
|
||||
lang: en_US
|
||||
```
|
||||
|
||||
### 支持的语言代码
|
||||
|
||||
- `zh_CN` - 简体中文(默认)
|
||||
- `en_US` - 英语
|
||||
|
||||
### 示例
|
||||
|
||||
#### JavaScript/Axios
|
||||
```javascript
|
||||
// 中文请求
|
||||
axios.get('/user/info', {
|
||||
headers: {
|
||||
'Accept-Language': 'zh_CN'
|
||||
}
|
||||
});
|
||||
|
||||
// 英文请求
|
||||
axios.get('/user/info', {
|
||||
headers: {
|
||||
'Accept-Language': 'en_US'
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
#### cURL
|
||||
```bash
|
||||
# 中文
|
||||
curl -H "Accept-Language: zh_CN" http://localhost:8080/user/info
|
||||
|
||||
# 英文
|
||||
curl -H "Accept-Language: en_US" http://localhost:8080/user/info
|
||||
```
|
||||
|
||||
#### Java/OkHttp
|
||||
```java
|
||||
Request request = new Request.Builder()
|
||||
.url("http://localhost:8080/user/info")
|
||||
.addHeader("Accept-Language", "zh_CN")
|
||||
.build();
|
||||
```
|
||||
|
||||
## 国际化功能范围
|
||||
|
||||
### 已国际化的内容
|
||||
|
||||
1. **API 响应消息**
|
||||
- 成功/失败提示
|
||||
- 用户操作反馈(登录、注册、登出等)
|
||||
- 数据验证消息
|
||||
|
||||
2. **异常和错误消息**
|
||||
- 用户认证异常
|
||||
- 业务逻辑异常
|
||||
- 服务器错误提示
|
||||
|
||||
3. **邮件模板**
|
||||
- 验证码邮件内容
|
||||
- 邮件主题和页脚
|
||||
|
||||
4. **短信模板**
|
||||
- 验证码短信内容
|
||||
- 短信发送结果消息
|
||||
|
||||
5. **钉钉推送消息**
|
||||
- 反馈通知标题和内容
|
||||
- 表单标签文本
|
||||
|
||||
## 技术实现
|
||||
|
||||
### 架构组成
|
||||
|
||||
1. **I18nConfig** - 国际化配置类
|
||||
- 配置 MessageSource
|
||||
- 实现自定义 LocaleResolver
|
||||
- 支持从 Header 读取语言设置
|
||||
|
||||
2. **I18nUtil** - 国际化工具类
|
||||
- 提供静态方法获取国际化消息
|
||||
- 支持消息参数替换
|
||||
|
||||
3. **消息资源文件**
|
||||
- `messages_zh_CN.properties` - 中文消息(约90条)
|
||||
- `messages_en_US.properties` - 英文消息(约90条)
|
||||
|
||||
### 消息 Key 命名规范
|
||||
|
||||
```
|
||||
common.* - 通用消息
|
||||
user.* - 用户模块
|
||||
feedback.* - 反馈模块
|
||||
error.* - 错误消息
|
||||
email.* - 邮件模板
|
||||
sms.* - 短信模板
|
||||
dingtalk.* - 钉钉推送
|
||||
```
|
||||
|
||||
## 响应示例
|
||||
|
||||
### 中文响应 (Accept-Language: zh_CN)
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "登录成功",
|
||||
"data": {
|
||||
"token": "xxx",
|
||||
"userId": 123
|
||||
},
|
||||
"success": true
|
||||
}
|
||||
```
|
||||
|
||||
### 英文响应 (Accept-Language: en_US)
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "Login successful",
|
||||
"data": {
|
||||
"token": "xxx",
|
||||
"userId": 123
|
||||
},
|
||||
"success": true
|
||||
}
|
||||
```
|
||||
|
||||
## 开发指南
|
||||
|
||||
### 添加新的国际化消息
|
||||
|
||||
1. 在 `messages_zh_CN.properties` 中添加中文消息:
|
||||
```properties
|
||||
user.new.feature=这是一个新功能
|
||||
```
|
||||
|
||||
2. 在 `messages_en_US.properties` 中添加对应的英文消息:
|
||||
```properties
|
||||
user.new.feature=This is a new feature
|
||||
```
|
||||
|
||||
3. 在代码中使用:
|
||||
```java
|
||||
String message = I18nUtil.getMessage("user.new.feature");
|
||||
```
|
||||
|
||||
### 带参数的消息
|
||||
|
||||
**资源文件:**
|
||||
```properties
|
||||
# 中文
|
||||
user.welcome=欢迎,{0}!您已成功登录。
|
||||
|
||||
# 英文
|
||||
user.welcome=Welcome, {0}! You have successfully logged in.
|
||||
```
|
||||
|
||||
**代码使用:**
|
||||
```java
|
||||
String message = I18nUtil.getMessage("user.welcome", username);
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **默认语言**:如果客户端未指定语言,系统默认使用中文(zh_CN)
|
||||
|
||||
2. **URL 参数支持**:也可以通过 URL 参数切换语言
|
||||
```
|
||||
/user/info?lang=en_US
|
||||
```
|
||||
|
||||
3. **消息缓存**:资源文件会缓存 1 小时,修改后需要重启应用或等待缓存过期
|
||||
|
||||
4. **消息 Key 不存在**:如果找不到对应的消息 key,会返回 key 本身
|
||||
|
||||
## 修改文件清单
|
||||
|
||||
### 新增文件(3个)
|
||||
- `src/main/java/com/corewing/app/config/I18nConfig.java`
|
||||
- `src/main/java/com/corewing/app/util/I18nUtil.java`
|
||||
- `src/main/resources/i18n/messages_zh_CN.properties`
|
||||
- `src/main/resources/i18n/messages_en_US.properties`
|
||||
|
||||
### 修改文件(13个)
|
||||
1. `Result.java` - 统一返回结果类
|
||||
2. `AppUserController.java` - 用户控制器
|
||||
3. `AppFeedbackController.java` - 反馈控制器
|
||||
4. `AppUserServiceImpl.java` - 用户服务实现
|
||||
5. `VerifyCodeServiceImpl.java` - 验证码服务实现
|
||||
6. `AppFeedbackServiceImpl.java` - 反馈服务实现
|
||||
7. `GlobalExceptionHandler.java` - 全局异常处理
|
||||
8. `EmailUtil.java` - 邮件工具类
|
||||
9. `SmsBaoUtil.java` - 短信工具类
|
||||
10. `RedisUtil.java` - Redis工具类
|
||||
|
||||
## 测试建议
|
||||
|
||||
使用 Postman 或 curl 测试不同语言的响应:
|
||||
|
||||
```bash
|
||||
# 测试中文
|
||||
curl -H "Accept-Language: zh_CN" http://localhost:8080/user/login
|
||||
|
||||
# 测试英文
|
||||
curl -H "Accept-Language: en_US" http://localhost:8080/user/login
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**更新时间:** 2025-01-21
|
||||
**版本:** 1.0
|
||||
Reference in New Issue
Block a user