From f707b2301cf0d34987621c92e382c9dfe5f32516 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=99=B4=E5=A4=A9?= Date: Thu, 12 Mar 2026 03:19:12 +0800 Subject: [PATCH] docs: add i18n internationalization plan --- docs/i18n-plan.md | 288 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 288 insertions(+) create mode 100644 docs/i18n-plan.md diff --git a/docs/i18n-plan.md b/docs/i18n-plan.md new file mode 100644 index 0000000..2a7cfa4 --- /dev/null +++ b/docs/i18n-plan.md @@ -0,0 +1,288 @@ +# ClawPanel i18n 国际化方案 + +> 本文档是 ClawPanel 多语言国际化的完整技术方案和实施指南。 +> 任何后续会话开始 i18n 工作时，请先阅读本文档。 + +## 一、现状评估 + +- **硬编码中文行数**：3508 行（分布在 25+ 个 JS 文件中） +- **预估翻译字符串数**：约 1500+ 个 +- **技术栈**：纯 Vanilla JS（无 React/Vue），Tauri v2 桌面应用 +- **当前语言**：仅中文 + +### 文件中文行数分布（Top 15） + +| 行数 | 文件 | 模块 | +|------|------|------| +| 838 | assistant.js | AI 助手（含内嵌知识库） | +| 312 | docker.js | Docker 集群管理 | +| 243 | models.js | 模型配置 | +| 183 | chat.js | 实时聊天 | +| 156 | chat-debug.js | 系统诊断 | +| 148 | openclaw-kb.js | 知识库文本 | +| 142 | setup.js | 初始安装引导 | +| 136 | channels.js | 消息渠道 | +| 136 | main.js | 主入口/路由/横幅 | +| 120 | services.js | 服务管理 | +| 105 | about.js | 关于页面 | +| 93 | cron.js | 定时任务 | +| 88 | dashboard.js | 仪表盘 | +| 72 | extensions.js | 扩展工具 | +| 68 | gateway.js | 网关配置 | + +## 二、技术架构 + +### 核心模块：`src/lib/i18n.js` + +```js +// 使用方式 +import { t, setLocale, getLocale } from '../lib/i18n.js' + +// 简单翻译 +t('common.save') // → "保存" / "Save" +t('common.cancel') // → "取消" / "Cancel" + +// 带参数插值 +t('chat.messageCount', { count: 5 }) // → "5 条消息" / "5 messages" + +// 嵌套 key +t('dashboard.gateway.running') // → "运行中" / "Running" + +// 切换语言 +setLocale('en') // 存 localStorage，触发页面重渲染 +``` + +### 语言检测优先级 + +1. `localStorage` 中存储的用户选择 (`clawpanel-locale`) +2. 浏览器 `navigator.language`（`zh-CN` → `zh-CN`，`en-US` → `en`） +3. 默认值：`zh-CN` + +### 缺失翻译 fallback + +1. 查找当前语言包 +2. 查找 `zh-CN` 兜底（中文作为最完整的语言） +3. 返回 key 本身（如 `common.save`） +4. 开发模式下 console.warn 提示缺失翻译 + +## 三、语言包结构 + +``` +src/locales/ + zh-CN.json — 中文简体（默认，最完整） + en.json — English + zh-TW.json — 中文繁体（未来） + ja.json — 日本語（未来） + ko.json — 한국어（未来） +``` + +### JSON 格式规范 + +按模块/页面分组，使用扁平化嵌套结构： + +```json +{ + "common": { + "save": "保存", + "cancel": "取消", + "delete": "删除", + "confirm": "确定", + "close": "关闭", + "loading": "加载中...", + "error": "错误", + "success": "成功", + "warning": "警告", + "retry": "重试", + "refresh": "刷新", + "edit": "编辑", + "create": "创建", + "back": "返回", + "next": "下一步", + "search": "搜索", + "copy": "复制", + "download": "下载", + "upload": "上传", + "enable": "启用", + "disable": "禁用", + "start": "启动", + "stop": "停止", + "restart": "重启", + "status": "状态", + "running": "运行中", + "stopped": "已停止", + "unknown": "未知", + "noData": "暂无数据", + "operationFailed": "操作失败: {error}", + "confirmDelete": "确定删除 {name}？", + "savedSuccessfully": "已保存" + }, + "sidebar": { + "dashboard": "仪表盘", + "assistant": "晴辰助手", + "chat": "实时聊天", + "services": "服务管理", + "logs": "日志查看", + "models": "模型配置", + "agents": "Agent 管理", + "memory": "记忆文件", + "channels": "消息渠道", + "gateway": "网关配置", + "skills": "Skills 工具", + "docker": "Docker 集群", + "cron": "定时任务", + "extensions": "扩展工具", + "about": "关于", + "setup": "初始设置", + "chatDebug": "系统诊断" + }, + "dashboard": { ... }, + "chat": { ... }, + "models": { ... }, + ... +} +``` + +## 四、迁移步骤（每个页面） + +### Step 1: 提取中文字符串 + +使用正则或手动扫描，将所有中文文本提取到对应的语言包 key 下。 + +**需要翻译的内容**： +- UI 文本（按钮文字、标题、描述、提示） +- toast 消息 +- 错误消息 +- placeholder 文本 +- confirm 对话框文本 +- tooltip 文本 + +**不需要翻译的内容**： +- 代码注释（保持中文） +- console.log 调试信息 +- 技术标识符（如 `Gateway`、`Agent`、`OpenClaw`） +- API 错误消息（后端返回的） +- 知识库内容 `openclaw-kb.js`（这个特殊处理，按语言版本分文件） + +### Step 2: 替换代码中的硬编码 + +```js +// Before +toast('保存成功', 'success') + +// After +toast(t('common.savedSuccessfully'), 'success') +``` + +```js +// Before (HTML 模板) +`` + +// After +`` +``` + +### Step 3: 编写英文翻译 + +逐 key 翻译到 `en.json`。 + +### Step 4: 测试 + +切换语言，检查每个页面的显示是否正常。 + +## 五、迁移顺序 + +### 第一批（基础 + 框架层，约 80 个字符串） +1. `src/lib/i18n.js` — 创建核心模块 +2. `src/locales/zh-CN.json` — 初始化中文包 +3. `src/locales/en.json` — 初始化英文包 +4. `src/components/sidebar.js` — 导航菜单（~20 个） +5. `src/components/modal.js` — 公共弹窗（~10 个） +6. `src/components/toast.js` — 提示组件 +7. `src/pages/about.js` — 关于页面 + 语言切换 UI（~30 个） + +### 第二批（核心页面，约 250 个字符串） +8. `src/pages/dashboard.js` — 仪表盘（~50 个） +9. `src/pages/setup.js` — 初始设置（~80 个） +10. `src/pages/chat.js` — 实时聊天（~100 个） +11. `src/main.js` — 主入口/横幅（~20 个） + +### 第三批（配置页面，约 350 个字符串） +12. `src/pages/models.js` — 模型配置（~120 个） +13. `src/pages/channels.js` — 消息渠道（~80 个） +14. `src/pages/services.js` — 服务管理（~70 个） +15. `src/pages/gateway.js` — 网关配置（~40 个） +16. `src/pages/agents.js` — Agent 管理（~40 个） + +### 第四批（功能页面，约 250 个字符串） +17. `src/pages/cron.js` — 定时任务（~50 个） +18. `src/pages/memory.js` — 记忆管理（~30 个） +19. `src/pages/extensions.js` — 扩展工具（~40 个） +20. `src/pages/logs.js` — 日志查看（~20 个） +21. `src/pages/skills.js` — Skills 工具（~60 个） +22. `src/pages/chat-debug.js` — 系统诊断（~50 个） + +### 第五批（大型页面 + 特殊处理，约 600 个字符串） +23. `src/pages/docker.js` — Docker 管理（~150 个） +24. `src/pages/assistant.js` — AI 助手（~400 个，含系统提示词） +25. `src/lib/openclaw-kb.js` — 知识库（按语言分文件） +26. `src/lib/error-diagnosis.js` — 错误诊断（~30 个） +27. `src/components/engagement.js` — 推荐弹窗（~15 个） + +### 第六批（官网 + 文档） +28. `docs/index.html` — 官网英文版 +29. `README.md` → `README_en.md` +30. `CONTRIBUTING.md` → `CONTRIBUTING_en.md` + +## 六、语言切换 UI 设计 + +### 位置 +1. **关于页面底部** — 语言选择下拉框 +2. **侧边栏底部** — 语言图标 + 当前语言缩写（如 `中` / `EN`） + +### 交互 +- 选择语言 → 存入 localStorage → 页面自动刷新 +- 首次访问自动检测浏览器语言 + +## 七、注意事项 + +### 技术品牌词不翻译 +以下词保持原样，不翻译： +- `OpenClaw` +- `ClawPanel` +- `Gateway` +- `Agent`（Agent 管理不翻译为"代理"） +- `MCP` +- `Skills` +- `Docker` +- `Tauri` + +### 参数插值语法 +使用 `{param}` 语法： +```json +{ + "chat.sessions": "{count} sessions", + "models.providers": "Based on {count} providers" +} +``` + +### 复数形式 +英文需要处理复数，但 MVP 阶段可以用简单方式： +```json +{ + "chat.messageCount": "{count} message(s)" +} +``` + +### Rust 后端 +后端错误消息暂不国际化（工作量大且用户较少直接看到），保持中文。 + +## 八、验证清单 + +每批迁移完成后检查： +- [ ] 中文模式下所有功能正常 +- [ ] 英文模式下所有功能正常 +- [ ] 语言切换后页面正确刷新 +- [ ] 没有遗漏的硬编码中文 +- [ ] 参数插值正确显示 +- [ ] 长英文文本不溢出布局 +- [ ] toast/modal/confirm 文本正确