kris/datai-vue
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop
datai-vue/docs/api-docs/2026-01-26-002-03-api.md

9.3 KiB
Raw Permalink Blame History

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 总记录数

成功示例

{
  "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
}

失败示例

{
  "code": 500,
  "msg": "查询失败"
}

错误码

错误码 说明
500 查询失败

接口 2：获取当前语言偏好

功能描述

获取当前登录用户的语言偏好，用于登录后自动同步并应用用户的语言偏好。

请求方式

GET

请求路径

/system/i18n/currentLocale

请求参数

无

响应参数

参数名 类型 说明
code Number 状态码（200 成功，其他失败）
msg String 提示信息
data Object 语言偏好数据
data.langCode String 语言代码（后端格式，如 zh_CN）

成功示例

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "langCode": "zh_CN"
  }
}

失败示例

{
  "code": 500,
  "msg": "查询失败"
}

错误码

错误码 说明
401 用户未登录
500 查询失败

接口 3：更新用户语言偏好

功能描述

更新当前登录用户的语言偏好，用于用户切换语言时同步到后端。

请求方式

PUT

请求路径

/system/i18n/updateLocale

请求参数

参数名 类型 必填 说明
langCode String 是 语言代码（后端格式，如 zh_CN）

请求示例

{
  "langCode": "zh_CN"
}

响应参数

参数名 类型 说明
code Number 状态码（200 成功，其他失败）
msg String 提示信息

成功示例

{
  "code": 200,
  "msg": "更新成功"
}

失败示例

{
  "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 总记录数

成功示例

{
  "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
}

失败示例

{
  "code": 500,
  "msg": "查询失败"
}

错误码

错误码 说明
500 查询失败

错误码汇总

错误码 说明 处理建议
200 操作成功 无
401 用户未登录 跳转到登录页面
500 操作失败 显示错误提示，联系管理员

使用示例

示例 1：动态获取语言列表

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：获取用户语言偏好

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：更新用户语言偏好

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：加载远程翻译资源

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
}

相关文档