# API 文档：前端国际化-动态资源 ## 元数据 - **需求编号**：2026-01-26-002-03 - **需求名称**：前端国际化-动态资源 - **创建时间**：2026-01-26 - **创建人**：SSOT 架构师 - **状态**：已完成 ## API 概述 本文档描述了前端国际化-动态资源功能涉及的 API 接口，包括查询语言列表、获取当前语言偏好、更新用户语言偏好、查询国际化资源列表等接口。这些接口用于实现前端与后端国际化接口的深度对接，包括动态获取系统支持的语言列表、登录后自动同步并应用用户的语言偏好、实现远程翻译资源的加载、合并与缓存策略，以及实现动态菜单国际化。 ## 接口列表 ### 接口 1：查询语言列表 #### 功能描述 查询系统支持的语言列表，用于动态生成语言选择器的下拉选项。 #### 请求方式 GET #### 请求路径 `/system/language/list` #### 请求参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | pageNum | Number | 否 | 页码，默认 1 | | pageSize | Number | 否 | 每页条数，默认 10 | | langCode | String | 否 | 语言代码（后端格式，如 zh_CN） | | langName | String | 否 | 语言名称（如 简体中文） | | status | String | 否 | 状态（0 正常，1 停用） | #### 响应参数 | 参数名 | 类型 | 说明 | |--------|------|------| | code | Number | 状态码（200 成功，其他失败） | | msg | String | 提示信息 | | rows | Array | 语言列表数据 | | rows[].id | Number | 语言 ID | | rows[].langCode | String | 语言代码（后端格式，如 zh_CN） | | rows[].langName | String | 语言名称（如 简体中文） | | rows[].status | String | 状态（0 正常，1 停用） | | rows[].createTime | String | 创建时间 | | rows[].updateTime | String | 更新时间 | | total | Number | 总记录数 | #### 成功示例 ```json { "code": 200, "msg": "查询成功", "rows": [ { "id": 1, "langCode": "zh_CN", "langName": "简体中文", "status": "0", "createTime": "2026-01-26 10:00:00", "updateTime": "2026-01-26 10:00:00" }, { "id": 2, "langCode": "en_US", "langName": "English", "status": "0", "createTime": "2026-01-26 10:00:00", "updateTime": "2026-01-26 10:00:00" } ], "total": 2 } ``` #### 失败示例 ```json { "code": 500, "msg": "查询失败" } ``` #### 错误码 | 错误码 | 说明 | |--------|------| | 500 | 查询失败 | --- ### 接口 2：获取当前语言偏好 #### 功能描述 获取当前登录用户的语言偏好，用于登录后自动同步并应用用户的语言偏好。 #### 请求方式 GET #### 请求路径 `/system/i18n/currentLocale` #### 请求参数 无 #### 响应参数 | 参数名 | 类型 | 说明 | |--------|------|------| | code | Number | 状态码（200 成功，其他失败） | | msg | String | 提示信息 | | data | Object | 语言偏好数据 | | data.langCode | String | 语言代码（后端格式，如 zh_CN） | #### 成功示例 ```json { "code": 200, "msg": "查询成功", "data": { "langCode": "zh_CN" } } ``` #### 失败示例 ```json { "code": 500, "msg": "查询失败" } ``` #### 错误码 | 错误码 | 说明 | |--------|------| | 401 | 用户未登录 | | 500 | 查询失败 | --- ### 接口 3：更新用户语言偏好 #### 功能描述 更新当前登录用户的语言偏好，用于用户切换语言时同步到后端。 #### 请求方式 PUT #### 请求路径 `/system/i18n/updateLocale` #### 请求参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | langCode | String | 是 | 语言代码（后端格式，如 zh_CN） | #### 请求示例 ```json { "langCode": "zh_CN" } ``` #### 响应参数 | 参数名 | 类型 | 说明 | |--------|------|------| | code | Number | 状态码（200 成功，其他失败） | | msg | String | 提示信息 | #### 成功示例 ```json { "code": 200, "msg": "更新成功" } ``` #### 失败示例 ```json { "code": 500, "msg": "更新失败" } ``` #### 错误码 | 错误码 | 说明 | |--------|------| | 401 | 用户未登录 | | 500 | 更新失败 | --- ### 接口 4：查询国际化资源列表 #### 功能描述 查询指定语言的国际化资源列表，用于远程加载翻译资源。 #### 请求方式 GET #### 请求路径 `/system/i18nresource/list` #### 请求参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | pageNum | Number | 否 | 页码，默认 1 | | pageSize | Number | 否 | 每页条数，默认 10 | | langCode | String | 否 | 语言代码（后端格式，如 zh_CN） | | moduleName | String | 否 | 模块名称（如 common、layout、login） | | resourceKey | String | 否 | 资源键（如 login.button.login） | | resourceValue | String | 否 | 资源值（如 登录） | #### 响应参数 | 参数名 | 类型 | 说明 | |--------|------|------| | code | Number | 状态码（200 成功，其他失败） | | msg | String | 提示信息 | | rows | Array | 国际化资源列表数据 | | rows[].id | Number | 资源 ID | | rows[].langCode | String | 语言代码（后端格式，如 zh_CN） | | rows[].moduleName | String | 模块名称（如 common、layout、login） | | rows[].resourceKey | String | 资源键（如 login.button.login） | | rows[].resourceValue | String | 资源值（如 登录） | | rows[].createTime | String | 创建时间 | | rows[].updateTime | String | 更新时间 | | total | Number | 总记录数 | #### 成功示例 ```json { "code": 200, "msg": "查询成功", "rows": [ { "id": 1, "langCode": "zh_CN", "moduleName": "common", "resourceKey": "common.ok", "resourceValue": "确定", "createTime": "2026-01-26 10:00:00", "updateTime": "2026-01-26 10:00:00" }, { "id": 2, "langCode": "zh_CN", "moduleName": "login", "resourceKey": "login.button.login", "resourceValue": "登录", "createTime": "2026-01-26 10:00:00", "updateTime": "2026-01-26 10:00:00" } ], "total": 2 } ``` #### 失败示例 ```json { "code": 500, "msg": "查询失败" } ``` #### 错误码 | 错误码 | 说明 | |--------|------| | 500 | 查询失败 | --- ## 错误码汇总 | 错误码 | 说明 | 处理建议 | |--------|------|----------| | 200 | 操作成功 | 无 | | 401 | 用户未登录 | 跳转到登录页面 | | 500 | 操作失败 | 显示错误提示，联系管理员 | ## 使用示例 ### 示例 1：动态获取语言列表 ```javascript import { listLanguage } from '@/api/system/language' async function loadLanguageList() { try { const response = await listLanguage({ status: '0' }) const languageOptions = response.rows .filter(item => item.status === '0') .map(item => ({ label: item.langName, value: item.langCode.replace('_', '-') })) console.log('语言列表：', languageOptions) } catch (error) { console.error('加载语言列表失败：', error) } } ``` ### 示例 2：获取用户语言偏好 ```javascript import { getCurrentLocale } from '@/api/system/language' import { toFrontend } from '@/utils/langFormat' async function syncUserLanguagePreference() { try { const response = await getCurrentLocale() const remoteLang = toFrontend(response.data.langCode) console.log('用户语言偏好：', remoteLang) // 应用用户语言偏好 appStore.setLanguage(remoteLang) } catch (error) { console.error('获取用户语言偏好失败：', error) } } ``` ### 示例 3：更新用户语言偏好 ```javascript import { updateLocale } from '@/api/system/language' import { toBackend } from '@/utils/langFormat' async function updateUserLanguagePreference(lang) { try { await updateLocale({ langCode: toBackend(lang) }) console.log('更新用户语言偏好成功') } catch (error) { console.error('更新用户语言偏好失败：', error) } } ``` ### 示例 4：加载远程翻译资源 ```javascript import { listI18nResource } from '@/api/system/language' async function loadRemoteMessages(lang) { try { const response = await listI18nResource({ pageNum: 1, pageSize: 9999, langCode: lang }) const messages = transformToNestedObject(response.rows) console.log('远程翻译资源：', messages) return messages } catch (error) { console.error('加载远程翻译资源失败：', error) return {} } } function transformToNestedObject(rows) { const result = {} rows.forEach(row => { const keys = row.resourceKey.split('.') let current = result keys.forEach((key, index) => { if (index === keys.length - 1) { current[key] = row.resourceValue } else { if (!current[key]) { current[key] = {} } current = current[key] } }) }) return result } ``` ## 相关文档 - [需求文档](../requirements/2026-01-26-002-03-前端国际化-动态资源.md) - [设计文档](../design/2026-01-26-002-03-前端国际化-动态资源-设计.md) - [决策记录](../decisions/2026-01-26-002-03-ADR-前端国际化-动态资源实现策略决策.md) - [提示词文档](../prompts/2026-01-26-002-03-prompt-前端国际化-动态资源.md) - [变更日志](../changelog/2026-01-26-002-03-changelog.md) - [复盘文档](../retros/2026-01-26-002-03-retro.md)