667 lines
21 KiB
Markdown
667 lines
21 KiB
Markdown
# ClawX 项目国际化 (i18n) 实现参考
|
||
|
||
本文档分析了 ClawX 项目的国际化实现架构，为 zn-ai 项目的国际化改进提供参考和开发计划。
|
||
|
||
## 概述
|
||
|
||
ClawX 使用 **React + i18next** 框架实现国际化，具有以下特点：
|
||
|
||
- **模块化语言文件**：按功能模块组织翻译内容
|
||
- **多语言支持**：支持英文 (en)、中文 (zh)、日文 (ja)
|
||
- **智能语言检测**：自动根据系统语言和用户偏好选择语言
|
||
- **状态管理集成**：与 Zustand 状态存储深度集成，支持持久化
|
||
- **类型安全**：完整的 TypeScript 类型支持
|
||
|
||
## 架构设计
|
||
|
||
### 核心文件结构
|
||
|
||
```
|
||
src/
|
||
├── i18n/
|
||
│ ├── locales/
|
||
│ │ ├── en/ # 英文翻译
|
||
│ │ │ ├── common.json # 通用翻译
|
||
│ │ │ ├── settings.json # 设置页面翻译
|
||
│ │ │ ├── dashboard.json # 仪表盘翻译
|
||
│ │ │ ├── chat.json # 聊天页面翻译
|
||
│ │ │ ├── channels.json # 频道页面翻译
|
||
│ │ │ ├── agents.json # 代理页面翻译
|
||
│ │ │ ├── skills.json # 技能页面翻译
|
||
│ │ │ ├── cron.json # 定时任务翻译
|
||
│ │ │ └── setup.json # 设置向导翻译
|
||
│ │ ├── zh/ # 中文翻译 (同上结构)
|
||
│ │ └── ja/ # 日文翻译 (同上结构)
|
||
│ └── index.ts # i18n 配置入口
|
||
├── shared/
|
||
│ └── language.ts # 语言解析工具
|
||
└── stores/
|
||
└── settings.ts # 语言状态管理
|
||
```
|
||
|
||
### 技术栈
|
||
|
||
```json
|
||
{
|
||
"dependencies": {
|
||
"i18next": "^25.8.11",
|
||
"react-i18next": "^16.5.4"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 核心代码解析
|
||
|
||
### 1. 语言解析工具 (`shared/language.ts`)
|
||
|
||
```typescript
|
||
export const SUPPORTED_LANGUAGE_CODES = ['en', 'zh', 'ja'] as const;
|
||
export type LanguageCode = (typeof SUPPORTED_LANGUAGE_CODES)[number];
|
||
|
||
// 标准化语言代码（处理 zh-CN、zh_TW 等变体）
|
||
function normalizeLocale(locale: string | null | undefined): string {
|
||
return locale?.trim().toLowerCase().replaceAll('_', '-') ?? '';
|
||
}
|
||
|
||
// 解析支持的语言代码
|
||
export function resolveSupportedLanguage(
|
||
locale: string | null | undefined,
|
||
fallback: LanguageCode = 'en',
|
||
): LanguageCode {
|
||
const normalizedLocale = normalizeLocale(locale);
|
||
if (!normalizedLocale) return fallback;
|
||
|
||
const [baseLanguage] = normalizedLocale.split('-');
|
||
return SUPPORTED_LANGUAGE_CODE_SET.has(baseLanguage)
|
||
? (baseLanguage as LanguageCode)
|
||
: fallback;
|
||
}
|
||
```
|
||
|
||
**关键特性：**
|
||
- 自动处理语言变体（如 `zh-CN` → `zh`, `en-US` → `en`）
|
||
- 安全的默认值回退机制
|
||
- 类型安全的语言代码枚举
|
||
|
||
### 2. i18n 配置入口 (`src/i18n/index.ts`)
|
||
|
||
```typescript
|
||
import i18n from 'i18next';
|
||
import { initReactI18next } from 'react-i18next';
|
||
import { SUPPORTED_LANGUAGE_CODES, resolveSupportedLanguage } from '../../shared/language';
|
||
|
||
// 导入所有语言文件（按模块）
|
||
import enCommon from './locales/en/common.json';
|
||
import enSettings from './locales/en/settings.json';
|
||
// ... 其他模块导入
|
||
|
||
// 定义支持的语言列表（包含显示标签）
|
||
export const SUPPORTED_LANGUAGES = [
|
||
{ code: 'en', label: 'English' },
|
||
{ code: 'zh', label: '中文' },
|
||
{ code: 'ja', label: '日本語' },
|
||
] as const;
|
||
|
||
// 构建 i18next 资源结构
|
||
const resources = {
|
||
en: {
|
||
common: enCommon,
|
||
settings: enSettings,
|
||
// ... 其他命名空间
|
||
},
|
||
zh: { /* 同上结构 */ },
|
||
ja: { /* 同上结构 */ },
|
||
};
|
||
|
||
// 初始化 i18next
|
||
i18n
|
||
.use(initReactI18next)
|
||
.init({
|
||
resources,
|
||
lng: resolveSupportedLanguage(
|
||
typeof navigator !== 'undefined' ? navigator.language : undefined
|
||
),
|
||
fallbackLng: 'en',
|
||
supportedLngs: [...SUPPORTED_LANGUAGE_CODES],
|
||
defaultNS: 'common', // 默认命名空间
|
||
ns: ['common', 'settings', 'dashboard', 'chat', 'channels', 'agents', 'skills', 'cron', 'setup'],
|
||
interpolation: { escapeValue: false }, // React 已处理转义
|
||
react: { useSuspense: false },
|
||
});
|
||
|
||
export default i18n;
|
||
```
|
||
|
||
**配置亮点：**
|
||
- **多命名空间**：按功能模块分离，避免单个文件过大
|
||
- **智能语言检测**：自动根据浏览器语言选择
|
||
- **安全的回退机制**：确保始终有可用的翻译
|
||
- **React 优化**：禁用 Suspense 避免渲染问题
|
||
|
||
### 3. 状态管理集成 (`src/stores/settings.ts`)
|
||
|
||
```typescript
|
||
import i18n from '@/i18n';
|
||
import { resolveSupportedLanguage } from '../../shared/language';
|
||
|
||
interface SettingsState {
|
||
language: string;
|
||
// ... 其他设置
|
||
}
|
||
|
||
const defaultSettings = {
|
||
language: resolveSupportedLanguage(
|
||
typeof navigator !== 'undefined' ? navigator.language : undefined
|
||
),
|
||
// ... 其他默认值
|
||
};
|
||
|
||
export const useSettingsStore = create<SettingsState>()(
|
||
persist(
|
||
(set) => ({
|
||
...defaultSettings,
|
||
|
||
// 初始化时加载远程设置并同步 i18n
|
||
init: async () => {
|
||
try {
|
||
const settings = await hostApiFetch<Partial<typeof defaultSettings>>('/api/settings');
|
||
const resolvedLanguage = settings.language
|
||
? resolveSupportedLanguage(settings.language)
|
||
: undefined;
|
||
set((state) => ({
|
||
...state,
|
||
...settings,
|
||
...(resolvedLanguage ? { language: resolvedLanguage } : {}),
|
||
}));
|
||
if (resolvedLanguage) {
|
||
i18n.changeLanguage(resolvedLanguage); // 同步 i18n 实例
|
||
}
|
||
} catch { /* 降级处理 */ }
|
||
},
|
||
|
||
// 设置语言时同步更新 i18n 和远程存储
|
||
setLanguage: (language) => {
|
||
const resolvedLanguage = resolveSupportedLanguage(language);
|
||
i18n.changeLanguage(resolvedLanguage); // 1. 更新 i18n 实例
|
||
set({ language: resolvedLanguage }); // 2. 更新本地状态
|
||
void hostApiFetch('/api/settings/language', { // 3. 同步到主进程
|
||
method: 'PUT',
|
||
body: JSON.stringify({ value: resolvedLanguage }),
|
||
}).catch(() => { });
|
||
},
|
||
}),
|
||
{ name: 'clawx-settings' } // Zustand 持久化配置
|
||
)
|
||
);
|
||
```
|
||
|
||
**集成特点：**
|
||
- **三级同步**：i18n 实例 ↔ 本地状态 ↔ 主进程存储
|
||
- **持久化**：使用 localStorage 持久化用户偏好
|
||
- **错误处理**：网络失败时降级到本地存储
|
||
|
||
### 4. 应用集成 (`src/App.tsx`)
|
||
|
||
```typescript
|
||
import i18n from './i18n';
|
||
import { useSettingsStore } from './stores/settings';
|
||
|
||
function App() {
|
||
const language = useSettingsStore((state) => state.language);
|
||
|
||
// 挂载时同步 i18n 语言与持久化设置
|
||
useEffect(() => {
|
||
if (language && language !== i18n.language) {
|
||
i18n.changeLanguage(language);
|
||
}
|
||
}, [language]);
|
||
|
||
return <>{/* 应用内容 */}</>;
|
||
}
|
||
```
|
||
|
||
### 5. 组件使用示例 (`src/pages/Setup/index.tsx`)
|
||
|
||
```typescript
|
||
import { useTranslation } from 'react-i18next';
|
||
import type { TFunction } from 'i18next';
|
||
import { SUPPORTED_LANGUAGES } from '@/i18n';
|
||
|
||
export function Setup() {
|
||
// 使用多个命名空间
|
||
const { t, i18n } = useTranslation(['setup', 'channels']);
|
||
|
||
// 获取语言设置操作
|
||
const { language, setLanguage } = useSettingsStore();
|
||
|
||
// 动态翻译函数（用于生成动态内容）
|
||
const getSteps = (t: TFunction): SetupStep[] => [
|
||
{
|
||
id: 'welcome',
|
||
title: t('steps.welcome.title'), // setup 命名空间
|
||
description: t('steps.welcome.description'),
|
||
},
|
||
// ...
|
||
];
|
||
|
||
return (
|
||
<div>
|
||
{/* 直接翻译 */}
|
||
<h1>{t(`steps.${step.id}.title`)}</h1>
|
||
|
||
{/* 语言选择器 */}
|
||
<div className="flex justify-center gap-2 py-2">
|
||
{SUPPORTED_LANGUAGES.map((lang) => (
|
||
<Button
|
||
key={lang.code}
|
||
variant={language === lang.code ? 'secondary' : 'ghost'}
|
||
onClick={() => setLanguage(lang.code)}
|
||
>
|
||
{lang.label}
|
||
</Button>
|
||
))}
|
||
</div>
|
||
|
||
{/* 带参数的翻译 */}
|
||
<p>{t('runtime.status.gatewayRunning', { port: gatewayStatus.port })}</p>
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
**使用模式：**
|
||
- **命名空间**：`useTranslation(['setup', 'channels'])` 加载多个模块
|
||
- **动态键**：`t(`steps.${step.id}.title`)` 支持动态翻译键
|
||
- **参数插值**：`t('key', { param: value })` 支持动态内容
|
||
- **类型安全**：通过 `TFunction` 类型提供类型提示
|
||
|
||
## 语言文件结构
|
||
|
||
### 模块化设计
|
||
|
||
```json
|
||
// locales/zh/common.json
|
||
{
|
||
"sidebar": {
|
||
"chat": "聊天",
|
||
"newChat": "新对话",
|
||
"cronTasks": "定时任务",
|
||
"skills": "技能",
|
||
"agents": "Agents",
|
||
"channels": "频道",
|
||
"dashboard": "仪表盘",
|
||
"settings": "设置",
|
||
"devConsole": "开发者控制台",
|
||
"models": "模型",
|
||
"deleteSessionConfirm": "确定要删除对话 \"{{label}}\" 吗？",
|
||
"openClawPage": "OpenClaw 页面"
|
||
},
|
||
"actions": {
|
||
"save": "保存",
|
||
"cancel": "取消",
|
||
"delete": "删除",
|
||
"edit": "编辑",
|
||
"refresh": "刷新",
|
||
"close": "关闭",
|
||
"copy": "复制",
|
||
"search": "搜索",
|
||
"confirm": "确认",
|
||
"dismiss": "忽略"
|
||
},
|
||
"status": {
|
||
"running": "运行中",
|
||
"stopped": "已停止",
|
||
"error": "错误",
|
||
"connected": "已连接",
|
||
"disconnected": "已断开"
|
||
}
|
||
}
|
||
|
||
// locales/zh/setup.json (设置向导专用)
|
||
{
|
||
"steps": {
|
||
"welcome": {
|
||
"title": "欢迎使用 ClawX",
|
||
"description": "让我们快速完成初始设置"
|
||
},
|
||
"runtime": {
|
||
"title": "运行环境检查",
|
||
"description": "确保所有依赖项已就绪"
|
||
}
|
||
},
|
||
"welcome": {
|
||
"title": "欢迎！",
|
||
"description": "ClawX 是一个基于 OpenClaw 的图形化 AI 助手...",
|
||
"features": {
|
||
"noCommand": "无需命令行经验",
|
||
"modernUI": "现代化的图形界面",
|
||
"bundles": "预置技能包",
|
||
"crossPlatform": "跨平台支持"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**组织原则：**
|
||
1. **按功能模块分离**：避免单个文件过大
|
||
2. **嵌套结构**：使用对象嵌套提高可读性
|
||
3. **参数化**：支持 `{{variable}}` 插值
|
||
4. **上下文清晰**：键名反映使用场景
|
||
|
||
## 构建配置
|
||
|
||
### package.json 依赖
|
||
|
||
```json
|
||
{
|
||
"devDependencies": {
|
||
"i18next": "^25.8.11",
|
||
"react-i18next": "^16.5.4"
|
||
}
|
||
}
|
||
```
|
||
|
||
### Vite 配置
|
||
|
||
无需特殊配置，i18next 与构建工具无关。
|
||
|
||
## 为 zn-ai 项目的改进建议
|
||
|
||
### 当前 zn-ai i18n 状态分析
|
||
|
||
zn-ai 项目目前使用 Vue 3 + vue-i18n，但实现较为简单：
|
||
|
||
**优势：**
|
||
- ✅ 已集成 vue-i18n 基础框架
|
||
- ✅ 基本的中英文翻译已就绪
|
||
- ✅ 目录结构已优化 (`src/i18n/`)
|
||
|
||
**不足：**
|
||
- ❌ 缺少模块化语言文件组织
|
||
- ❌ 缺乏智能语言检测和解析
|
||
- ❌ 未与状态管理集成（持久化）
|
||
- ❌ 没有类型安全的语言代码
|
||
- ❌ 缺少多命名空间支持
|
||
|
||
### 推荐架构迁移
|
||
|
||
鉴于 zn-ai 使用 Vue 3，建议采用以下架构：
|
||
|
||
```
|
||
src/i18n/
|
||
├── locales/
|
||
│ ├── en/ # 英文模块
|
||
│ │ ├── common.json # 通用翻译
|
||
│ │ ├── login.json # 登录页面
|
||
│ │ ├── dashboard.json # 仪表盘
|
||
│ │ ├── task.json # 任务管理
|
||
│ │ ├── rate.json # 费率管理
|
||
│ │ ├── knowledge.json # 知识库
|
||
│ │ ├── setting.json # 设置页面
|
||
│ │ └── component.json # 组件翻译
|
||
│ ├── zh/ # 中文模块（同上结构）
|
||
│ └── ja/ # 日文模块（可选）
|
||
├── constants.ts # 语言常量定义
|
||
├── resolver.ts # 语言解析工具
|
||
├── store.ts # 语言状态管理
|
||
└── index.ts # vue-i18n 配置
|
||
```
|
||
|
||
### 技术选择
|
||
|
||
1. **核心库**：继续使用 `vue-i18n@9.x`（与 Vue 3 兼容）
|
||
2. **状态管理**：集成到现有的 Pinia store
|
||
3. **类型安全**：使用 TypeScript 增强类型提示
|
||
4. **持久化**：通过 `electron-store` 或 `localStorage`
|
||
|
||
## 当前进展
|
||
|
||
### 语言选择器 UI 试点实现
|
||
已在设置页面的版本信息组件 (`src/pages/setting/components/Version/index.vue`) 中实现语言选择器 UI，作为国际化改进的试点。
|
||
|
||
**实现内容：**
|
||
- 添加了语言设置区域，包含三个按钮：中文、English、日本語
|
||
- 默认语言为中文，当前选中语言高亮显示
|
||
- 集成了现有的 `vue-i18n` 实例，使用 `setLanguage`/`getLanguage` API
|
||
- 支持日语语言文件占位 (`ja.json`)
|
||
|
||
**技术细节：**
|
||
- 使用 Element Plus 按钮组件 (`el-button`)
|
||
- 响应式当前语言状态管理
|
||
- 类型安全的语言代码 (`LanguageType`)
|
||
- 遵循 ClawX 项目的 UI 设计模式
|
||
|
||
**下一步：**
|
||
- 将语言选择器集成到全局设置页面
|
||
- 添加语言状态持久化（Pinia Store）
|
||
- 完善日语翻译内容
|
||
- 推广到其他组件
|
||
|
||
## 开发计划
|
||
|
||
### 第一阶段：基础架构升级 (预计: 2-3 天)
|
||
|
||
**目标**：建立模块化、类型安全的 i18n 基础架构
|
||
|
||
1. **语言文件重组**
|
||
- 创建模块化目录结构 (`src/i18n/locales/en/`, `src/i18n/locales/zh/`)
|
||
- 按功能拆分现有翻译：`common`, `login`, `dashboard`, `task`, `rate`, `knowledge`, `setting`, `component`
|
||
- 保持向后兼容，逐步迁移
|
||
|
||
2. **核心工具开发**
|
||
- 创建 `src/i18n/constants.ts`：定义 `SUPPORTED_LANGUAGES` 等常量
|
||
- 创建 `src/i18n/resolver.ts`：语言检测和解析工具
|
||
- 增强类型定义：`LanguageCode`, `NamespaceKey` 等
|
||
|
||
3. **vue-i18n 配置升级**
|
||
- 重写 `src/i18n/index.ts`：支持多命名空间、智能语言检测
|
||
- 配置回退链：`zh-CN` → `zh` → `en`
|
||
- 添加开发调试工具
|
||
|
||
### 第二阶段：状态管理集成 (预计: 1-2 天)
|
||
|
||
**目标**：实现语言设置的持久化和全应用同步
|
||
|
||
1. **Pinia Store 创建**
|
||
- 创建 `src/store/locale.ts`：管理语言状态
|
||
- 集成语言解析工具
|
||
- 实现与 vue-i18n 实例的同步
|
||
|
||
2. **持久化机制**
|
||
- 集成 `electron-store` 或使用 `localStorage`
|
||
- 实现设置保存/加载
|
||
- 添加错误处理和降级方案
|
||
|
||
3. **主进程同步**（可选）
|
||
- 通过 IPC 与主进程设置同步
|
||
- 系统语言变化监听
|
||
|
||
### 第三阶段：组件集成优化 (预计: 2-3 天)
|
||
|
||
**目标**：更新所有组件使用新的 i18n 架构
|
||
|
||
1. **工具函数创建**
|
||
- 创建 `useLocale()` composable：提供类型安全的翻译函数
|
||
- 添加 `t()` 函数的 TypeScript 增强
|
||
- 开发批量翻译更新脚本
|
||
|
||
2. **组件迁移**
|
||
- 按页面逐步更新组件：Login, Dashboard, Task, Rate, Knowledge, Setting
|
||
- 更新路由和菜单的国际化
|
||
- 验证所有动态插值功能
|
||
|
||
3. **开发体验优化**
|
||
- 添加 VSCode 扩展建议 (i18n-ally)
|
||
- 配置提取工具
|
||
- 添加缺失翻译标记
|
||
|
||
### 第四阶段：高级功能与测试 (预计: 1-2 天)
|
||
|
||
**目标**：添加高级功能和确保质量
|
||
|
||
1. **语言切换界面**
|
||
- 在设置页面添加语言选择器
|
||
- 实时预览功能
|
||
- 语言包元信息显示（作者、版本）
|
||
|
||
2. **测试与验证**
|
||
- 单元测试：语言解析工具
|
||
- 集成测试：语言切换流程
|
||
- E2E 测试：多语言场景
|
||
|
||
3. **构建优化**
|
||
- 按需加载语言包
|
||
- 构建时提取和验证
|
||
- 生产环境优化
|
||
|
||
### 第五阶段：维护与扩展 (持续)
|
||
|
||
**目标**：建立可持续的国际化工作流
|
||
|
||
1. **工作流建立**
|
||
- 翻译提取脚本
|
||
- 与翻译平台集成方案
|
||
- 版本控制和协作流程
|
||
|
||
2. **扩展准备**
|
||
- 支持 RTL 语言（阿拉伯语等）
|
||
- 日期、数字、货币格式化
|
||
- 复数规则支持
|
||
|
||
3. **文档完善**
|
||
- 开发者指南
|
||
- 翻译贡献指南
|
||
- 最佳实践文档
|
||
|
||
## 实施优先级
|
||
|
||
### 高优先级（立即执行）
|
||
1. 模块化语言文件重组
|
||
2. 语言解析工具开发
|
||
3. vue-i18n 配置升级
|
||
4. Pinia store 集成
|
||
|
||
### 中优先级（本周内）
|
||
1. 组件迁移（按页面）
|
||
2. 语言切换界面
|
||
3. 持久化实现
|
||
|
||
### 低优先级（后续迭代）
|
||
1. 主进程同步
|
||
2. 高级格式化功能
|
||
3. 自动化翻译流程
|
||
|
||
## 预期收益
|
||
|
||
1. **可维护性**：模块化结构使翻译更易管理
|
||
2. **开发者体验**：类型安全、智能提示、调试工具
|
||
3. **用户体验**：智能语言检测、无缝切换、持久化偏好
|
||
4. **扩展性**：轻松添加新语言、支持高级 i18n 功能
|
||
5. **代码质量**：统一模式、减少硬编码、便于测试
|
||
|
||
## 具体实施任务清单（第一阶段）
|
||
|
||
### 任务 0：语言选择器 UI 试点（已完成）
|
||
- [x] 在设置页面版本组件中添加语言选择器 UI (`src/pages/setting/components/Version/index.vue`)
|
||
- [x] 实现三个语言按钮：中文、English、日本語，默认选中中文
|
||
- [x] 集成现有 `vue-i18n` API (`setLanguage`/`getLanguage`)
|
||
- [x] 添加日语语言文件占位 (`src/i18n/locales/ja.json`)
|
||
- [x] 导出 `LanguageType` 类型供组件使用
|
||
|
||
### 任务 1：语言文件重组
|
||
- [x] 创建目录结构：`src/i18n/locales/en/` 和 `src/i18n/locales/zh/`
|
||
- [ ] 分析现有翻译内容，按功能模块拆分：
|
||
- `common.json`：通用翻译（按钮、状态、提示）
|
||
- `login.json`：登录页面相关
|
||
- `dashboard.json`：仪表盘相关
|
||
- `task.json`：任务管理相关
|
||
- `rate.json`：费率管理相关
|
||
- `knowledge.json`：知识库相关
|
||
- `setting.json`：设置页面相关
|
||
- `component.json`：组件专用翻译
|
||
- [ ] 迁移现有翻译内容到新结构
|
||
- [ ] 验证 JSON 格式正确性
|
||
|
||
### 任务 2：核心工具开发
|
||
- [ ] 创建 `src/i18n/constants.ts`：
|
||
```typescript
|
||
export const SUPPORTED_LANGUAGE_CODES = ['en', 'zh', 'ja'] as const;
|
||
export type LanguageCode = (typeof SUPPORTED_LANGUAGE_CODES)[number];
|
||
export const SUPPORTED_LANGUAGES = [
|
||
{ code: 'en', label: 'English' },
|
||
{ code: 'zh', label: '中文' },
|
||
{ code: 'ja', label: '日本語' },
|
||
] as const;
|
||
```
|
||
- [ ] 创建 `src/i18n/resolver.ts`：
|
||
- `normalizeLocale()`：标准化语言代码
|
||
- `resolveSupportedLanguage()`：解析支持的语言
|
||
- 处理 `zh-CN`、`zh-TW`、`en-US` 等变体
|
||
- [ ] 添加类型定义：`LanguageCode`、`Namespace`、`TranslationKey` 等
|
||
|
||
### 任务 3：vue-i18n 配置升级
|
||
- [ ] 重写 `src/i18n/index.ts`：
|
||
- 支持多命名空间导入
|
||
- 集成语言解析工具
|
||
- 配置智能回退链：`zh-CN` → `zh` → `en`
|
||
- 添加开发调试选项
|
||
- [ ] 验证配置正确性：
|
||
- 运行 `npm run typecheck` 检查类型
|
||
- 运行 `npm run build:vite` 验证构建
|
||
- 启动开发服务器测试基础功能
|
||
|
||
### 任务 4：Pinia Store 集成
|
||
- [ ] 创建 `src/store/locale.ts`：
|
||
- 状态：`language: LanguageCode`
|
||
- 动作：`setLanguage(lang: LanguageCode)`
|
||
- 持久化：集成 `localStorage` 或 `electron-store`
|
||
- [ ] 实现与 vue-i18n 实例的同步：
|
||
- Store 初始化时读取持久化设置
|
||
- 语言切换时更新 i18n 实例
|
||
- 监听 i18n 语言变化更新 Store
|
||
- [ ] 在 `src/main.ts` 中集成 Store
|
||
|
||
### 任务 5：基础组件迁移（试点）
|
||
- [ ] 创建 `src/composables/useLocale.ts`：
|
||
- 提供类型安全的 `t()` 函数
|
||
- 集成命名空间支持
|
||
- 添加语言切换功能
|
||
- [ ] 迁移登录页面 (`src/pages/login/index.vue`)：
|
||
- 使用新的 `useLocale()` composable
|
||
- 更新所有静态文本为翻译键
|
||
- 验证动态插值功能
|
||
- [ ] 迁移侧边栏菜单：
|
||
- 更新菜单项文本
|
||
- 验证语言切换实时生效
|
||
|
||
### 验收标准
|
||
- [ ] 类型检查通过 (`npm run typecheck`)
|
||
- [ ] 生产构建通过 (`npm run build:vite`)
|
||
- [ ] 开发服务器正常启动 (`npm run dev`)
|
||
- [ ] 中英文切换功能正常
|
||
- [ ] 语言设置持久化生效
|
||
- [ ] 控制台无 i18n 相关错误
|
||
|
||
## 第一阶段完成状态
|
||
|
||
### 任务完成情况
|
||
- ✅ **任务 0：语言选择器 UI 试点** - 已完成（设置页面版本组件）
|
||
- ✅ **任务 1：语言文件重组** - 已完成（创建模块化目录结构，拆分现有翻译）
|
||
- ✅ **任务 2：核心工具开发** - 已完成（创建 constants.ts 和 resolver.ts）
|
||
- ✅ **任务 3：vue-i18n配置升级** - 已完成（重写 index.ts，支持多命名空间）
|
||
- ✅ **任务 4：Pinia Store集成** - 已完成（创建 locale.ts，实现状态管理）
|
||
- ✅ **任务 5：基础组件迁移试点** - 已完成（创建 useLocale composable，迁移登录页面）
|
||
|
||
### 验证结果
|
||
- ✅ 类型检查通过 (`npm run typecheck`)
|
||
- ✅ 生产构建通过 (`npm run build:vite`)
|
||
- ✅ 无代码缺失，保持向后兼容
|
||
|
||
### 下一步建议
|
||
第一阶段基础架构已成功建立，建议继续推进第二阶段（状态管理集成优化）和第三阶段（组件集成优化），逐步将新的国际化架构推广到全应用。
|
||
|
||
## 结论
|
||
|
||
ClawX 的 i18n 实现提供了一个优秀的参考架构，其核心思想——**模块化、类型安全、状态集成、智能解析**——完全适用于 zn-ai 项目。通过分阶段实施上述开发计划，zn-ai 可以在 1-2 周内建立专业级的国际化系统，为多语言用户提供更好的体验，同时提高代码的可维护性和开发效率。
|
||
|
||
建议立即开始第二阶段实施，逐步推广到全应用。 |