Translation Skill

Overview

此 Skill 定义翻译任务的分层策略：

1. 少量文本 — AI 自身手动翻译，逐段逐句完成，保证最高翻译质量。
2. 大批量文本 — 当手动翻译不现实时，使用 LLM API 自动翻译。默认使用 DeepSeek API，支持通过环境变量配置任意 OpenAI 兼容端点。
3. 传统机翻 API（Google Translate、DeepL、百度翻译等） — 不推荐使用，翻译质量差且容易破坏格式。优先使用 LLM API。

核心原则：翻译质量优先。少量文本手动翻译，大批量文本用 LLM API 保证效率与质量的平衡。

核心规则

策略选择

> 判断原则：默认手动翻译。仅当文件数量或篇幅使得手动翻译明显不现实时，才使用 LLM API。当不确定时，询问用户偏好。

API 配置

本 Skill 通过环境变量 DEEPSEEK_API_KEY 获取 API 密钥。密钥不在本 Skill 中存储，统一由 deepseek-api Skill 提供。运行脚本前，须从 deepseek-api Skill 获取 API Key 并设置环境变量：

# 从 deepseek-api skill 获取 API Key 后设置
export DEEPSEEK_API_KEY="sk-xxxxxxxxxxxx"

如需使用其他 OpenAI 兼容端点，可通过环境变量覆盖：

其他供应商配置示例（通过环境变量覆盖）：

# OpenAI
export DEEPSEEK_API_KEY="sk-your-key"
export DEEPSEEK_BASE_URL="https://api.openai.com/v1"
# 模型通过 -m 参数指定

# Moonshot (月之暗面)
export DEEPSEEK_API_KEY="sk-your-key"
export DEEPSEEK_BASE_URL="https://api.moonshot.cn/v1"
# 模型通过 -m 参数指定

> 变量名保留 DEEPSEEK_ 前缀是为向后兼容，但实际可用于任意 OpenAI 兼容端点。

可用模型 (DeepSeek)

核心 API 参数

> frequency_penalty 和 presence_penalty 已废弃，传入无效。

快速测试 (curl)

curl https://api.deepseek.com/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {
        "role": "system",
        "content": "You are a professional translator. Translate the following text to English. Preserve all formatting. Output only the translated text."
      },
      {
        "role": "user",
        "content": "你好，世界！这是一个翻译测试。"
      }
    ],
    "temperature": 0.3,
    "stream": false
  }'

OpenAI SDK 调用方式 (Python)

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("DEEPSEEK_API_KEY"),  # 从 deepseek-api skill 获取
    base_url="https://api.deepseek.com",
)

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        {"role": "system", "content": "You are a professional translator..."},
        {"role": "user", "content": "你好，世界！"}
    ],
    temperature=0.3,
    stream=False,
)

print(response.choices[0].message.content)

API Key 不可用时的降级策略

当 DEEPSEEK_API_KEY 环境变量未设置（如 deepseek-api Skill 中的付费 Key 过期、余额不足、被撤销等），按以下优先级处理：

1. 使用替代 LLM API

优先尝试使用 zhipu-api Skill 中预置的智谱清言免费模型（glm-4.7-flash）。智谱 API 兼容 OpenAI 格式，切换时只需修改 DEEPSEEK_API_KEY 和 DEEPSEEK_BASE_URL 环境变量即可，脚本调用方式不变。

> 具体配置和调用方式请参考 zhipu-api Skill。

2. 无替代 API 可用时

如果以上替代 API 也不可用，应告知用户并让用户选择：

• 方案 A：完全手动翻译 — 由 AI 逐段逐句手动翻译。质量最高，但速度受限，适合文件数量较少（< 20 个）的场景。参考下方「手动翻译工作流」
• 方案 B：更换 API Key — 引导用户更新 deepseek-api 或 zhipu-api Skill 中的 Key

> 判断原则：始终优先尝试使用已有的付费 API（deepseek-api skill）。当付费 API 不可用时，主动引导用户选择降级方案，不要默默降级或静默失败。

手动翻译工作流

单文件翻译

1. 读取源文件全部内容。
2. 逐段理解原文语义，翻译为目标语言。
3. 保留所有格式标记（Markdown、HTML、代码块等）。
4. 将翻译结果写入目标文件或直接输出。

批量文件翻译 (手动)

1. 列出所有待翻译文件，确认文件总数和类型。
2. 批量读取：一次并行读取 8-10 个源文件（而非逐个读取），减少交互轮次。
3. 批量翻译：对已读取的文件逐个进行翻译（翻译本身需逐文件理解语义，无法并行）。
4. 批量写入：将翻译好的文件一次性并行写入。
5. 每完成一批后，简要告知进度（如"已完成 10/43"），继续下一批。
6. 全部完成后，输出翻译文件列表及简要总结。

> 效率提示：对于 10-20 个小文件（每个 < 5KB），按 10 个一批进行"批量读取→逐个翻译→批量写入"是最高效的手动翻译方式。

翻译质量要求（通用）

• 语义准确：忠实传达原文含义，不增译、不漏译。
• 表达自然：译文符合目标语言的表达习惯，避免机翻腔。
• 上下文连贯：前后文指代、时态、语气保持一致。
• 专业术语：技术文档中的术语采用业界通用译法；不确定时保留原文并在括号中标注。
• 代码不翻译：代码块内容、命令行、变量名、函数名等保持原样，仅翻译注释和说明文字。
• 格式保留：严格保留 Markdown 标题层级、代码块围栏、表格结构、HTML 标签结构等。

格式保留规则（按文件类型）

> 代码注释翻译：翻译描述性文字，保留代码片段。如 // 获取元素 → // Get the element；但 // document.getElementById('x') 保持不变。API 密钥、URL 等注释内容不翻译。

文件命名规范（通用原则）

翻译后的输出文件建议使用目标语言的命名习惯：

• 保留编号/序号：如 第一章.md → Chapter01.md，笔记03.txt → Note03.txt
• 使用 PascalCase（大驼峰命名）
• 输出目录使用英文命名
• 如果用户指定了命名规范，优先遵循用户的要求
• 非拉丁字符命名的文件，翻译后建议转为拉丁字符命名

LLM API 翻译

当需要使用 LLM API 进行大批量翻译时，使用本 Skill 目录下的脚本：

• Python 脚本：scripts/translate.py
• Node.js 脚本：scripts/translate.js

两个脚本功能一致，均支持并发翻译和进度文件。使用 DeepSeek API，密钥通过环境变量 DEEPSEEK_API_KEY 传入（从 deepseek-api skill 获取）。

并发翻译使用方式

# 依赖安装 (Python)
pip install requests

# 单文件翻译 (中文 -> 英文)
python scripts/translate.py -i README.md -o README_en.md -t en

# 批量翻译目录 (默认并发 10)
python scripts/translate.py -i ./docs/ -o ./docs_en/ -t en --batch

# 指定并发数 20
python scripts/translate.py -i ./docs/ -o ./docs_en/ -t en --batch -c 20

# 使用高质量模型 + 高并发
python scripts/translate.py -i ./docs/ -o ./docs_en/ -t en --batch -m deepseek-v4-pro -c 30

# 指定源语言和目标语言
python scripts/translate.py -i input.txt -o output.txt -s zh -t ja

# 指定文件扩展名 (批量模式)
python scripts/translate.py -i ./docs/ -o ./docs_en/ -t en --batch -e .md .txt .rst

Node.js 版本用法完全一致（需要 Node.js >= 18）：

node scripts/translate.js -i README.md -o README_en.md -t en
node scripts/translate.js -i ./docs/ -o ./docs_en/ -t en --batch -c 20

使用其他供应商

通过环境变量切换到其他 OpenAI 兼容端点：

# 使用 Moonshot
export DEEPSEEK_API_KEY="sk-your-moonshot-key"
export DEEPSEEK_BASE_URL="https://api.moonshot.cn/v1"
python scripts/translate.py -i ./docs/ -o ./docs_en/ -t en --batch -m moonshot-v1-8k

脚本参数

并发建议

> 脚本会根据模型名称自动判断并发上限。flash 模型上限 100，其他模型上限 50。

翻译 System Prompt 设计

脚本中使用的核心 system prompt：

You are a professional translator. Translate the following text from {源语言} to {目标语言}.

Translation rules:
1. Preserve ALL formatting: Markdown headers, code blocks, lists, tables, HTML tags, etc.
2. Do NOT translate code, variable names, function names, CLI commands, or file paths.
3. Only translate comments and descriptive text within code blocks.
4. Maintain the original document structure and line breaks.
5. Use industry-standard terminology for technical terms.
6. If unsure about a term, keep the original and add translation in parentheses.
7. Output ONLY the translated text — no explanations, no notes, no preamble.

> temperature 设为 0.3：低温度确保翻译一致性，同一术语在不同位置得到相同翻译。

进度文件

机制

批量翻译时，脚本会在输出目录下自动创建 translation_progress.json，实时记录翻译进度和时间戳。

{
  "start_time": "2025-01-01T00:00:00+00:00",
  "total_files": 100,
  "completed": 35,
  "failed": 2,
  "model": "deepseek-v4-flash",
  "target_lang": "en",
  "concurrency": 10,
  "files": [
    {"file": "README.md", "status": "success", "timestamp": "2025-01-01T00:00:05+00:00", "duration_seconds": 4.8},
    {"file": "guide/intro.md", "status": "pending", "timestamp": null, "duration_seconds": null}
  ]
}

关键规则

1. 创建时机：批量翻译开始时自动创建，记录启动时间和全部待翻译文件列表。
2. 更新时机：每完成一个文件（成功或失败）后，立即更新该文件的状态和时间戳。
3. 删除时机：仅在所有翻译任务完成后才删除此文件。翻译进行中绝不删除。
4. 用途：
   - 通过比较时间戳判断翻译是否在正常推进
   - 通过 completed / failed / total_files 了解整体进度
   - 翻译中断后可用于排查哪些文件未完成

如何检查进度

python -c "import json; d=json.load(open('output_dir/translation_progress.json')); print(f\"进度: {d['completed']}/{d['total_files']} (失败: {d['failed']})\")"

翻译运行时行为规则（关键！）

等待规则

当使用 LLM API 脚本进行批量翻译时，必须严格遵守以下规则：

1. 禁止幻觉等待时间：不得声称"已等待 X 分钟"——除非你真的通过 sleep 或定时器等待了。立即执行检查 = 立即检查，不是等待。

2. 禁止估算总翻译时间：不得基于"已翻译文件数 x 单文件耗时"预估总时间，并发场景下几乎总是不准确。

3. 禁止基于幻觉时间判断"卡住"：翻译是否在推进，只能通过 translation_progress.json 中的时间戳判断——最近的时间戳近期更新过 = 正常推进。

4. 没翻译完就继续等：如果翻译尚未完成且当前无其他工作，就老老实实继续等待，直到翻译完成。

5. 如何判断翻译是否完成：
   - translation_progress.json 被删除 = 所有任务完成
   - 或脚本进程已结束（退出码 0 = 成功，非 0 = 部分失败）
   - 或 completed + failed == total_files

6. 如何判断翻译是否真的卡住（仅当以下所有条件同时满足）：
   - 进度文件仍然存在
   - 最近一次 timestamp 更新距离当前时间超过 10 分钟（通过实际比较时间戳，不是幻觉）
   - 脚本进程仍在运行但没有新的输出
   - 即使如此，也应先再等一段时间确认，而非立即中断

正确的等待模式

1. 启动翻译脚本（后台运行）
2. 等待一段时间后（真正等待，使用 sleep 或定时器），检查 translation_progress.json
3. 如果 completed + failed < total_files 且进度文件仍存在 → 翻译进行中，继续等待
4. 如果进度文件已被删除或 completed + failed == total_files → 翻译完成
5. 重复步骤 2-4 直到翻译完成

错误的做法（禁止）

❌ 启动脚本后立即检查，然后声称"已等待 2-3 分钟"
❌ 基于幻觉的等待时间估算总翻译时间
❌ 基于估算的总翻译时间判断"任务卡住了"
❌ 因为"觉得等了很久"就中断翻译进程
❌ 在翻译未完成时删除 translation_progress.json

限流与错误处理

并发限制：
- deepseek-v4-pro：500 并发/账号
- deepseek-v4-flash：2500 并发/账号
- 脚本默认限制：flash 100 并发，pro 50 并发（保守值，避免触发限流）
- 超过限制返回 HTTP 429，脚本自动指数退避重试

翻译方案对比

结论：LLM API 通过大语言模型能力理解上下文，翻译质量接近手动翻译，适合大批量场景。传统机翻 API 在质量和格式保留方面均不如 LLM API，不推荐使用。

用户请求示例

示例 1：单文件翻译

> 用户："帮我把这个 README.md 翻译成英文"

正确做法：读取 README.md，逐段手动翻译为英文，保留所有 Markdown 格式和代码块，写入 README_en.md。

示例 2：少量文件批量翻译

> 用户："把这个文件夹下 8 个 .md 文件翻译成英文"

正确做法：批量读取（一次 8-10 个），逐个手动翻译，批量写入。每批完成后告知进度。

示例 3：超大批量翻译

> 用户："把这个目录下 200 个文档文件翻译成英文"

正确做法：使用脚本并发翻译：

python scripts/translate.py -i ./docs/ -o ./docs_en/ -t en --batch -c 30

然后老老实实等待，通过 translation_progress.json 判断是否完成。

示例 4：用户要求用机翻 API

> 用户："用 Google Translate API 帮我翻译这些文件"

正确做法：说明传统机翻 API 的局限性（机翻腔、格式破坏、隐私风险等），建议使用 LLM API 或手动翻译。如果用户坚持要自动化，引导至 LLM API 方案。

示例 5：切换供应商

> 用户："用 Moonshot 的 API 翻译这些文件"

正确做法：帮助用户设置环境变量后运行脚本：

export DEEPSEEK_API_KEY="sk-..."
export DEEPSEEK_BASE_URL="https://api.moonshot.cn/v1"
python scripts/translate.py -i ./docs/ -o ./docs_en/ -t en --batch -m moonshot-v1-8k