translate-post
安装 · INSTALL
curl -fsSL --create-dirs -o ~/.claude/skills/translate-post/SKILL.md https://nyann.cc/raw/skills/translate-post/SKILL.md 装到 ~/.claude/skills/translate-post/,重开 Claude Code 后输入 /translate-post 调用。
简介 · SUMMARY
把英文文章翻译成本站的中英对照文章(posts/ 下的 bilingual 译文),再用 humanizer 把中文润色一遍。两个子命令:file <路径> 读本地文件,url <网址> 抓网页。用户说「翻译这篇」「做成中英对照」「把这个链接翻成文章」时使用。
原文 · SKILL.md 查看原始文件
下面是 SKILL.md 的完整内容,也就是 Claude 实际读到的指令。
参数:$ARGUMENTS
硬性要求(每一步都适用)
- 全文翻译,绝对不是摘要。 原文每一段、每一个列表项、每一句都要有对应的译文,不缩写、不合并、不跳过「看起来不重要」的段落。文章再长也分批翻完,不能因为篇幅省略。
- 图片、视频等资源原样保留在原来的位置。 markdown 图片
、<img>、<video>、<iframe>(YouTube 等嵌入)、音频、GIF 都要在。只写一份,放在对应的段落之间,不放进.yn-en块里(否则只看中文时会被一起藏掉)。图片的 alt 文字可以翻成中文。 - 媒体先下载到本地,下不了再用原链接。 做法见下面「媒体本地化」。
媒体本地化
翻译前先把文中的媒体处理掉:
- 目录:
public/posts/<slug>/,<slug>用原文英文标题转成小写连字符(如building-effective-ai-agents)。不用中文文件名——路径里有空格和中文时 markdown 图片语法会断。 - 逐个下载:
curl -fsSL --max-time 60 -o public/posts/<slug>/<文件名> <URL>。文件名取 URL 路径最后一段(去掉 query),没有扩展名或重名时按顺序编号01.png、02.mp4,扩展名按file --mime-type补对。 - 校验:
file --mime-type必须是image/*、video/*或audio/*,且文件非空。拿到的是 HTML(防盗链、登录页)就删掉,当作下载失败。 - 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;装不上就留原图,汇报里说一声
- PNG(流程图、截图)用无损,像素不变:
- 成功的改成站内绝对路径
/posts/<slug>/<文件名>(转过的写.webp);失败的保留原文的绝对 URL。 - 不下载的:YouTube / Vimeo 等
<iframe>嵌入(本来就只能嵌),以及超过 20MB 的视频(进 git 仓库太大)——这两类保留原链接。 - 本地 md 里的相对路径(
./img/a.png):在源文件旁边找到就复制进同一目录(同样按第 4 步转换),找不到就保留原引用并记下来。
最后汇报时列出:几个下载成功、几个用了原链接(以及原因)、转 WebP 前后的总体积。
0. 分派
看第一个词:
file <路径>→ 走 1aurl <网址>→ 走 1b- 没写子命令:以
http:///https://开头当url,否则当file - 参数为空:问用户要文件路径或网址,不要猜
1a. 从本地文件读
用户给的都是本地 .md。用 Read 把整个文件读完(长文件用 offset 分段读到结尾,路径含空格时照原样传)。正文就按原文的 markdown 来,不要重新整理或精简;只去掉剪藏工具留下的非正文内容(文件自带的 front matter、「Clipped from…」之类的说明行)。
找原文链接,按顺序:
- front matter 里的
source/url/link/original/origin/canonical等字段; - 正文开头几行里形如「原文」「Source:」「Originally published at」后面的链接。
找到就记下,第 3 步写进 front matter 的 source。找不到就停下问用户要,不要拿正文里随便一个链接充数,也不要省略。
图片、视频按上面「媒体本地化」处理。
1b. 从网页抓
目标是逐字拿到全文,不是摘要。 WebFetch 会让小模型处理页面,长文容易被截断或改写,所以按下面顺序来:
- WebFetch,prompt 写:「把这篇文章的正文原样转成 markdown 返回,一个字都不要改、不要总结、不要省略。保留所有标题、列表、代码块、图片和视频(用绝对 URL,视频和 iframe 嵌入保留原 HTML)和链接。」
- 核对完整性:用
curl -sL <网址>存到 scratchpad 里一个新建的空目录,grep -o '<h[1-6][^>]*>[^<]*'列出原页面的标题,和第 1 步结果的标题逐个对;再看结尾那段是不是原文最后一段。对不上就说明被截断了。 - 截断时:从 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:
---
title: 中文标题
date: YYYY-MM-DD # 今天,不加引号
description: 一两句中文简介,说清这篇讲什么
tags: [翻译, 标签1, 标签2] # 第一个固定是「翻译」,后面按内容加
bilingual: true
source: https://... # 原文链接
sourceTitle: "Original English Title" # 原文标题,照英文原样、不翻译;含冒号,必须加引号
---开头:文章标题 h1 只写中文(不要对照),后面直接接正文。原文链接不写进正文:PostMeta 读 front matter 的 source + sourceTitle,在标题下方渲染成「原文标题 + 外链图标」的链接。不写作者、发表时间等任何其他信息:
# 中文标题
<div class="yn-en" lang="en">段落:每段英文原文包进 <div class="yn-en" lang="en">,中文紧跟在后面。div 和里面的 markdown 之间必须留空行,否则 markdown-it 不解析:
<div class="yn-en" lang="en">
English paragraph.
</div>
中文段落。一个 div 里只放一段(或一个列表、一个引用),div 里不能再嵌 div——config.mts 算阅读时长的正则按最近的 </div> 截断,嵌套会把后面的中文也剔掉。
标题(h2 及以下):英文在上、中文在下,写在同一行:
## <span class="yn-en ignore-header" lang="en">English Heading</span>中文标题列表:逐项对照,英文和中文在同一个 li 里:
- <span class="yn-en" lang="en">English item.</span>中文条目。
- <span class="yn-en" lang="en">Another item.</span>另一条。引用:整块原文引用放进 div,中文引用跟在后面:
<div class="yn-en" lang="en">
> English quote.
</div>
> 中文引用。粗体、斜体的边界:** 的内侧紧挨标点(。 : 」 . 等),外侧又紧挨文字时,CommonMark 不认它,页面上会原样露出星号。中英文都一样,中文句末带句号的粗体导语最容易中招:
**看证据。**测试输出…… ✗ 不渲染
**看证据。** 测试输出…… ✓ 结束的 ** 后面加一个空格
前文**「引语」**后文 ✗ 开头的 ** 内侧是「,外侧是文字
前文 **「引语」** 后文 ✓ 两边都加空格*斜体* 和 _斜体_ 是同一条规则。
只写一份、不对照的:代码块、图片、视频和其他嵌入、表格(表格直接翻成中文;表头是专有名词就留英文)、公式、嵌入的 HTML。
文件名用中文标题:posts/<中文标题>.md(和现有文章一致,冒号用全角 :,去掉 / 等不能进文件名的字符)。同名文件已存在时先问用户。
4. humanizer 润色中文
用 Skill 工具调用 humanizer:humanizer,embedded 模式,只交给它中文部分。调用时说明:
- 只改中文正文和中文标题;
.yn-en里的英文原文、front matter、代码、链接地址、HTML 标签一律不动。 - 写作样本是第 2 步读过的那篇本站文章,照它的语气。
- 这是译文:可以拆句、换词序、去掉翻译腔,但每段中文仍要和上面那段英文意思一一对应,不能合并段落、不能跨段挪内容(否则对照就对不上了),不能删句子、不能缩写成概括,不能补原文没有的事实。
- 图片、视频、嵌入一个都不能动。
拿回结果后逐段核对:英文块数和中文段数相等,没有丢段、没有哪段中文明显比英文短一截(那通常是被概括了);改完写回文件。
5. 验证
- 完整性对账(对原文 vs 译文各数一遍,数字必须相等):
- 段落/列表项/标题数:原文的块数 = 译文里
class="yn-en的个数; - 图片数:
grep -oE '!\[|<img' | wc -l;视频/嵌入数:grep -oE '<(video|iframe|audio)' | wc -l;代码块数:```的个数。 任何一项对不上,回去补,不要交差。
- 段落/列表项/标题数:原文的块数 = 译文里
grep -n '<div class="yn-en"' -A1确认每个开标签后都是空行;front matter 里有source和sourceTitle(原文英文标题,不是网址),正文里没有「原文:」那行引用。- 粗体边界(见第 3 步):下面这条列出所有渲染不出来的
**…**,必须没有输出。有输出就按第 3 步的写法补空格。humanizer 改过的中文也要过这一遍:bashperl -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" pnpm build通过。- 在产物里打开这篇(
pnpm preview),确认工具条出现「中En」开关、切到只看中文后英文全部隐藏、目录里只列中文标题、阅读时长是按中文算出来的合理数字。
最后告诉用户:文件路径、原文链接、上面对账的数字、媒体下载情况、有哪些地方拿不准(术语译法、原文含糊处),以及第 1b 步是否发生过截断回退。