ss-visit/MULTILINGUAL_API.md

# 多语言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` 数组