Skip to content

translate-post

命令
/translate-post
参数
file <本地路径> | url <网址>
文件
SKILL.md
更新
2026-10-31

安装 · 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 文字可以翻成中文。
  • 媒体先下载到本地,下不了再用原链接。 做法见下面「媒体本地化」。

媒体本地化 ​

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

  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 步是否发生过截断回退。

最后更新: