# i18n-check

Adopt this skill: https://proskills.md/skills/other/zhimaai-chatclaw-cursor-skills-i18n-check

Page: https://proskills.md/skills/other/zhimaai-chatclaw-cursor-skills-i18n-check
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: .cursor/skills/i18n-check/SKILL.md
size: 7629
upstream: https://github.com/zhimaai/chatclaw/blob/main/.cursor/skills/i18n-check/SKILL.md

````text
---
name: i18n-check
description: 检查并补充前端和后端的i18n翻译文件。以中文（zh-CN）为基准，检查其他语言翻译文件是否缺少key，并补充缺失的key和对应的翻译值。对于日语(ja-JP)、韩语(ko-KR)、繁体中文(zh-TW)，使用与非CJK语言对比的方式检测未翻译内容。
---

# i18n 翻译检查与补充

## 快速开始（推荐安全用法）

> **强制前提**：先用 Git 保证当前工作区是干净的（或至少 locales 相关改动可回滚），再运行下面任何脚本。

1. **只在必要范围格式化翻译文件**（建议从后端/英文开始）

   - 后端 JSON 一般是纯英文，占位少，**优先安全**：

   ```bash
   python .cursor/skills/i18n-check/scripts/format_frontend.py
   python .cursor/skills/i18n-check/scripts/format_backend.py
   ```

   - `format_frontend.py` 会**重写所有 `frontend/src/locales/*.ts`**：
     - 仅做语法级重排与缩进，不再对字符做任何再编码；
     - 仍然建议：**先只在当前分支本地运行，确认 diff 可接受后再提交**。

2. **对比翻译差异（只读，不改文件）**:
   ```bash
   python .cursor/skills/i18n-check/scripts/compare_frontend.py
   python .cursor/skills/i18n-check/scripts/compare_backend.py
   ```

3. **补全缺失的 key（使用中文作为占位符）**

   - **推荐做法：先只对英文和后端补全，再视情况扩展到其他语言。**

   ```bash
   # 仅补前端英文（安全范围小）
   python .cursor/skills/i18n-check/scripts/fill_frontend.py --target en-US

   # 补全所有前端语言（会改动所有 locales，务必在 Git 干净时使用）
   python .cursor/skills/i18n-check/scripts/fill_frontend.py

   # 补全所有后端语言（JSON，风险相对可控）
   python .cursor/skills/i18n-check/scripts/fill_backend.py
   ```

4. **AI 翻译**（自动检测需要翻译的内容，**不会直接改 TS/JSON 文件**）
   ```bash
   # 翻译特定语言
   python .cursor/skills/i18n-check/scripts/translate_with_ai.py --target en-US

   # 翻译所有语言（包括 CJK 语言）
   python .cursor/skills/i18n-check/scripts/translate_with_ai.py --all --cjk
   ```

5. **CJK 语言翻译后检测**（翻译完成后检查是否还有未翻译）
   ```bash
   # 导出 CJK 语言未翻译内容到文本文件
   python .cursor/skills/i18n-check/scripts/export_translations.py --target ja-JP --cjk
   
   # 填充后检测 CJK 语言未翻译 key
   python .cursor/skills/i18n-check/scripts/fill_frontend.py --check-cjk
   ```

## 完整工作流程（推荐顺序）

```bash
# Step 0: 确认 Git 状态
# - 确保 frontend/src/locales 和 internal/services/i18n/locales 内的改动都可回滚
# - 不要在未提交的重要改动上直接批量格式化/补全

# Step 1: 格式化（可选，但推荐先只在后端/英文上尝试）
python .cursor/skills/i18n-check/scripts/format_frontend.py
python .cursor/skills/i18n-check/scripts/format_backend.py

# Step 2: 对比（只读）
python .cursor/skills/i18n-check/scripts/compare_frontend.py
python .cursor/skills/i18n-check/scripts/compare_backend.py

# Step 3: 补全缺失 key（中文占位）
# 先补英文，再按需扩展其他语言
python .cursor/skills/i18n-check/scripts/fill_frontend.py --target en-US
python .cursor/skills/i18n-check/scripts/fill_backend.py

# Step 4: AI 翻译（前端 + 后端）
# 脚本会自动检测需要翻译的内容并生成翻译提示（只读，不改 TS/JSON）
python .cursor/skills/i18n-check/scripts/translate_with_ai.py --all
# 仅处理后端 JSON 时，可显式指定：
# python .cursor/skills/i18n-check/scripts/translate_with_ai.py --type backend --all

# Step 5: 翻译完成后检测 CJK 语言
# 对于 ja-JP, ko-KR, zh-TW，检测是否还有未翻译内容
python .cursor/skills/i18n-check/scripts/fill_frontend.py --check-cjk
python .cursor/skills/i18n-check/scripts/translate_with_ai.py --cjk

# Step 6: 导出未翻译内容到文本，统一翻译后再导入
python .cursor/skills/i18n-check/scripts/export_translations.py --target ja-JP --cjk
# 手动翻译文本文件中的内容
python .cursor/skills/i18n-check/scripts/import_translations.py --file translation_export_ja-JP.txt
```

## 脚本说明

### 脚本位置
所有脚本位于 `.cursor/skills/i18n-check/scripts/` 目录：

| 脚本 | 用途 |
|------|------|
| `format_frontend.py` | 格式化前端 TS 翻译文件 |
| `compare_frontend.py` | 对比前端翻译差异，支持 `--cjk` 检测 CJK 语言 |
| `fill_frontend.py` | 补全前端缺失的 key，支持 `--check-cjk` 检测 CJK 未翻译 |
| `translate_with_ai.py` | AI 翻译：自动检测需要翻译的内容并生成翻译提示，支持 `--cjk` |
| `export_translations.py` | 导出未翻译内容到文本文件，支持 `--cjk` |
| `import_translations.py` | 导入翻译结果 |
| `format_backend.py` | 格式化后端 JSON 翻译文件 |
| `compare_backend.py` | 对比后端翻译差异 |
| `fill_backend.py` | 补全后端缺失的 key |

### 使用示例

**对比 CJK 语言**
```bash
# 对比特定 CJK 语言与英文
python compare_frontend.py --target ja-JP --cjk

# 对比所有 CJK 语言
python compare_frontend.py --cjk-only
```

**填充 CJK 语言**
```bash
# 填充时使用 CJK 模式
python fill_frontend.py --cjk

# 检测 CJK 语言未翻译 key
python fill_frontend.py --check-cjk
```

**AI 翻译脚本**
```bash
# 翻译特定语言
python translate_with_ai.py --type frontend --target en-US

# 翻译 CJK 语言
python translate_with_ai.py --target ja-JP --cjk

# 翻译所有语言（包括 CJK）
python translate_with_ai.py --all --cjk
```

**导出翻译**
```bash
# 导出 CJK 语言未翻译内容
python export_translations.py --target ja-JP --cjk
```

### 翻译检测逻辑

- **非 CJK 语言** (en-US, de-DE, fr-FR 等): 检测含有中文的 key，需要翻译
- **CJK 语言** (zh-TW, ja-JP, ko-KR): 检测与非 CJK 语言（如 en-US）相同的 key，需要翻译成对应语言

### CJK 语言特殊处理

对于日语 (ja-JP)、韩语 (ko-KR)、繁体中文 (zh-TW)，采用以下检测逻辑：

1. **对比方式**: 不以 zh-CN 为基准，而是与英语等非 CJK 语言对比
2. **检测原理**: 如果某个 key 在目标语言中的值与英语相同，说明该 key 未翻译
3. **导出格式**: 显示 baseline(中文) | reference(英语) | current(当前值)，便于翻译

### AI 翻译流程

1. 运行 `translate_with_ai.py` 脚本
2. 脚本会自动：
   - 读取目标语言文件
   - 检测需要翻译的中文内容（或 CJK 未翻译内容）
   - 生成 AI 翻译提示 (prompt)
3. 将生成的提示复制给 AI 进行翻译
4. AI 返回 JSON 格式的翻译结果
5. 使用 `import_translations.py` 导入翻译结果

## 文件位置

| 类型 | 目录 | 格式 | 基准文件 | CJK 基准文件 |
|------|------|------|---------|-------------|
| 前端 | `frontend/src/locales/` | TypeScript `.ts` | `zh-CN.ts` | `en-US.ts` |
| 后端 | `internal/services/i18n/locales/` | JSON `.json` | `zh-CN.json` | `en-US.json` |

## 注意事项

- **保持 key 结构**: 必须与基准文件完全一致，使用相同的嵌套层级
- **不要删除任何内容**: 只能添加缺失的 key，不能删除现有的 key
- **变量占位符**: 后端 JSON 使用 `{{.xxx}}` 格式，前端使用 `{xxx}` 格式，必须保留
- **格式化后再对比**: 每次对比前先运行格式化脚本，确保格式统一
- **CJK 语言处理**: 繁体中文(zh-TW)、日语(ja-JP)、韩语(ko-KR)使用英语(en-US)作为基准文件进行对比和填充
````

## File: README.md
upstream: https://github.com/zhimaai/chatclaw/blob/main/README.md

````text
﻿<p align="center">
<img src="./frontend/src/assets/images/logo-floatingball.png" width="150" height="150">
</p>

<h1 align="center">ChatClaw</h1>

<p align="center">
  5分钟拥有类 OpenClaw 的小龙虾个人AI智能体，沙箱安全，占资源少，运行快.
</p>

<p align="center">
  <a href="./docs/readmes/README_en.md">English</a> |
  <a href="./docs/readmes/README_zh-CN.md">简体中文</a> |
  <a href="./docs/readmes/README_zh-TW.md">繁體中文</a> |
  <a href="./docs/readmes/README_ja-JP.md">日本語</a> |
  <a href="./docs/readmes/README_ko-KR.md">한국어</a> |
  <a href="./docs/readmes/README_ar-SA.md">العربية</a> |
  <a href="./docs/readmes/README_bn-BD.md">বাংলা</a> |
  <a href="./docs/readmes/README_de-DE.md">Deutsch</a> |
  <a href="./docs/readmes/README_es-ES.md">Español</a> |
  <a href="./docs/readmes/README_fr-FR.md">Français</a> |
  <a href="./docs/readmes/README_hi-IN.md">हिन्दी</a> |
  <a href="./docs/readmes/README_it-IT.md">Italiano</a> |
  <a href="./docs/readmes/README_pt-BR.md">Português</a> |
  <a href="./docs/readmes/README_sl-SI.md">Slovenščina</a> |
  <a href="./docs/readmes/README_tr-TR.md">Türkçe</a> |
  <a href="./docs/readmes/README_vi-VN.md">Tiếng Việt</a>
</p>

Chatclaw是一款开源的本地知识库、OpenClaw图形化桌面管家应用
无需编程，一键部署至本地电脑。可连接 微信、 钉钉、企业微信、QQ、飞书，WhatsApp等主流通讯应用，
发送指令即可让 AI 帮你执行任务。内置 OpenClaw 5000+ 技能库，并支持类 ima 的本地知识库管理

## 功能预览

### AI 聊天助手

向 AI 助手提出任何问题，它会智能搜索您的知识库并生成相关回答。搭配内置技能市场，让 AI Agent 自主干活，无需人工全程干预。无论是复杂的项目规划、文档整理，还是 PPT 快速生成、多步骤任务执行，都能自主拆解，高效推进，最终交付完整结果，大幅节省人工时间，提升工作效率。

![](./images/previews/zh-CN/image1.png)

![](./images/previews/zh-CN/image2.png)

### 多Agent模式，满足不同场景使用

创建多个独立 AI Agent，每个拥有专属角色、记忆和技能，按需切换使用，互不干扰。每个 Agent 可设定不同身份，如"客服专员""数据分析师""文案助手"，可分别为每个 Agent 配置不同的技能，知识库、回复风格。在界面中自由切换 Agent，适应不同任务场景。

![](./images/previews/zh-CN/image3.png)

### 开源的本地知识库管理

上传您的文档（如 TXT、PDF、Word、Excel、CSV、HTML、Markdown），系统会自动解析、分割并转换为向量嵌入，存储到您的私有知识库中，供 AI 模型进行精准检索和利用，支持按文件夹，知识库文档进行分类整理。

![](./images/previews/zh-CN/image4.png)

### 海量技能库，输入指令，AI 秒级响应

5000+ 开箱即用的 AI 技能，覆盖效率办公，开发工具、多媒体创作、智能家居等全场景，让 AI 帮你干活，无需编程。使用指令让机器人帮您查找电脑上已安装的功能或安装新的扩展插件。技能市场，自主选择和安装技能。

![](./images/previews/zh-CN/image5.png)

### 记忆功能 — 交互更自然，更智能

实现上下文对话，提供个性化服务，完成复杂任务，持续学习和进化，让机器人像一个不断成长的伙伴，能提供越来越贴心、越来越智能的服务。

![](./images/previews/zh-CN/image6.png)

### 免费模型试用

一键授权接入 ChatWiki，同步 ChatWiki 账号积分，同时支持自定义模型，内置优质国内外大模型，Ollama、Google Gemini、OpenAI 等，无论是日常办公还是专业场景，使用您喜欢的 AI 模型。

![](./images/previews/zh-CN/image7.png)

### 企业微信/微信/钉钉/飞书/QQ/WhatsApp 等多渠道远程控制

ChatClaw 支持多种消息通道，让分析结果、监控告警，研究摘要直接推送到您的手机上，突破平台壁垒。
接入多家消息通道，国内外主流通讯应用全支持。AI 处理完成后，结果自动发送到指定渠道，无需主动刷新。在聊天窗口中发送指令，即可远程操控 AI 执行任务。

![](./images/previews/zh-CN/image8.png)

### 定时任务，自动化运行更方便

设定监控频率：每 5 分钟、每小时、每天固定时间点，图形化调度器配合 cron 表达式，让自动执行更直观。
定时抓取特定页面或数据源，对比变化，监控关键指标，政策发布、公告更新，异常触发时，第一时间通过消息通道推送提醒。

![](./images/previews/zh-CN/image9.png)

### 划词即时问答

选中屏幕上的任意文字，它会被自动复制并填入悬浮快问框。一键发送给 AI 助手，即刻获得回答。

![](./images/previews/zh-CN/image10.png)

### 智能侧边栏

可以贴靠在其他应用窗口旁的智能助手。在其中快速切换不同配置的 AI 助手进行提问。机器人根据您关联的知识库生成回答，并支持一键将回复发送到您的对话中。智能悬浮跟随，工具入口随手可得，不遮挡、不打断。

![](./images/previews/zh-CN/image11.png)

![](./images/previews/zh-CN/image12.png)

### 一问多答：轻松比较

无需重复提问。同时咨询多个"AI 专家"，在一个界面中并排查看它们的回复，方便比较，帮助您得出最佳结论。

![](./images/previews/zh-CN/image13.png)

### 一键启动

点击桌面上的悬浮球，即可唤醒或打开 ChatClaw 主应用窗口。

![](./images/previews/zh-CN/image14.png)

### 社区交流&联系我们

欢迎联系我们获取帮助，或者提供建议帮助我们改善 ChatClaw。您可以通过以下方式联系我们：
微信，使用微信扫码加入 ChatClaw 技术交流群，添加请备注"chatclaw"。

![](./images/previews/zh-CN/image15.png)

## Server Mode Deployment

ChatClaw 支持以服务器模式运行（无需桌面 GUI），通过浏览器访问。

### 二进制直接运行

从 [GitHub Releases](https://github.com/chatwiki/chatclaw/releases) 下载对应平台的二进制文件：

| 平台 | 文件 |
|------|------|
| Linux x86_64 | `ChatClaw-server-linux-amd64` |
| Linux ARM64 | `ChatClaw-server-linux-arm64` |

```bash
chmod +x ChatClaw-server-linux-amd64
./ChatClaw-server-linux-amd64
```

浏览器打开 http://localhost:8080 即可使用。

服务默认监听 `0.0.0.0:8080`。可通过环境变量自定义监听地址和端口：

```bash
WAILS_SERVER_HOST=127.0.0.1 WAILS_SERVER_PORT=3000 ./ChatClaw-server-linux-amd64
```

### Docker

```bash
docker run -d \
  --name chatclaw-server \
  -p 8080:8080 \
  -v chatclaw-data:/root/.config/chatclaw \
  registry.cn-hangzhou.aliyuncs.com/chatwiki/chatclaw:latest
```

浏览器打开 http://localhost:8080 即可使用。

### Docker Compose

创建 `docker-compose.yml` 文件：

```yaml
services:
  chatclaw:
    image: registry.cn-hangzhou.aliyuncs.com/chatwiki/chatclaw:latest
    container_name: chatclaw-server
    volumes:
      - chatclaw-data:/root/.config/chatclaw
    ports:
      - "8080:8080"
    restart: unless-stopped

volumes:
  chatclaw-data:
```

然后运行：

```bash
docker compose up -d
```

浏览器打开 http://localhost:8080 即可使用。停止服务：`docker compose down`。数据持久化在 `chatclaw-data` 卷中。

## 技术栈

| 层级 | 技术 |
|------|------|
| 桌面框架 | [Wails v3](https://wails.io/) (Go + WebView) |
| 后端语言 | [Go 1.26](https://go.dev/) |
| 前端框架 | [Vue 3](https://vuejs.org/) + [TypeScript](https://www.typescriptlang.org/) |
| UI 组件 | [shadcn-vue](https://www.shadcn-vue.com/) (New York 风格) + [Reka UI](https://reka-ui.com/) |
| 样式方案 | [Tailwind CSS v4](https://tailwindcss.com/) |
| 状态管理 | [Pinia](https://pinia.vuejs.org/) |
| 构建工具 | [Vite](https://vite.dev/) |
| AI 框架 | [Eino](https://github.com/cloudwego/eino) (字节跳动 CloudWeGo) |
| AI 模型供应商 | OpenAI / Claude / Gemini / Ollama / DeepSeek / 豆包 / 通义千问 / 智谱 / Grok |
| 数据库 | [SQLite](https://www.sqlite.org/) + [sqlite-vec](https://github.com/asg017/sqlite-vec) (向量检索) |
| 国际化 | [go-i18n](https://github.com/nicksnyder/go-i18n) + [vue-i18n](https://vue-i18n.intlify.dev/) |
| 任务运行 | [Task](https://taskfile.dev/) |
| 图标 | [Lucide](https://lucide.dev/) |

## 项目结构

```
ChatClaw_D2/
├── main.go                     # 应用入口
├── go.mod / go.sum             # Go 模块依赖
├── Taskfile.yml                # 任务运行器配置
├── build/                      # 构建配置与平台资源
│   ├── config.yml              # Wails 构建配置
│   ├── darwin/                 # macOS 构建设置与授权
│   ├── windows/                # Windows 安装器 (NSIS/MSIX) 与清单
│   ├── linux/                  # Linux 打包 (AppImage, nfpm)
│   ├── ios/                    # iOS 构建设置
│   └── android/                # Android 构建设置
├── frontend/                   # Vue 3 前端应用
│   ├── package.json            # Node.js 依赖
│   ├── vite.config.ts          # Vite 打包配置
│   ├── components.json         # shadcn-vue 配置
│   ├── index.html              # 主窗口入口
│   ├── floatingball.html       # 悬浮球窗口入口
│   ├── selection.html          # 划词弹窗入口
│   ├── winsnap.html            # 贴靠窗口入口
│   └── src/
│       ├── assets/             # 图标 (SVG)、图片与全局 CSS
│       ├── components/         # 共享组件
│       │   ├── layout/         # 应用布局、侧边栏、标题栏
│       │   └── ui/             # shadcn-vue 基础组件 (button, dialog, toast…)
│       ├── composables/        # Vue 组合式函数（可复用逻辑）
│       ├── i18n/               # 前端国际化配置
│       ├── locales/            # 翻译文件 (zh-CN, en-US…)
│       ├── lib/                # 工具函数
│       ├── pages/              # 页面级视图
│       │   ├── assistant/      # AI 聊天助手页面及组件
│       │   ├── knowledge/      # 知识库管理页面
│       │   ├── multiask/       # 多模型对比页面
│       │   └── settings/       # 设置页面（供应商、模型、工具…）
│       ├── stores/             # Pinia 状态仓库
│       ├── floatingball/       # 悬浮球迷你应用
│       ├── selection/          # 划词迷你应用
│       └── winsnap/            # 贴靠窗口迷你应用
├── internal/                   # 私有 Go 包
│   ├── bootstrap/              # 应用初始化与依赖注入
│   ├── define/                 # 常量、内置供应商、环境标志
│   ├── device/                 # 设备标识
│   ├── eino/                   # AI/LLM 集成层
│   │   ├── agent/              # Agent 编排
│   │   ├── chatmodel/          # 聊天模型工厂（多供应商）
│   │   ├── embedding/          # 嵌入模型工厂
│   │   ├── filesystem/         # AI Agent 文件系统工具
│   │   ├── parser/             # 文档解析器 (PDF, DOCX, XLSX, CSV)
│   │   ├── processor/          # 文档处理流水线
│   │   ├── raptor/             # RAPTOR 递归摘要
│   │   ├── splitter/           # 文本分割器工厂
│   │   └── tools/              # AI 工具集成（浏览器、搜索、计算器…）
│   ├── errs/                   # 国际化错误处理
│   ├── fts/                    # 全文搜索分词器
│   ├── logger/                 # 结构化日志
│   ├── services/               # 业务逻辑服务
````
