GithubBackup/clawpanel

Fork 0

mirror of https://github.com/qingchencloud/clawpanel.git synced 2026-05-07 05:02:52 +08:00

Files

晴天 f707b2301c docs: add i18n internationalization plan

2026-03-12 03:22:57 +08:00

8.0 KiB

Raw Blame History

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`

// 使用方式
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，触发页面重渲染

语言检测优先级

localStorage 中存储的用户选择 (clawpanel-locale)
浏览器 navigator.language（zh-CN → zh-CN，en-US → en）
默认值：zh-CN

缺失翻译 fallback

查找当前语言包
查找 zh-CN 兜底（中文作为最完整的语言）
返回 key 本身（如 common.save）
开发模式下 console.warn 提示缺失翻译

三、语言包结构

src/locales/
  zh-CN.json    — 中文简体（默认，最完整）
  en.json       — English
  zh-TW.json    — 中文繁体（未来）
  ja.json       — 日本語（未来）
  ko.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: 替换代码中的硬编码

// Before
toast('保存成功', 'success')

// After
toast(t('common.savedSuccessfully'), 'success')

// Before (HTML 模板)
`<button class="btn">${icon('save', 14)} 保存</button>`

// After
`<button class="btn">${icon('save', 14)} ${t('common.save')}</button>`

Step 3: 编写英文翻译

逐 key 翻译到 en.json。

Step 4: 测试

切换语言，检查每个页面的显示是否正常。

五、迁移顺序

第一批（基础 + 框架层，约 80 个字符串）

src/lib/i18n.js — 创建核心模块
src/locales/zh-CN.json — 初始化中文包
src/locales/en.json — 初始化英文包
src/components/sidebar.js — 导航菜单（~20 个）
src/components/modal.js — 公共弹窗（~10 个）
src/components/toast.js — 提示组件
src/pages/about.js — 关于页面 + 语言切换 UI（~30 个）

第二批（核心页面，约 250 个字符串）

src/pages/dashboard.js — 仪表盘（~50 个）
src/pages/setup.js — 初始设置（~80 个）
src/pages/chat.js — 实时聊天（~100 个）
src/main.js — 主入口/横幅（~20 个）

第三批（配置页面，约 350 个字符串）

src/pages/models.js — 模型配置（~120 个）
src/pages/channels.js — 消息渠道（~80 个）
src/pages/services.js — 服务管理（~70 个）
src/pages/gateway.js — 网关配置（~40 个）
src/pages/agents.js — Agent 管理（~40 个）

第四批（功能页面，约 250 个字符串）

src/pages/cron.js — 定时任务（~50 个）
src/pages/memory.js — 记忆管理（~30 个）
src/pages/extensions.js — 扩展工具（~40 个）
src/pages/logs.js — 日志查看（~20 个）
src/pages/skills.js — Skills 工具（~60 个）
src/pages/chat-debug.js — 系统诊断（~50 个）

第五批（大型页面 + 特殊处理，约 600 个字符串）

src/pages/docker.js — Docker 管理（~150 个）
src/pages/assistant.js — AI 助手（~400 个，含系统提示词）
src/lib/openclaw-kb.js — 知识库（按语言分文件）
src/lib/error-diagnosis.js — 错误诊断（~30 个）
src/components/engagement.js — 推荐弹窗（~15 个）

第六批（官网 + 文档）

docs/index.html — 官网英文版
README.md → README_en.md
CONTRIBUTING.md → CONTRIBUTING_en.md

六、语言切换 UI 设计

位置

关于页面底部 — 语言选择下拉框
侧边栏底部 — 语言图标 + 当前语言缩写（如 中 / EN）

交互

选择语言 → 存入 localStorage → 页面自动刷新
首次访问自动检测浏览器语言

七、注意事项

技术品牌词不翻译

以下词保持原样，不翻译：

OpenClaw
ClawPanel
Gateway
Agent（Agent 管理不翻译为"代理"）
MCP
Skills
Docker
Tauri

参数插值语法

使用 {param} 语法：

{
  "chat.sessions": "{count} sessions",
  "models.providers": "Based on {count} providers"
}

复数形式

英文需要处理复数，但 MVP 阶段可以用简单方式：

{
  "chat.messageCount": "{count} message(s)"
}

Rust 后端

后端错误消息暂不国际化（工作量大且用户较少直接看到），保持中文。

八、验证清单

每批迁移完成后检查：

中文模式下所有功能正常
英文模式下所有功能正常
语言切换后页面正确刷新
没有遗漏的硬编码中文
参数插值正确显示
长英文文本不溢出布局
toast/modal/confirm 文本正确

8.0 KiB Raw Blame History Unescape Escape