| name | doc-translator |
| description | 技术文档翻译技能。将英文技术文档翻译为中文，自动添加目录（TOC）， 保持原有文档结构（标题层级、表格、代码块、列表等），保留专有名词不翻译。 翻译完成后保存到 docs/ 目录。当用户需要翻译技术文档、翻译 Markdown 文件、 翻译 README、翻译 API 文档、翻译技术博客时使用此技能。 |
| license | MIT |
| compatibility | 无额外依赖，纯 LLM 翻译 |
| metadata | {"author":"copilot-tools","version":"1.0.0"} |
| allowed-tools | Read |
技术文档翻译技能
将英文技术文档翻译为高质量中文文档，自动添加目录，保持原有结构完整。
文件存储规范
| 文件类型 | 存储位置 | 命名规则 |
|---|
| 翻译后的文档 | docs/ | 保持原文件名，如 docs/original-name.md |
翻译原则
专有名词保留
以下类型的词汇必须保留英文原文，不做翻译：
- 技术术语: API, SDK, REST, GraphQL, WebSocket, OAuth, JWT, CI/CD, Docker, Kubernetes 等
- 产品名称: GitHub, Copilot, VS Code, Node.js, React, Python, TypeScript 等
- 协议与标准: HTTP, HTTPS, TCP/IP, JSON, YAML, XML, gRPC, MQTT 等
- 编程概念: middleware, hook, callback, promise, async/await, decorator 等
- 缩写: URL, CLI, GUI, IDE, ORM, MVC, CRUD, RBAC 等
- 命令与代码: 所有代码块、命令行内容、文件路径、变量名保持原样
⚠️ 当首次出现不常见的专有名词时，可在翻译中加注：中文翻译（English Term）
结构保持
翻译时必须完整保留原文的：
- 标题层级:
#, ##, ### 等层级结构不变
- 表格: 保持表格格式和列数，仅翻译文字内容
- 代码块: 代码内容不翻译，代码注释可翻译
- 列表: 有序和无序列表结构不变
- 链接: 保持链接 URL 不变，链接文字视情况翻译
- 图片: 保持图片引用不变，alt 文字可翻译
- 引用块:
> 引用块结构不变
- 分隔线:
--- 等分隔线保留
- HTML 标签: 保持原有 HTML 标签不变
- 脚注: 保持脚注格式，翻译脚注内容
翻译质量
- 使用自然流畅的中文表达，避免机翻感
- 技术描述准确，符合中文技术写作习惯
- 长句适当拆分，提高可读性
- 被动语态转换为主动语态（如适用）
工作流程
步骤 1: 读取源文档
使用 Read 工具读取用户指定的源文档文件。
- 若用户提供 URL，使用 web_fetch 获取内容
- 若用户提供文件路径，使用 Read 工具读取
步骤 2: 分析文档结构
在翻译前分析文档的整体结构：
- 标题层级和章节划分
- 是否包含表格、代码块、列表等特殊元素
- 识别需要保留的专有名词
步骤 3: 逐节翻译
按章节依次翻译，每个章节翻译时：
- 保持标题层级不变
- 翻译正文内容
- 保留代码块原文
- 翻译表格中的文字内容，保持表格格式
- 保留专有名词
步骤 4: 生成目录（TOC）
在文档标题之后、正文之前插入目录：
# 文档标题
## 目录
- [章节一](#章节一)
- [子章节](#子章节)
- [章节二](#章节二)
...
---
## 章节一
目录生成规则：
- 包含所有
## 和 ### 级别的标题
- 使用中文标题作为锚点链接
- 锚点格式：小写、空格替换为
-、去除特殊字符
- 目录与正文之间用
--- 分隔
步骤 5: 保存文档
将翻译后的文档保存到 docs/ 目录：
- 文件名与源文档保持一致
- 若源文档无
.md 后缀，自动添加
- 在文档末尾添加翻译信息：
---
> 本文翻译自 [原文档名](原文档路径或URL)
输出格式
翻译后的 Markdown 文件结构：
# 翻译后的标题
## 目录
- [章节一](#章节一)
- [子章节一](#子章节一)
- [章节二](#章节二)
---
## 章节一
翻译后的内容...
### 子章节一
翻译后的内容...
## 章节二
翻译后的内容...
---
> 本文翻译自 [original-doc.md](路径或URL)
常见场景
| 用户请求 | 处理方式 |
|---|
| "翻译这个文档" | 读取文档 → 翻译 → 添加 TOC → 保存到 docs/ |
| "翻译这个 README" | 同上，文件名保持为 README.md |
| "翻译这篇技术博客" | 若为 URL 则先 fetch，再翻译保存 |
| "把这个英文文档翻译成中文" | 同标准翻译流程 |
| "翻译并保留专有名词" | 默认行为，所有专有名词均保留 |
注意事项
- 大文档分段处理: 超过 5000 字的文档按章节分段翻译，避免遗漏
- 代码块不翻译: 代码块中的代码保持原样，注释可酌情翻译
- 表格对齐: 翻译后注意表格中文对齐格式
- 锚点兼容: 目录中的锚点链接需与实际标题匹配
- 上下文一致性: 同一文档中相同术语的翻译保持一致
