|
|
# 多语言API接口文档
|
|
|
|
|
|
## 概述
|
|
|
|
|
|
本系统已实现完整的中英双语多语言支持，所有API接口都支持通过HTTP头动态语言切换。
|
|
|
|
|
|
## 支持的语言
|
|
|
|
|
|
- `zh-CN`: 简体中文（默认）
|
|
|
- `en`: 英文
|
|
|
|
|
|
## 语言切换方式
|
|
|
|
|
|
### 通过HTTP头切换
|
|
|
|
|
|
```bash
|
|
|
# 设置Accept-Language头为中文
|
|
|
Accept-Language: zh-CN
|
|
|
|
|
|
# 设置Accept-Language头为英文
|
|
|
Accept-Language: en
|
|
|
```
|
|
|
|
|
|
## 接口示例
|
|
|
|
|
|
### 门岗端接口
|
|
|
|
|
|
#### 获取拜访列表（中文）
|
|
|
```bash
|
|
|
GET /api/gate/visits?date=2024-01-15
|
|
|
Accept-Language: zh-CN
|
|
|
```
|
|
|
|
|
|
响应：
|
|
|
```json
|
|
|
{
|
|
|
"code": 200,
|
|
|
"message": "success",
|
|
|
"data": {
|
|
|
"current_page": 1,
|
|
|
"data": [...],
|
|
|
"total": 10
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
#### 获取拜访列表（英文）
|
|
|
```bash
|
|
|
GET /api/gate/visits?date=2024-01-15
|
|
|
Accept-Language: en
|
|
|
```
|
|
|
|
|
|
### 后台管理接口
|
|
|
|
|
|
#### 获取拜访日志列表（中文）
|
|
|
```bash
|
|
|
GET /api/admin/visit-logs/index?token=your_token
|
|
|
Accept-Language: zh-CN
|
|
|
```
|
|
|
|
|
|
#### 获取拜访日志列表（英文）
|
|
|
```bash
|
|
|
GET /api/admin/visit-logs/index?token=your_token
|
|
|
Accept-Language: en
|
|
|
```
|
|
|
|
|
|
## 错误消息多语言
|
|
|
|
|
|
所有错误消息都支持多语言：
|
|
|
|
|
|
### 中文错误消息
|
|
|
```json
|
|
|
{
|
|
|
"code": 400,
|
|
|
"message": "拜访ID不能为空",
|
|
|
"data": null
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 英文错误消息
|
|
|
```json
|
|
|
{
|
|
|
"code": 400,
|
|
|
"message": "Visit ID is required",
|
|
|
"data": null
|
|
|
}
|
|
|
```
|
|
|
|
|
|
## 语言文件结构
|
|
|
|
|
|
```
|
|
|
lang/
|
|
|
├── zh-CN/
|
|
|
│ ├── common.php # 通用消息
|
|
|
│ ├── gate.php # 门岗端消息
|
|
|
│ ├── visit.php # 拜访相关消息
|
|
|
│ ├── visit_log.php # 拜访日志消息
|
|
|
│ └── ...
|
|
|
└── en/
|
|
|
├── common.php # Common messages
|
|
|
├── gate.php # Gate interface messages
|
|
|
├── visit.php # Visit related messages
|
|
|
├── visit_log.php # Visit log messages
|
|
|
└── ...
|
|
|
```
|
|
|
|
|
|
## 测试多语言功能
|
|
|
|
|
|
可以通过设置不同的Accept-Language头来测试多语言功能：
|
|
|
|
|
|
```bash
|
|
|
# 测试中文响应
|
|
|
curl -H "Accept-Language: zh-CN" http://your-domain/api/gate/visits
|
|
|
|
|
|
# 测试英文响应
|
|
|
curl -H "Accept-Language: en" http://your-domain/api/gate/visits
|
|
|
```
|
|
|
|
|
|
## 中间件说明
|
|
|
|
|
|
系统使用 `SetLocale` 中间件自动处理语言切换：
|
|
|
|
|
|
1. 检查HTTP头 `Accept-Language`
|
|
|
2. 验证语言是否支持（zh-CN, en）
|
|
|
3. 默认使用 `zh-CN`
|
|
|
|
|
|
## 前端集成建议
|
|
|
|
|
|
### JavaScript示例
|
|
|
```javascript
|
|
|
// 请求时设置Accept-Language头
|
|
|
function fetchVisits(lang = 'zh-CN') {
|
|
|
return fetch('/api/gate/visits', {
|
|
|
headers: {
|
|
|
'Accept-Language': lang
|
|
|
}
|
|
|
}).then(response => response.json());
|
|
|
}
|
|
|
|
|
|
// 使用
|
|
|
fetchVisits('en');
|
|
|
```
|
|
|
|
|
|
### Vue.js示例
|
|
|
```javascript
|
|
|
// 在Vue组件中
|
|
|
export default {
|
|
|
data() {
|
|
|
return {
|
|
|
currentLang: 'zh-CN'
|
|
|
}
|
|
|
},
|
|
|
methods: {
|
|
|
switchLanguage(lang) {
|
|
|
this.currentLang = lang;
|
|
|
},
|
|
|
async fetchData() {
|
|
|
const response = await this.$http.get('/api/gate/visits', {
|
|
|
headers: {
|
|
|
'Accept-Language': this.currentLang
|
|
|
}
|
|
|
});
|
|
|
return response.data;
|
|
|
}
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
## 注意事项
|
|
|
|
|
|
1. 所有API接口都支持多语言，无需额外配置
|
|
|
2. 通过设置 `Accept-Language` HTTP头来指定语言
|
|
|
3. 不设置语言头则使用默认语言（zh-CN）
|
|
|
4. 错误消息和成功消息都会根据当前语言返回对应文本
|
|
|
5. 支持的语言：zh-CN（中文）、en（英文）
|
|
|
|
|
|
## 扩展新语言
|
|
|
|
|
|
如需添加新语言支持：
|
|
|
|
|
|
1. 在 `lang/` 目录下创建新的语言文件夹
|
|
|
2. 复制现有语言文件并翻译内容
|
|
|
3. 在 `SetLocale` 中间件中添加新语言到 `$supportedLocales` 数组
|
