ss-visit/MULTILINGUAL_API.md

多语言API接口文档

概述

本系统已实现完整的中英双语多语言支持，所有API接口都支持通过HTTP头动态语言切换。

支持的语言

• zh-CN: 简体中文（默认）
• en: 英文

语言切换方式

通过HTTP头切换

# 设置Accept-Language头为中文
Accept-Language: zh-CN

# 设置Accept-Language头为英文
Accept-Language: en

接口示例

门岗端接口

获取拜访列表（中文）

GET /api/gate/visits?date=2024-01-15
Accept-Language: zh-CN

响应：

{
    "code": 200,
    "message": "success",
    "data": {
        "current_page": 1,
        "data": [...],
        "total": 10
    }
}

获取拜访列表（英文）

GET /api/gate/visits?date=2024-01-15
Accept-Language: en

后台管理接口

获取拜访日志列表（中文）

GET /api/admin/visit-logs/index?token=your_token
Accept-Language: zh-CN

获取拜访日志列表（英文）

GET /api/admin/visit-logs/index?token=your_token
Accept-Language: en

错误消息多语言

所有错误消息都支持多语言：

中文错误消息

{
    "code": 400,
    "message": "拜访ID不能为空",
    "data": null
}

英文错误消息

{
    "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头来测试多语言功能：

# 测试中文响应
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示例

// 请求时设置Accept-Language头
function fetchVisits(lang = 'zh-CN') {
    return fetch('/api/gate/visits', {
        headers: {
            'Accept-Language': lang
        }
    }).then(response => response.json());
}

// 使用
fetchVisits('en');

Vue.js示例

// 在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 数组