AI agent skill · by @JimLiu

Translate Subtitles

用户要把视频的转写或字幕翻译成另一种语言、做双语字幕，或更新原文改动后过期的译文时用：逐句翻译写成视频里的译文文档，再放到画面上、按需导出。有媒体时「翻译」默认指字幕翻译。不用于翻译与视频无关的文章、文档或一段纯文本；对话里没有视频或字幕、又看不出指的是什么时先问一次。

Archived 2026-10-23 · Source updated 2026-10-12. Check the original repository for the latest version.

SKILL.md instructions

# 翻译字幕

观众是在说话人还在说的时候读字幕的：一行很窄，停留两三秒，读完就换下一行。所以成品是字幕，不是散文。你写每句的整句译文；放到画面上时（captions_create）BaoCut 按句把译文对上原文那一句的时间，再按宽度切成字幕条。句子的边界要和原文一一对应，句内的语序要让切开的每一段大致对得上那时说的话，字要少到两三秒读得完。

最容易做坏的样子：译得像一篇好文章。把两句并成一句、把一句拆成两句、为了通顺把后半句挪到前面、把原文的口语写成书面语、每句都比原文长一截。这样的译文单独读很好，放到画面上就对不上声音，观众读到一半字幕已经换了。

用户明确只要翻译一个字幕文件、没有视频时也可以用，做法见最后的「用户明确只要字幕文件时」一节。

## 1. 先确认

- **目标语言**：用 BCP 47 标签（如 `zh-Hans`、`en`、`ja`）。用户没说要译成什么时问一次。原文语言取转写文档的 language。
- **哪份转写**：videos_inspect 列出的文档里 kind 为 speech 的那份；有几份时按来源素材（sourceAssetId）对上用户说的那段，对不上就问。
- **转写润色过没有**：没有润色过（错字、术语、标点都还是识别出来的样子）时，先按 `polish-transcript` 的做法润色再翻译。润色会改分句与句子指纹：先润色、写回，再读句子来翻译；已有译文的视频润色之后，多数句子要重译。先翻译再润色等于做两遍。
- **已有译文**：已经有同一目标语言、sourceDocumentId 指向这份转写的译文（kind translation）时，在它上面改（同一个 documentId），不新建第二份；用户明确要另起一份时才新建。

## 2. 通读，定下译法

用 documents_read 读转写，translateTo 给目标语言：BaoCut 据此在视频卡与字幕面板显示「正在翻译」，写入这门语言的译文时结束。它带的 translationBasis 给出切好的句子。动笔前先通读全文，定下这几件事，翻译时全文照它们。它们不进成品：

- **内容概要**：一两句话说清这个视频讲什么。听岔的词、含糊的指代，都要靠它判断。
- **术语**：认出原文里的术语（转写可能把它们拼错，留意同一个术语的几种错写），每个术语全文只用一种译法。
- **专名**：人名、产品名、机构名保留并全文一致。
- **用户的术语表**：用户点名的译法是硬性要求，逐字照用：不变形、不改拼写、不增减空格、不翻译、不省略；用户只说「最好这样译」的是偏好，保持一致，但可以随上下文让步。每个术语只有一种译法。
- **用户的要求**：语气、风格等明确要求的优先级最高，但不违反用户点名的术语译法，也不违反下面的成品规则。

## 3. 逐句翻译的规则

- 每句翻译一次：不合并、不拆分、不漏、不调序，不把一句挪到别的段落。前后句只是理解上下文用的。
- 先理解整句，再按目标语言自己地道的语序，忠实而自然地翻译。之后的对时会把自然的整句映射到时间上；不要为了跟着原文的分句顺序写出生硬的句子。
- 同样自然的几种译法里，选分句顺序**跟着原文**的那一种（同声传译的做法）：字幕行按原文的语音对时，展开顺序与原文一致的译文，切出来的每一行和正在听到的意思对得上。只在目标语言确实需要时才调序。
- 长度是正确性的一部分，不是风格问题：意思一样、字更少的译文是更好的译文。先删口头填充、多余的连接词、重复的主语和铺垫；两种同样忠实的说法选短的。
- 长度永远排在意思后面。不为了变短删掉必要的意思、否定、限定、数字、名字、语气或语体：这句确实需要那么长，就用那么长。
- 保留每一个明确的因果、转折、条件与结果关系（因为、但是、如果、所以这一类）以及它们管着的内容，哪怕因此变长。切行可以拆开一句完整的译文，但补不回漏掉的分句。
- 每句只给**一种**译法：不写斜杠分隔或括号里的备选。斜杠只在逐字照抄的术语里出现（例如 `/compact` 这样的命令，不论它来自原文还是用户的术语表）。
- 术语全文一致。
- 遵守目标语言自己的空格习惯：中文、日文的字与字之间不加空格；韩文按词分写，助词、量词贴着前面的词或数字。
- 句子里不加换行或分段标记；只输出译文本身，不带注释、引号或原文。

对比一下（英译中，只是示意）：

原文：`So what we ended up doing, and this took us a while to figure out, was to let the model review first.`

不好：`我们花了好一阵子才想明白，最后决定让模型先审一遍。`（把后半句挪到了前面：观众听到 "what we ended up doing" 时，字幕上出现的却是「花了好一阵子」）

好：`我们最后的做法，花了好一阵子才想明白，就是让模型先审一遍。`（展开顺序跟着原文，切成两三行后每一行都对得上当时在说的话）

### 目标是简体中文时另加

这几条是固定要求，优先于自己定下的风格：

- 用地道的简体中文；原文语序读着像翻译腔时不照搬。
- 用中文标点。两个汉字之间不加空格，标识符内部不加空格。
- 汉字与相邻的拉丁字母之间一律加一个半角空格：拉丁单词、标识符、模型名，以及连同前导短横线的命令行参数。写「35% KV 缓存」「通过 --speculative-model 指定」，不写「35%KV缓存」「通过--speculative-model指定」。阿拉伯数字或百分数与相邻的拉丁单词之间同样加一个空格。这是硬性要求。
- 省略号用「……」，连串重复的问号、叹号收成一个，普通的四位数不加千位逗号。
- 代码、标识符、网址、模型名、产品名和用户点名的术语译法逐字保留：标识符自己的字符不动，与汉字相邻时照样加那一个空格。

## 4. 写回视频

- 照 documents_read 说明里的写法，用 documents_put 写入完整的译文：新建时给 kind `translation`、language 为目标语言、sourceDocument 为转写的 documentId；更新已有的译文时给 document。每句一个单元，sourceBasis 用这次读到的 translationBasis，每个单元的对齐信息（对应原文哪一句、哪些词）也照说明填，不省略、不自己发明字段。一次 documents_put 写完整份。
- **只重译变了的句子**（转写改过、剪过之后，或用户说译文过期了）：重新 documents_read 转写（同样给 translateTo）拿最新的 translationBasis，再读已有的译文。句子 id 与 fingerprint 都和已有单元对得上的，原样保留那一单元；对不上的和新出现的重新翻译；转写里已经没有的句子不再写。sourceBasis 换成新的。用户要求整份重译时才全部重来：没变的句子重译一遍，只会让用户已经看过、改过的译文又变样。
- 写之前转写又被改过（版本冲突或读到的已不是当前版本）时，重新读，按新的句子来。

## 5. 交付

- 说明：目标语言；译了多少句（只重译时说保留了多少、重译了多少）；照用了哪些术语；哪些句子拿不准、为什么。
- 放到画面上：用 captions_create 建字幕层。双语给译文文档并带 `bilingual: true`；只要译文给译文文档。同一份文档每调用一次多一层，先 videos_inspect 看是不是已经建过。
- 用户要字幕文件时用 export（kind `subtitles`）：双语给 `bilingual: true`（主文档是转写，副文档是译文，每句一条）；只要译文给 language，要求画面上已有这种语言的字幕层（先 captions_create）；一行的宽度用 maxCharsPerLine。等 jobs_inspect 到 completed，把 outputs 里的 path 告诉用户。

## 6. 要避免的

- 不要合并、拆分、漏译句子，不要把后半句挪到前面。
- 不要为了通顺把口语译成书面语，也不要每句都比原文长。
- 不要为了短删掉否定、限定、数字、名字和因果转折。
- 不要给备选译法，不要在句内换行，不要带注释或原文。
- 不要在润色之前翻译；不要在已有译文时新建第二份；不要整份重译没变的句子。

## 7. 自查

- 每句都译了，没有合并、拆分、漏译或多出来的句子。
- 术语和专名全文一致；用户点名的译法逐字出现在对应的句子里。
- 否定、数字、限定和因果转折都在；没有为了短删掉意思。
- 随便挑几句长的，想象切成两三行：每一行和那时说的话对得上吗？
- 没有备选译法、没有句内换行、没有注释。
- 目标语言的空格与标点习惯对；简体中文的中西文空格对。

## 8. 用户明确只要字幕文件时

这是例外：只有用户明确说只要一个字幕文件、不要视频或项目时才这样做；否则按上面的做法在视频里翻译。

- 从链接取：transcribe 给 url 并带 `noVideo: true`（或 download 不给 video、newVideo 与 project，带 `transcribe: true`），只下载并在下载目录里生成 TXT 与 SRT 文稿。本机媒体文件用 transcribe 给 file 并带 `noVideo: true`。jobs_inspect 到 completed 时 outputs 里有它们的 path，直接读；读不到时用 artifacts_save 存进工作目录再读。用户给的是现成的字幕文件时直接读它。
- 目标语言（第 1 节）、通读定译法（第 2 节）与逐句的规则（第 3 节）照样适用；这条路没有视频里的转写可以润色，原文的识别错误在译文里按上下文译对。
- 每条字幕翻译一次，保留序号与时间码，不合并、不拆分字幕条。
- 一句话跨了几条字幕时，按整句理解，再按「跟着原文顺序」的规则，让每一条的译文对应那一条时间里说的内容。
- 写成工作目录里的新文件，文件名在原名后加目标语言标签（如 `<原名>.<目标语言>.srt`），再用 downloads_save 放进下载目录，把它返回的 path 告诉用户。