name: translate
description: Use this skill when the user / a caller asks to translate or rewrite English Markdown articles into Chinese. Two modes: 原文翻译模式 (default) preserves paragraph/list/heading 1:1 with the source; 原文重写模式 restructures along Chinese tech-blog conventions (use only when caller explicitly opts in or user says "按中文重写"). Trigger on requests like "翻译英文文章", "把英文文章翻成中文", "翻译这些 .md", "用中文重写", "按中文阅读习惯写", or a fully-spec'd handoff prompt with slugs + input_root + output_root + date (+ optional mode). This is a leaf executor—it owns single-article quality (忠实通顺、人称代词约束、保留英文白名单、领域专名一致性). Path/dir setup, frontmatter shape, image-ref rewriting, and post-translation self-checks are all delegated to scripts/translate-prepare.mjs + scripts/translate-verify.mjs. Caller (typically material-pipeline) decides slugs / input_root / output_root / date / mode — if any required field is missing, stop and ask. Does not register results into site navigation; does not orchestrate batches.
version: 4.0.0
Translate 文章中译执行器
把英文 Markdown 文章转成中文。提供两种工作模式：
- 原文翻译模式（默认）——段落 / 列表 / 标题层级与原文 1:1 对齐，零省略、零摘要压缩。适合作者论证骨架本身就值得忠实保留的稿子（学术性、强结构、引用密集）。
- 原文重写模式——尊重原文 H2 序列，但章节内段落、列表、表格、强调按中文媒体节奏重组；可合并过场段、把散文里的密集事实转成 list/table、给小标题加 takeaway。适合英文写作惯性较重的稿子（hook 开头、过场段多、散文里塞着一堆数据）。
这是一个 leaf executor skill——只负责单篇的语义工作（忠实/通顺/中文流畅度）。机械活（建目录、拷图、frontmatter 形状、图片路径改写、终末自检）全部由 helper 脚本承担，不靠 Claude 凭记忆操作。
两种模式速览
| 维度 | 原文翻译模式（默认） | 原文重写模式 |
|---|
| 触发 | 调用方不传 mode，或显式 mode=translate | 调用方显式 mode=rewrite；或用户原话："按中文重写"、"按中文阅读习惯写"、"用中文重新写一篇" |
| 段落顺序 | 严格 1:1 对齐 | H2 序列保留；章节内段落顺序可调 |
| 段落 / 列表项数 | 与原文一致 | 可合可拆 |
| 散文 vs list/table | 保持原文形式 | 密集事实可转 list / table |
| 小标题 | 直译，层级与原文一致 | 可加 takeaway；可拆出 H3 |
| 过场段 | 全部保留 | 英文式过场段可删或极简 |
| 信息忠实 | 零省略、零摘要压缩 | 数字/人名/引语全保；表达层面全放 |
| frontmatter 契约 | 同（共用） | 同（共用） |
| verify 硬检查 | 同（共用） | 同（共用） |
| 典型用法 | 教科书式翻译；存量稿件中译 | 中文媒体风格的解读类文章 |
默认走原文翻译模式——除非调用方明示，或用户原话提到"重写"、"按中文阅读习惯"。leaf 不替调用方决策模式。
调用契约
调用方必须显式提供 4 项必填参数，缺任一就停下问，不要按历史路径凭空填值：
| 字段 | 必填 | 含义 |
|---|
slugs | 是 | 要处理的 slug 列表（≥1 条） |
input_root | 是 | 源根目录绝对路径，每个 slug 对应 <input_root>/<slug>/<slug>.md + 可选 <input_root>/<slug>/assets/ |
output_root | 是 | 输出根目录绝对路径，产物落到 <output_root>/<slug>.md + <output_root>/images/<slug>/ |
date | 是 | YYYY-MM-DD，写进译文 frontmatter 的 translated 字段 |
mode | 否 | translate（默认） 或 rewrite。可选；不传则按原文翻译模式 |
日期分层是调用方的策略——material-pipeline 已把 output_root 指向 materials/output/<date>/，本 skill 看到的就是扁平目录。
工作流（每个 slug 三步）
步骤 1：跑 prepare 准备机械骨架（两模式共用）
node <skill 目录>/scripts/translate-prepare.mjs \
--slug <slug> \
--input-root <input_root> \
--output-root <output_root> \
--date <date>
它会：
- 建好
<output_root>/images/<slug>/，并把 <input_root>/<slug>/assets/* 全部拷过去
- 读源 frontmatter，按"输出字段 + 顺序"生成目标 frontmatter（
translated 填好）
- 在
<output_root>/<slug>.md 写入"目标 frontmatter + 源 body + 图片引用已改写为 ./images/<slug>/"的骨架
骨架里的 frontmatter title / excerpt（如有）还是英文，body 也是英文——这是供你就地改写的底板。
目标 frontmatter 字段（顺序固定，两模式共用）：
| 字段 | 来源 | 是否必填 |
|---|
title | 源（英文，待译） | 必填 |
author | 源（保留英文原值） | 必填 |
url | 源（保留原值） | 必填 |
translated | 调用方 --date | 必填 |
excerpt | 源（英文，待译） | 可选——源 frontmatter 有就出现 |
tags | 源（英文原值，原样透传） | 可选 |
步骤 2：把英文骨架改写成中文（这里是 Claude 唯一的真活）
Read 骨架文件 → 按当前 mode 对应的规则整篇改写 → 用一次 Write 覆盖回同一路径。
mode=translate → 按下方「原文翻译模式：规则详解」mode=rewrite → 按下方「原文重写模式：规则详解」
两模式都绝对要保留的：
- frontmatter 块边界（
--- ... ---）与字段集合 + 顺序；只翻译 title 与 excerpt（如有）的值
- 所有图片引用（已是
./images/<slug>/... 形式）；不要改路径，不要去/加 () 周围空格
- 链接 URL 原样；链接 anchor 文本译为中文
步骤 3：跑 verify 把质量门关掉（两模式共用）
node <skill 目录>/scripts/translate-verify.mjs \
--slug <slug> \
--output-root <output_root> \
--date <date>
它会硬检查：
- body 无残留
./assets/ 引用
- md 图片引用文件名 vs
images/<slug>/ 文件名一致（缺/多都报）
frontmatter.translated 与 --date 一致- frontmatter 字段子集 ⊆
[title, author, url, translated, excerpt, tags] 且顺序正确，无额外字段
title 含 CJK（英文标题 = 改写未完成）
并打印：孤儿图片（⚠）、excerpt 仍是英文（⚠，软提示漏译）。
注：代词节制（"你/你的/我们"等）由译者按语感判断，verify 不打印代词密度、也没有数值阈值——阈值化会被当成"达标即可"的硬指标，反过来引导出过度删代词或忽视语感的译文。规则在下方「人称代词」一节，执行靠默读自检。
任一硬检查失败 → exit 1 → 修译文重跑 verify，直至通过。
原文翻译模式：规则详解
⓪ 最高规则：杜绝翻译腔（凌驾于其它所有规则之上）
译文必须读起来像中国作者手写的中文——而不是从英文一句一句对译过来的"翻译稿"。任何一段译文，读者闭着眼应该感觉是原创中文文章，而不是机器翻译产物。这条规则优先级高于下面所有规则——为了不出翻译腔，可以重组句序、合并/拆分句子、调整段落内的叙事节奏。
翻译腔的典型病征（写之前先记住，写完逐项自检）：
| 病征 | ✗ 翻译腔 | ✓ 自然中文 |
|---|
| 主语全留 | 你的 AI agent 可以读你的代码库 | AI agent 能读代码库 |
| 长定语前置堆叠 | 一个被设计来处理复杂任务的能够同时管理多个子任务的智能体系统 | 一套能处理复杂任务、同时管理多个子任务的智能体系统 |
| "的"字串成串 | 这是一个简单的高效的可复用的工具 | 这是一个简洁、高效、可复用的工具 |
| "进行/做出 + 名词" | 我们对系统进行了优化 / 做出了改进 | 我们优化了系统 / 改进了系统 |
| "当……的时候" | 当系统失败的时候 | 系统失败时 |
| 被动语态 | 该问题被发现后，相关补丁被部署 | 发现问题后，部署了补丁 |
| "对于……来说" / "关于……方面" | 对于性能来说，这很重要 | 性能上这很重要 / 这对性能很关键 |
| 翻译式连接词过密 | 基于此 / 在此基础上 / 与此同时 / 不仅如此 / 值得注意的是 | 顺其自然——按中文写作节奏用"于是 / 接着 / 而 / 但" |
| 冗余量词 | 它是一种非常强大的一个工具 | 是个强大工具 / 工具非常强 |
| "存在……的问题/情况" | 该方案存在性能不佳的问题 | 该方案性能不行 / 这方案跑得慢 |
| "进行了一次……" | 我们进行了一次重构 | 我们重构了 / 重构了一遍 |
| 完整保留英文语序 | 通过使用 X，我们实现了 Y | 用 X 拿到 Y / X 让 Y 成为可能 |
自检手段：写完一段，默读一遍——卡顿、别扭、需要停下来理解结构的地方就是翻译腔。改到读起来一气呵成为止。
判定标杆：少数派 / 机器之心 / InfoQ 中文站 / 阮一峰周刊 / 知乎技术大V 的写作风格。如果一句话不可能出现在这些媒体的原创文章里，就改写。
① 忠实信息，通顺表达
译文要完整传达原文的全部信息，同时读起来是自然、流畅的中文。忠实的单位是段落 / 意群，不是单个句子——英文靠从句层层嵌套，中文靠短句流水推进，强行一句对一句必出翻译腔（见规则 ⓪）。
必须保留（硬约束）：
- 零内容省略：原文每一个段落、列表项、引用块、图片 alt + caption 都必须出现在译文里。不准因为"这句和上句意思重复"就省掉。
- 零摘要压缩：不做精炼、不做概括式改写；原文展开讲的，译文也展开讲。
- 细节锚点：所有数字、百分比、年份、人名、产品名、版本号、URL、专有名词、引用语措辞，一律按字面照搬，不四舍五入、不本地化、不替换为更通用的说法。
- 强调与口吻：原文加粗就加粗、斜体就斜体；第一人称保留第一人称；反问、感叹、口语、调侃的语气，译文保留同等强度。
- 结构对应：标题层级、段落数量与顺序、列表项数量与顺序、引用块、图片位置，与原文一致。
- 不补新信息：不添加原文没有的事实、解释、举例、背景。允许补充的只有让中文连贯所必需的连接词与过渡（见下）。
为通顺而放开（鼓励）：
- 句子可合可拆：一个英文长句可拆成几个中文短句；几个关系紧密的英文短句也可并成一句中文。以"中文读着顺"为准。
- 子句可重排：定语、状语、条件从句的位置按中文习惯调整（如英文后置定语从句 → 中文前置，或拆成后续短句）。
- 可补连接词：为让行文连贯，可加"因此 / 也就是说 / 但 / 于是 / 换句话说"等中文连接词——只补逻辑连接，不补新内容。
- 长从句链 → 流水短句：遇到层层嵌套的英文长句，拆成符合中文节奏的短句序列。
每翻完一段，自检：原文这一段承载的信息点（事实、数字、因果、转折、强调、态度），在译文这一段里是否都在、是否没多没少？ 对得上即可——不要再去数句子数量。
人称代词：能省就省
英文语法要求主语必有，中文允许且鼓励主语脱落。把英文 I / we / our / you / your / it / they 逐一直译，结果就是"你 / 你的 / 我们 / 我们的 / 它 / 它们"密度爆表的翻译腔。
关键消歧：人称代词不是前面「翻译原则」里"细节锚点"的一部分，不在"按字面照搬"范畴。事实、数字、人名要忠实，代词不要——上下文足够指代时省去。
判定方式：靠语感和默读，不靠数值。脚本不会统计代词密度，更没有"达标阈值"——一旦数字化，写出来的就是凑数译文。规则就一句话：能省就省，不是必须降到零。
"it / they" 指代事物时：复述名词或省略，不要"它 / 它们"堆叠。
对照示例（取自真实译文里的失败案例）：
| 原文 | ✗ 直译 | ✓ 自然 |
|---|
| Your AI agent can grep your entire codebase, but it lacks your product's design context. | 你的 AI agent 可以 grep 你的整个代码库，但它缺的是你产品的 design context。 | AI agent 能 grep 整个代码库，缺的是产品的 design context。 |
| I can describe our architecture in our README, list our entities, point to our component library. | 我可以在 README 里描述我们的架构，可以列出我们的实体，可以指向我们的组件库。 | README 里可以描述架构、列出实体、指向组件库。 |
| They lay in taste, in some Figma file, in our Slack threads. | 它们躺在 taste 里、躺在某个 Figma 文件里、躺在我们的 Slack 对话里。 | 躺在 taste 里、躺在某个 Figma 文件里、躺在 Slack 对话里。 |
保留代词的例外：
- 强烈第一人称叙事的段首（"我做了 X / 我试了 Y"）保留"我"作主语；但避免"我"开头的句子连续出现
- 对比/强调必须依赖代词时（"不是他们的，是我们的"）
- 同段出现多个主体、不复述名词会歧义时
保留英文，不要翻译
保留英文是封闭白名单，不是默认行为。只有下面这几类才不翻译；不在列内、且中文有约定俗成译法的，一律译。
- 人名：Karpathy、Andrej、Yanli Liu、Sam Altman 等。
- 产品 / 公司 / 模型名：Claude、Claude Code、Anthropic、OpenAI、Codex、ChatGPT、Gemini、Llama、GPT、Cursor、Copilot、GitHub、Medium、Unsplash、Pinecone、Weaviate、Qdrant、PostgreSQL 等。
- 文件 / 标识符：
CLAUDE.md、AGENTS.md、README.md、package.json、.cursorrules、命令行片段、shell 命令、/plugin、curl ...。
- 真正的字母缩写 + AI 领域无定译核心词：LLM、API、JSON、CSV、RAG、MCP、CNN、RNN、GPU、PII、SDK、UTC、CTA、Token、Embedding、Attention、Transformer 等。一般缩写出现就保留英文，不要翻成"大语言模型 (LLM)"这种带括号注释的形式（除非是首次出现且对新手关键的术语）。
- AI agent 领域译法未稳的高频词（可保留）：agent、prompt、context、skill、router（限编排上下文）。注意：可保留 ≠ 必须保留——能用中文表达且不损失精度时，仍优先译。
- 代码块（
...）：内部内容完全不翻译，包括注释。例外：注释里的纯叙述性中文/英文段落如果显然不是代码语义的一部分，可酌情翻译。
- 链接 URL：
[anchor](URL) 中的 URL 一律保持原样；anchor 文本翻译成中文。
不在以上类别 → 默认译。常见误判（本应译却被保留英文的，按推荐中文替换）：
| 英文原词 | 推荐中文 |
|---|
| dashboard | 仪表盘 / 看板（按上下文） |
| widget | 部件 / 小组件 |
| breakpoint | 断点 / 响应式断点 |
| repo | 仓库 |
| commit | 提交 |
| session | 会话 |
| frontmatter | 前置元数据 / 文件头元数据 |
| onboarding | 新人引导 / 引导流程 |
| review | 评审 / 复审 |
| bug | 缺陷 / bug（口语博客可保留） |
| TL;DR | 摘要 / TL;DR（口语博客可保留） |
判定原则：中文技术媒体（少数派、机器之心、InfoQ 中文站、阮一峰周刊、UI 中国）习惯怎么写就怎么写。不要把"保留英文的范围"无限外推到所有 IT 名词。
领域专名（设计风格 / 学术流派 / 方法论）
设计风格名（neobrutalist、glassmorphic、maximalist）、学术流派（impressionism、cubism）、方法论（agile、lean、kanban）这类不属于"产品/公司/缩写"的领域专名：
- 有公认中文译法的优先译：neobrutalist → 新粗野主义 / 新野兽派；glassmorphic → 玻璃拟态；maximalist → 极繁主义；playful → 俏皮风；impressionism → 印象派；agile → 敏捷；lean → 精益
- 没有公认译法的可保留英文，首次出现时酌情加一句中文意译
- 同一句 / 同一段内必须保持一致：不允许同一个枚举里既译又不译
英文排版强调（caps / italics）→ 中文等价手段
原文用全大写或斜体表示强调时（如 "we are NOT neobrutalist"、"this is the answer"），中文必须换成中文等价手段，不要原样保留英文 caps 或英文斜体。
| 英文强调 | ✗ 直搬 | ✓ 中文等价 |
|---|
| we are NOT neobrutalist | 我们就 NOT neobrutalist | 我们就不是新粗野主义 |
| this is the answer | 这是 the 答案 | 这才是那个答案 |
| I did try | 我did试过 | 我确实试过 |
可用的中文强调手段：粗体（**...**）、副词（"绝""根本""压根""偏偏""确实"）、语气词（"就是""恰恰"）、引号。
例外：英文斜体如果标记的是书名、专有术语、外来语（如 Bloomberg Terminal、ad hoc、Zeitgeist），按原意保留斜体——这不算"强调"，是排版约定。
标题、引用、代码、风格细节
- 不要在正文里追加"原文链接 / 作者 / 译者注"之类的引用块——这些元数据已在 frontmatter 里
- 图注（
*Photo by ...* / *Diagram by Author: ...*）→ *图片来源：...* / *作者绘图：...*
- 段落与列表的划分保持与原文一致：不合并/拆分段落、不增删/合并列表项（句子在段落内部可合可拆）
- 不要添加译者点评、个人观点，或额外的"翻译说明"段落
- 原文如果有 inline diff（
- /+ ）或代码片段，原样保留为代码块，不要翻译里面的英文标识符
- 引用块里的叙述句可译为中文；作者引语
"..." 译为中文并保留引号，保持原说话人口吻
中文行文风格：
- 短句优先：一句话讲一件事。中文句子超过约 40–50 字、或定语层层套叠时，拆开
- 去翻译腔：
- 被动语态："X 被 Y 所驱动" → "Y 驱动着 X" / "X 由 Y 驱动"
- 一个句子里多个"的"时，删冗余的、或改语序
- "当……的时候" 简化为 "……时"
- 删冗余虚词：英文语法要求、中文里冗余的虚词去掉；同义反复处合并表达（合并的是说法，不是删信息）
- 标点：句号、逗号、冒号用全角；英文专有名词周围保留必要的半角空格；引号优先用英文双引号
"..."
原文重写模式：规则详解
⚠️ 只在调用方明示 mode=rewrite、或用户原话提到"按中文重写"、"按中文阅读习惯写"时启用。默认仍走原文翻译模式。
原文重写模式的核心信念：译文要像中文媒体的原创稿，不是翻译稿。允许动结构、动节奏、动呈现形式，但信息层面零损失。
1. 边界：信息忠实，表达全放
- 零信息损失：数字、百分比、年份、人名、产品名、版本号、URL、引用语措辞——一字不改
- 结构全放：段落顺序、句子边界、列表展开方式、强调位置、章节内章法——按中文媒体习惯重组
"忠实"的对象是事实而不是表达形式。
2. 章节顺序保留，章节内可重塑
- 不动原文 H2 序列——作者的论证骨架通常是有道理的，动了就脱离原作
- H3 可拆可合可加：原文一节里的多块信息可拆成几个 H3 子节；几个相邻短节可合并
- 章节内的段落、列表、表格、强调全部按中文节奏重新组织
3. 散文里的密集事实 → 清单或表格
原文一段连续叙述里塞了一组数字（如 "75 万行 / 99.8% / 11 天"）、上手要点（状态/渠道/默认/启动）、对照（用 vs 不用）——就算原文是散文，中文也用 bullet 或 table。中文媒体读者扫描效率差好几倍。
典型转写场景：
- 多个数据点连续出现 → bullet list
- "用 X，不用 Y" 的对照 → table
- 上手要点（状态/渠道/默认值/启动方式）→ bullet list
- 三个以上并列特性 → bullet list
4. 小标题加 takeaway
中文技术媒体的标题习惯是「标题：结论或卖点」，而不是英文那种抽象主题词。
| ✗ 翻译过来的英式标题 | ✓ 中文式带 takeaway |
|---|
| Fast Mode: Cheaper, Faster Loops | Fast mode：三倍便宜，值得回头看看你毙过的想法 |
| Why Opus 4.8 Is Easier to Trust | 为什么 Opus 4.8 更让人放心：它学会了承认自己没把握 |
| Honest Limitations | 几条丑话 |
目的：读者扫一眼就能取到本节要点。
5. 英文式过场段直接删或极简
原文里那种"段落 hook"——英文写作的惯性产物——在中文里基本都是水：
| 英文式过场 | 中文处理 |
|---|
| "The headline says X. The more interesting story is Y." | 直接说 Y |
| "Here is the combined picture." | 删；或压成一句 "把这些拼起来：" |
| "The caveats belong up front, so here they are." | 删；或一句 "几条丑话" |
| "Two disclosures, because both matter." | 一句 "先交代两件事" |
| "Let us start with..." | 删 |
判断标准：这一段不传递任何新信息，只是英文行文的连接组织手段 → 删或极简。
6. dangling 句降权
原文里那种"卖瓜句"——后面没接内容、独立成段的——在中文里突兀。处理方式：
- 放进引用块（降权但保留信息）
- 合并进相邻段
- 实在没用就删
例子：原文末尾 "Here is my version of a interactive Claude Code Plugin — On Github:" 后面什么都没有 → 改成引用块：「> 顺带：我自己做了一个交互式 Claude Code 插件——在 Github 上。」
7. 删英文 transition 的直译
大部分英文 transition 直译过来都是水：
- 也就是说 / 也即 / 具体而言 / 另一方面 / 换句话说
- 在某种意义上 / 在...之上 / 从某种程度上看
- 值得一提的是 / 不可忽视的是
中文按行文节奏自然连接即可——大部分时候不需要任何连接词，中文短句靠并列就能流畅推进。
8. 代词节制按语感
与原文翻译模式的「人称代词」一节相同：能省就省、不强删到零、不靠数字判断。
9. frontmatter 契约不破
title / author / url / translated / excerpt / tags 的字段集合、顺序、值的处理一律不变；只有 title 与 excerpt 的"中文写法"可以更博客化（标题加 takeaway 风格、excerpt 写成中文媒体常用的"...，加上..."结构）。
10. 完成后做"扫描测试"
写完后，假装自己是中文技术媒体读者，按以下路径扫描全文：
H2 → H3 → 加粗 → list / table → 散文
如果一段超过 200 字、没有任何扫描锚点（加粗 / list / 子标题 / 数字），拆。
如果整篇全是散文段，没有 list 也没有 table，重新看一眼第 3 条。
重写模式不做的事
- 不改事实——数字、人名、引语、产品名、版本号一律字面照搬
- 不加观点——不添加译者评注、个人观点、原文没有的背景
- 不动 H2 顺序——作者的论证骨架要保留
- 不动 frontmatter 字段契约——和原文翻译模式完全一致
完成回复（两模式共用）
跑完 prepare → translate/rewrite → verify 后，至少说明：
- 每个 slug：图片张数、verify 是否通过；如有 ⚠（孤儿图 / excerpt 漏译）一并列出
- 使用的 mode（translate / rewrite）
- 没未译的英文残留 / 没遗漏的图片
这个 skill 不做的事
- 不决定路径 / 日期 / 批次 / mode —— 5 个契约字段（mode 可选）由调用方提供
- 不做并发调度 —— 多 agent 并行由编排者（material-pipeline）决策
- 不做跨日去重 —— 同名文件直接覆盖；是否覆盖是编排者的决定
- 不扫描
output_root 决定"还没译过的" —— slug 选择是调用方在更上游完成的
- 不写
_meta.json / 不接入站点导航 / 不修改 medium-sub / medium-fetch / material-pipeline 的代码
