| name | doc-translate |
| description | 翻译 Markdown 文档为中文，并格式化为 Obsidian 兼容的 Markdown。用户指定文件或目录路径，翻译 front matter（title 简化翻译、description 翻译）和正文内容，使用 Obsidian Callout 等语法美化输出。触发词：翻译文档、translate、翻译 markdown、doc translate、翻译文件、translate doc。即使用户只说"翻译这个文件"或"把这个翻译一下"也应该触发此 skill。 |
文档翻译 Skill
将英文 Markdown 文档翻译为中文，同时将输出格式化为 Obsidian 兼容的 Markdown 文档。
边界说明
这个 skill 做且只做一件事：原地翻译指定的 Markdown 文件。
- 直接用翻译后的内容覆盖源文件（除非用户指定了其他输出位置）
- 不会在 wiki/ 目录下创建任何新页面
- 不会触发 Ingest、Query、Lint 等 Wiki 操作
- 不会更新 index.md、log.md、.status.json
- 即使文件位于 raw/ 目录下，也只是原地翻译，不做知识库摄入
前置确认
- 用户必须指定要翻译的文件或目录路径。如果用户没有指定，用
AskUserQuestion 主动询问。
- 确认路径存在后再开始翻译。如果路径不存在，提示用户检查。
- 如果用户指定的是目录，找出该目录下所有
.md 文件，逐个翻译。
大文件处理策略
文件大小 > 30KB 时，必须使用 general-purpose subagent 执行翻译。
原因：大文件翻译需要多次分段读取和多次 edit，容易填满主会话 context；会话压缩后需要重建翻译状态，效率低且容易出错。
操作方式：
- 检查文件大小（
Get-Item <path> | Select-Object -ExpandProperty Length）
- 若 > 30KB，使用 task 工具启动
general-purpose subagent，将完整翻译任务（含文件路径、翻译规范、术语约定）作为 prompt 传入
- Subagent 在独立 context 中完成全部翻译，主会话只做最终验收
- 文件 ≤ 30KB 时，在主会话中直接按以下步骤执行
翻译流程
步骤 1：读取原文
用 Read 工具读取源文件内容。
步骤 2：处理 Front Matter
分析文档顶部的 YAML front matter（--- 包裹的部分）：
| 字段 | 处理规则 |
|---|
title | 简化并翻译为中文。如果原标题冗长，提取核心含义。如果不存在 title 字段，从文档第一个 H1 标题提取并创建 |
description | 翻译为中文。如果不存在则忽略，不创建 |
| 其他字段 | 保留原样，不做修改 |
title 简化原则：去掉冗余修饰词，保留核心主题。例如 "Getting Started with Spring Security Authentication" → "Spring Security 认证入门"。
步骤 3：翻译正文
翻译核心理念
目标是产出自然流畅的中文，读起来像是由母语工程师撰写的——而非机器翻译的逐字对应。
- 准确性优先：保留所有技术含义，不遗漏或扭曲
- 自然性次之：产出资深中文工程师会撰写的文章
- 不解释、不说明、不总结——仅进行翻译
术语处理（关键）
术语处理是翻译质量的核心分界线。分四种情况：
情况 1：行业通用英文术语——保持英文，不加注解
在中文技术写作中广泛使用的术语应保持英文原样，不要强行翻译，也不需要附加中文注解：
Spring Boot、Bean、Controller、Handler、Provider、Service、Repository、Promise、Hook、middleware、payload、token、socket、pipeline、callback、namespace、runtime、mock、stub、framework、plugin、schema、endpoint、request、response、session、cookie、header 等。
正确示例：Controller 负责处理 HTTP 请求。
错误示例：Controller（控制器）负责处理 HTTP 请求。
错误示例：控制器负责处理 HTTP 请求。
情况 2：英文术语+首次出现附中文注解
当保留英文术语有助于精确性或符合标准实践时，保留英文，首次出现时在括号中附加简短中文注解：
Interceptor（拦截器）、Circuit Breaker（熔断器）、Service Mesh（服务网格）、Dead Letter Queue（死信队列）
注解只在术语首次出现时添加，后续出现保持纯英文。
情况 3：中文术语+附英文原文
对于翻译成中文的术语，在括号中附加英文原文：依赖注入 (Dependency Injection)、消息队列 (Message Queue)、反向代理 (Reverse Proxy)。
情况 4：纯中文通用术语
如果术语本身已经是中文技术写作中的通用表达（如"数据库"、"服务器"、"线程"、"接口"），直接使用中文，不需要附加英文。
翻译风格
- 使用领域适当的中文术语（软件工程、Java/Spring 生态、分布式系统、密码学、网络安全等）
- 倾向于简洁、主动的措辞而非冗长的字面翻译
- 匹配源文本的语体：技术文档保持正式；注释保持简洁
- 当源文本存在歧义时，选择与软件工程背景最一致的解释
- 不自行扩展、补充或删减原文内容
代码块处理
- 代码块内容不翻译
- 代码块中的注释可翻译为中文
- 代码块上方的说明文字正常翻译
其他处理
- 链接：保留所有超链接地址不变，链接文字翻译为中文
- 图片：图片地址和格式保持不变，图注（caption）翻译为中文
- 代码中的标识符：保持所有变量名、类名、方法名、包路径不变
步骤 4：Obsidian 格式化
将翻译后的内容按照 Obsidian 兼容的 Markdown 语法进行格式化。
Callouts（提示框）
根据原文内容语义，适当添加 Obsidian Callout 提升可读性：
> [!note] 标题
> 内容
> [!tip] 标题
> 内容
> [!warning] 标题
> 警告内容
> [!info] 标题
> 补充说明
适用场景：
note：一般性备注info：补充说明、背景知识tip：实用技巧、最佳实践warning：注意事项、潜在问题danger：严重警告、可能导致数据丢失等example：示例说明abstract：摘要、总结question：常见问题bug：已知问题
Callout 语法规则：
- 使用
> 引用块语法，[!type] 后跟标题
- 多行内容每行都以
> 开头
- 可嵌套：在
> 前加 > 表示嵌套层级
- 不要过度使用，只在原文有明确提示/警告/备注语义时添加
代码块
使用标准 Markdown 代码块，Obsidian 原生支持语言标识符高亮：
```java
// 代码内容
```
如果需要标注代码来源文件，在代码块上方用普通文本说明，不使用特殊属性语法。
Wikilinks（双链）
翻译过程中遇到原文的交叉引用时：
- 如果引用的是已有 Wiki 页面，使用 Obsidian 的
[[页面名]] 双链语法
- 如果是普通文档（非 Wiki 环境），保留原始 Markdown 链接格式
表格、列表等
保留原有的 Markdown 表格和列表格式，内容翻译为中文。
行内格式
- 用反引号包裹关键技术术语：
依赖注入 (Dependency Injection)
- 不用
** 加粗正文文本
- 不用反引号包裹标题文本
步骤 5：输出结果
- 用 Write 或 Edit 工具将翻译后的内容写回源文件，原地覆盖
- 如果用户指定了输出目录，则写入到指定目录
- 完成后告知用户翻译了哪些文件
- 不要执行任何额外操作（不创建 wiki 页面、不更新索引、不运行搜索命令）
翻译质量自检
完成翻译后，对照以下清单自检：
