dros/docs/实现/多语言切换功能.md

多语言切换功能实现文档

功能概述

在 SystemZone 区域添加语言管理按钮（mgr按钮），点击后以弹出对话框的形式显示多语言列表，支持选择语言并保存，实现系统语言切换。

需求分析

接口信息

1. 获取多语言列表

• 接口: GET /dr/api/v1/pub/language
• 说明: 公开接口，无需认证

• 响应示例:

  {
  "code": "0x000000",
  "data": [
  {
    "language": "en",
    "display": "English"
  },
  {
    "language": "zh",
    "display": "简体中文"
  }
  ],
  "description": "Success",
  "solution": ""
  }
  

  2. 修改系统语言

  • 接口: POST /api/v1/auth/manage/language
  • 说明: 需要认证，需要在请求头中携带 token
  • 请求头:
  • Authorization: Bearer {token}
  • Language: en 或 zh
  • Product: DROS 或 VETDROS
  • Source: Electron 或 Browser 或 Android
  • 请求体: json { "lang": "en_US.UTF-8" // 或 "zh_CN.UTF-8" }

• 响应示例:

  {
  "code": "0x000000",
  "description": "Success",
  "solution": "",
  "data": {}
  }
  

  语言代码映射关系

  • en -> en_US.UTF-8
  • zh -> zh_CN.UTF-8

  实现方案

  1. 状态管理（Redux）

  扩展 src/states/i18nSlice.ts，添加语言管理功能：

  • 新增状态字段：
  • availableLanguages: 可用语言列表
  • selectedLanguage: 当前选中的语言
  • languagesLoading: 加载语言列表状态
  • savingLanguage: 保存语言设置状态

  • languageError: 语言操作错误信息

  • 新增 async thunks：

  • loadAvailableLanguages: 加载可用语言列表

  • updateSystemLanguage: 更新系统语言

  • 新增 reducers：

  • setSelectedLanguage: 设置选中的语言

  • clearLanguageError: 清除语言错误

  2. API层实现

  创建 src/API/language.ts 文件，包含以下接口：

  // 获取多语言列表接口
  export interface LanguageItem {
  language: string;  // en, zh
  display: string;   // English, 简体中文
  }
  
  export interface LanguageListResponse {
  code: string;
  data: LanguageItem[];
  description: string;
  solution: string;
  }
  
  // 修改系统语言接口
  export interface ChangeLanguageRequest {
  lang: string;  // en_US.UTF-8, zh_CN.UTF-8
  }
  
  export interface ChangeLanguageResponse {
  code: string;
  description: string;
  solution: string;
  data: {};
  }
  

接口方法：

• getLanguageList(): 获取多语言列表
• changeLanguage(lang: string): 修改系统语言

3. 组件层实现

3.1 创建语言设置对话框组件

创建 src/components/LanguageSettingModal.tsx，实现以下功能：

• 使用 Redux 状态管理，通过 useAppSelector 和 useAppDispatch hooks
• 自动加载语言列表（仅在列表为空时）
• 使用 Ant Design 的 Select 组件作为下拉选择框
• 保存按钮，调用修改语言接口
• 取消按钮，关闭对话框
• 参考 ExitModal 的实现风格

组件特性：

• 无本地状态，所有状态由 Redux 管理
• 居中显示
• 宽度 500px
• 包含语言下拉选择和操作按钮
• 提供成功/失败的消息提示
• 自动显示加载状态和错误信息

3.2 更新 SystemZone 组件

在 src/layouts/SystemZone.tsx 中：

• 将"配置"按钮改为"语言管理"按钮（mgr按钮）
• 移除 disabled 属性
• 添加状态管理和点击事件处理
• 集成 LanguageSettingModal 组件

4. 实现步骤

1. 创建 API 文件 (src/API/language.ts)

   • 定义接口类型
   • 实现 getLanguageList 方法
   • 实现 changeLanguage 方法
   • 处理语言代码映射 (en -> en_US.UTF-8, zh -> zh_CN.UTF-8)

2. 扩展 i18nSlice (src/states/i18nSlice.ts)

   • 添加语言管理相关状态
   • 实现 loadAvailableLanguages async thunk
   • 实现 updateSystemLanguage async thunk
   • 添加相关 reducers

3. 创建语言设置对话框组件 (src/components/LanguageSettingModal.tsx)

   • 使用 Modal 组件作为容器
   • 使用 Select 组件作为语言选择器
   • 使用 Redux hooks 连接状态
   • 实现加载语言列表逻辑
   • 实现保存语言设置逻辑
   • 添加错误处理和消息提示

4. 更新 SystemZone 组件 (src/layouts/SystemZone.tsx)

   • 添加语言设置对话框的状态管理
   • 更新"配置"按钮为"语言管理"按钮
   • 添加按钮点击事件
   • 集成 LanguageSettingModal 组件

5. 测试验证

   • 验证语言列表正确加载
   • 验证语言切换功能正常
   • 验证错误处理机制
   • 验证用户交互体验
   • 验证状态在 Redux 中正确管理

技术细节

语言代码转换

// 从简短代码转换为完整代码
const languageMap = {
  'en': 'en_US.UTF-8',
  'zh': 'zh_CN.UTF-8'
};

function mapLanguageCode(shortCode: string): string {
  return languageMap[shortCode] || shortCode;
}

请求头处理

修改语言接口需要携带特定的请求头，这些会在 axios interceptor 中统一处理：

• Authorization: 从 Redux store 中获取
• Language: 当前系统语言
• Product: 从配置中获取
• Source: 固定为 Electron

UI/UX 设计

对话框布局

+----------------------------------+
|      语言设置                      |
+----------------------------------+
|                                  |
|  选择语言：                        |
|  [                     ▼]        |
|                                  |
|  [取消]              [保存]       |
|                                  |
+----------------------------------+

交互流程

1. 用户点击"语言管理"按钮
2. 弹出语言设置对话框
3. 自动加载可用语言列表
4. 用户从下拉框选择目标语言
5. 点击"保存"按钮
6. 调用 API 修改系统语言
7. 显示成功/失败提示
8. 关闭对话框

注意事项

1. 错误处理：

   • API 调用失败时显示错误提示
   • 网络异常时提供友好提示

2. 加载状态：

   • 语言列表加载时显示 loading 状态
   • 保存操作时禁用按钮防止重复提交

3. 用户体验：

   • 操作成功后显示成功提示
   • 按钮状态合理管理

4. 代码规范：

   • 遵循项目现有代码风格
   • 使用 TypeScript 类型定义
   • 组件解耦，职责清晰

文件清单

新增文件

• src/API/language.ts - 语言相关API

修改文件

• src/states/i18nSlice.ts - 扩展添加语言管理功能
• src/components/LanguageSettingModal.tsx - 语言设置对话框组件（使用 Redux 状态）
• src/layouts/SystemZone.tsx - 集成语言管理功能

验收标准

• 能够正确获取并显示语言列表
• 能够成功切换系统语言
• 操作有适当的加载状态提示
• 有完善的错误处理机制
• 代码符合项目规范
• UI 与现有组件风格一致
• 语言状态由 Redux 统一管理
• 组件无本地状态，完全依赖 Redux
• 通过实际运行测试验证功能

重构说明

Redux 状态管理优化

为了更好地管理应用状态，我们将语言相关的状态从组件本地状态提升到 Redux store 中：

优势：

1. 状态共享：整个应用可以访问和使用语言列表
2. 缓存优化：语言列表只需加载一次，存储在 Redux 中复用
3. 代码简洁：组件逻辑更简单，只负责 UI 渲染
4. 可测试性：Redux 状态管理更易于测试
5. 一致性：与项目现有的状态管理模式保持一致

实现方式：

• 在 i18nSlice.ts 中添加 availableLanguages、selectedLanguage 等状态
• 使用 createAsyncThunk 处理异步 API 调用
• 组件通过 useAppSelector 读取状态，通过 useAppDispatch 触发 actions