---
name: translate-post
description: 把英文文章翻译成本站的中英对照文章（posts/ 下的 bilingual 译文），再用 humanizer 把中文润色一遍。两个子命令：`file <路径>` 读本地文件，`url <网址>` 抓网页。用户说「翻译这篇」「做成中英对照」「把这个链接翻成文章」时使用。
argument-hint: file <本地路径> | url <网址>
---

# 中英对照译文

参数：`$ARGUMENTS`

## 硬性要求（每一步都适用）

- **全文翻译，绝对不是摘要。** 原文每一段、每一个列表项、每一句都要有对应的译文，不缩写、不合并、不跳过「看起来不重要」的段落。文章再长也分批翻完，不能因为篇幅省略。
- **图片、视频等资源原样保留在原来的位置。** markdown 图片 `![](...)`、`<img>`、`<video>`、`<iframe>`（YouTube 等嵌入）、音频、GIF 都要在。只写一份，放在对应的段落之间，**不放进 `.yn-en` 块里**（否则只看中文时会被一起藏掉）。图片的 alt 文字可以翻成中文。
- **媒体先下载到本地，下不了再用原链接。** 做法见下面「媒体本地化」。

## 媒体本地化

翻译前先把文中的媒体处理掉：

1. 目录：`public/posts/<slug>/`，`<slug>` 用原文英文标题转成小写连字符（如 `building-effective-ai-agents`）。**不用中文文件名**——路径里有空格和中文时 markdown 图片语法会断。
2. 逐个下载：`curl -fsSL --max-time 60 -o public/posts/<slug>/<文件名> <URL>`。文件名取 URL 路径最后一段（去掉 query），没有扩展名或重名时按顺序编号 `01.png`、`02.mp4`，扩展名按 `file --mime-type` 补对。
3. 校验：`file --mime-type` 必须是 `image/*`、`video/*` 或 `audio/*`，且文件非空。拿到的是 HTML（防盗链、登录页）就删掉，当作下载失败。
4. PNG / JPG 转成 WebP，转完删掉原图（站里的配图全是 WebP，PNG 平均小六七成）：
   - PNG（流程图、截图）用无损，像素不变：`cwebp -quiet -lossless -z 9 a.png -o a.webp`
   - JPG 用 q85：`cwebp -quiet -q 85 -sharp_yuv -m 6 -metadata none a.jpg -o a.webp`。原图本来就是有损的，用无损反而大一倍多
   - 极少数情况转完比原图还大，就留原图不转。GIF（可能是动图）、SVG、视频不转
   - 没有 `cwebp` 就 `brew install webp`；装不上就留原图，汇报里说一声
5. 成功的改成站内绝对路径 `/posts/<slug>/<文件名>`（转过的写 `.webp`）；失败的保留原文的绝对 URL。
6. 不下载的：YouTube / Vimeo 等 `<iframe>` 嵌入（本来就只能嵌），以及超过 20MB 的视频（进 git 仓库太大）——这两类保留原链接。
7. 本地 md 里的相对路径（`./img/a.png`）：在源文件旁边找到就复制进同一目录（同样按第 4 步转换），找不到就保留原引用并记下来。

最后汇报时列出：几个下载成功、几个用了原链接（以及原因）、转 WebP 前后的总体积。

## 0. 分派

看第一个词：

- `file <路径>` → 走 1a
- `url <网址>` → 走 1b
- 没写子命令：以 `http://` / `https://` 开头当 `url`，否则当 `file`
- 参数为空：问用户要文件路径或网址，不要猜

## 1a. 从本地文件读

用户给的都是本地 `.md`。用 Read 把整个文件读完（长文件用 `offset` 分段读到结尾，路径含空格时照原样传）。正文就按原文的 markdown 来，**不要重新整理或精简**；只去掉剪藏工具留下的非正文内容（文件自带的 front matter、「Clipped from…」之类的说明行）。

**找原文链接**，按顺序：

1. front matter 里的 `source` / `url` / `link` / `original` / `origin` / `canonical` 等字段；
2. 正文开头几行里形如「原文」「Source:」「Originally published at」后面的链接。

找到就记下，第 3 步写进 front matter 的 `source`。**找不到就停下问用户要**，不要拿正文里随便一个链接充数，也不要省略。

图片、视频按上面「媒体本地化」处理。

## 1b. 从网页抓

**目标是逐字拿到全文，不是摘要。** WebFetch 会让小模型处理页面，长文容易被截断或改写，所以按下面顺序来：

1. WebFetch，prompt 写：「把这篇文章的正文原样转成 markdown 返回，一个字都不要改、不要总结、不要省略。保留所有标题、列表、代码块、图片和视频（用绝对 URL，视频和 iframe 嵌入保留原 HTML）和链接。」
2. **核对完整性**：用 `curl -sL <网址>` 存到 scratchpad 里一个新建的空目录，`grep -o '<h[1-6][^>]*>[^<]*' ` 列出原页面的标题，和第 1 步结果的标题逐个对；再看结尾那段是不是原文最后一段。对不上就说明被截断了。
3. 截断时：从 curl 下来的 HTML 里取 `<article>`（没有就取 `<main>`）这一段自己转 markdown。页面是客户端渲染、curl 拿不到正文时，用 chrome-devtools 打开页面，`evaluate_script` 取 `document.querySelector('article, main').innerText` 和图片地址。

原文链接就是这个网址，第 3 步写进 front matter 的 `source`。图片、视频先换成绝对 URL，再按「媒体本地化」下载。付费墙、需要登录或内容明显不全时，停下告诉用户，不要拿残缺的内容去翻译。

## 2. 翻译

先读 `posts/` 下一两篇已有文章（不是 `index.md`），对一下本站中文的语气：口语化、第一人称、短句、少用书面套话。译文向它靠，但**意思以原文为准**：不加原文没有的信息，不删原文有的论点，数字、专有名词、引语照译。

- 术语第一次出现时写成「中文（English）」，之后只用中文；没有通行译名的（产品名、库名、API 名）保留英文。
- 代码块、命令、行内代码、URL 不翻译。代码里的注释可以翻，但只改注释。
- 原文的强调（粗体、斜体）照搬到对应的中文位置。

## 3. 写成对照格式

样式在 `.vitepress/theme/style.css` 的「中英对照」那段，写法必须跟它对上，否则样式和阅读时长都会算错。

**front matter：**

```yaml
---
title: 中文标题
date: YYYY-MM-DD        # 今天，不加引号
description: 一两句中文简介，说清这篇讲什么
tags: [翻译, 标签1, 标签2]   # 第一个固定是「翻译」，后面按内容加
bilingual: true
source: https://...     # 原文链接
sourceTitle: "Original English Title"   # 原文标题，照英文原样、不翻译；含冒号，必须加引号
---
```

**开头**：文章标题 h1 只写中文（不要对照），后面直接接正文。原文链接**不写进正文**：`PostMeta` 读 front matter 的 `source` + `sourceTitle`，在标题下方渲染成「原文标题 + 外链图标」的链接。不写作者、发表时间等任何其他信息：

```markdown
# 中文标题

<div class="yn-en" lang="en">
```

**段落**：每段英文原文包进 `<div class="yn-en" lang="en">`，中文紧跟在后面。div 和里面的 markdown 之间**必须留空行**，否则 markdown-it 不解析：

```markdown
<div class="yn-en" lang="en">

English paragraph.

</div>

中文段落。
```

一个 div 里只放一段（或一个列表、一个引用），**div 里不能再嵌 div**——`config.mts` 算阅读时长的正则按最近的 `</div>` 截断，嵌套会把后面的中文也剔掉。

**标题**（h2 及以下）：英文在上、中文在下，写在同一行：

```markdown
## <span class="yn-en ignore-header" lang="en">English Heading</span>中文标题
```

**列表**：逐项对照，英文和中文在同一个 `li` 里：

```markdown
- <span class="yn-en" lang="en">English item.</span>中文条目。
- <span class="yn-en" lang="en">Another item.</span>另一条。
```

**引用**：整块原文引用放进 div，中文引用跟在后面：

```markdown
<div class="yn-en" lang="en">

> English quote.

</div>

> 中文引用。
```

**粗体、斜体的边界**：`**` 的内侧紧挨标点（`。` `：` `」` `.` 等），外侧又紧挨文字时，CommonMark 不认它，页面上会原样露出星号。中英文都一样，中文句末带句号的粗体导语最容易中招：

```markdown
**看证据。**测试输出……      ✗ 不渲染
**看证据。** 测试输出……     ✓ 结束的 ** 后面加一个空格
前文**「引语」**后文          ✗ 开头的 ** 内侧是「，外侧是文字
前文 **「引语」** 后文        ✓ 两边都加空格
```

`*斜体*` 和 `_斜体_` 是同一条规则。

**只写一份、不对照的**：代码块、图片、视频和其他嵌入、表格（表格直接翻成中文；表头是专有名词就留英文）、公式、嵌入的 HTML。

文件名用中文标题：`posts/<中文标题>.md`（和现有文章一致，冒号用全角 `：`，去掉 `/` 等不能进文件名的字符）。同名文件已存在时先问用户。

## 4. humanizer 润色中文

用 Skill 工具调用 `humanizer:humanizer`，**embedded 模式**，只交给它中文部分。调用时说明：

- 只改中文正文和中文标题；`.yn-en` 里的英文原文、front matter、代码、链接地址、HTML 标签一律不动。
- 写作样本是第 2 步读过的那篇本站文章，照它的语气。
- 这是译文：可以拆句、换词序、去掉翻译腔，但每段中文仍要和上面那段英文**意思一一对应**，不能合并段落、不能跨段挪内容（否则对照就对不上了），不能删句子、不能缩写成概括，不能补原文没有的事实。
- 图片、视频、嵌入一个都不能动。

拿回结果后逐段核对：英文块数和中文段数相等，没有丢段、没有哪段中文明显比英文短一截（那通常是被概括了）；改完写回文件。

## 5. 验证

1. **完整性对账**（对原文 vs 译文各数一遍，数字必须相等）：
   - 段落/列表项/标题数：原文的块数 = 译文里 `class="yn-en` 的个数；
   - 图片数：`grep -oE '!\[|<img' | wc -l`；视频/嵌入数：`grep -oE '<(video|iframe|audio)' | wc -l`；代码块数：```` ``` ```` 的个数。
   任何一项对不上，回去补，不要交差。
2. `grep -n '<div class="yn-en"' -A1` 确认每个开标签后都是空行；front matter 里有 `source` 和 `sourceTitle`（原文英文标题，不是网址），正文里没有「原文：」那行引用。
3. **粗体边界**（见第 3 步）：下面这条列出所有渲染不出来的 `**…**`，必须没有输出。有输出就按第 3 步的写法补空格。humanizer 改过的中文也要过这一遍：
   ```bash
   perl -CSA -Mutf8 -ne 'utf8::decode($_); my $p=qr/[\s\p{P}\p{S}]/; while (/\*\*(?!\s)(.+?)(?<!\s)\*\*/g) { my ($m,$s,$e,$in)=($&,$-[0],$+[0],$1); my $b=$s?substr($_,$s-1,1):" "; my $a=substr($_,$e,1); $a=" " if $a!~/./; print "$.: $m\n" if ($in=~/^[\p{P}\p{S}]/ && $b!~$p) || ($in=~/[\p{P}\p{S}]$/ && $a!~$p) }' "posts/<文件名>.md"
   ```
4. `pnpm build` 通过。
5. 在产物里打开这篇（`pnpm preview`），确认工具条出现「中En」开关、切到只看中文后英文全部隐藏、目录里只列中文标题、阅读时长是按中文算出来的合理数字。

最后告诉用户：文件路径、原文链接、上面对账的数字、媒体下载情况、有哪些地方拿不准（术语译法、原文含糊处），以及第 1b 步是否发生过截断回退。
