core_wing_web/I18N_README.md

# 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