subtitle-translator

把外语 SRT 字幕翻译为中文。这条流水线之所以分四步,是因为原始转录字幕的"瑕疵"大多源于语音识别模型的局限(听写错、断句错、强行换行),如果直接翻译就把这些瑕疵也翻进中文里了。先纠错,再规范化结构,最后翻译并按字幕规范输出,才能拿到一份干净可用的成品。

整个流程:

1. 热词搜索 + 建工作目录 — 派 subagent (或有 fallback) 把热词背景查清楚,带回干净的"实体清单";同时在原字幕同级建一个工作目录(命名规则见 Step 1)存放本次的中间产物和成品
2. 拼写纠错 — 主代理拿着实体清单,在原始 _jpn.srt 上直接 Edit 改写错的专有名词
3. 结构规范化 — 修正断句错误(双向: 末尾溢出 + 开头错拿)、合并被强行换行的同句;输出到 工作目录下的 *_fixed.srt,不动原文件
4. 翻译 + 规范化输出 — 读 _fixed.srt 翻成中文,写到工作目录下的 *_zh.srt,经过 scripts/postprocess.py 输出最终成品

为什么 Step 2 改原文、Step 3 不改原文: Step 2 改的是局部词(专有名词的正字),错改了人工 diff 也好定位;Step 3 涉及大量句子边界迁移和换行折叠,如果直接 Edit 原文,出问题时几乎没法回滚,所以保留 _jpn.srt 原貌,产物另存为 _fixed.srt。

Step 1: 热词搜索 + 建工作目录

为什么用 subagent (如果可以)

WebSearch 一次会返回大量原文摘要、URL、广告、不相关条目。这些塞进主代理上下文,后面就没空间认真翻字幕了。subagent 做完搜索后只把"干净的实体清单"带回来,主代理省下的上下文用来读字幕和翻译。

工作目录探查

先在当前工作目录里查这两类文件:

• 外语字幕: 带语言后缀的 SRT,如 *_jpn.srt、*_eng.srt、*_kor.srt,或任何 *.srt
• 热词表: 通常叫 热词表.txt、hotwords.txt、vocab.txt,内容可能是"序号+tab+词",也可能是每行一个词

按存在性分情况:

搜索 — 优先派 subagent, 没条件就主代理上

判断当前会话是否有 Agent 工具:

• 有: 派 general-purpose subagent 做搜索,prompt 用下面的模板。subagent 做完只返回"实体清单",搜索过程的噪声留在 subagent 那边。
• 没有 (例如本 skill 正在被一个外层 subagent 调用、嵌套 subagent 不可用、或者用户明确要求主代理跑): 主代理直接 WebSearch,遵循完全一样的"全景式搜索"原则和返回格式,搜完不要把搜索结果摘要塞进上下文,只保留最终的清单。

两条路径输出的"实体清单"在后续 Step 2 里用法完全一样,所以选哪条都不影响下游。

搜索 prompt 模板

(如果是派 subagent,把这段当作 subagent 的 task prompt;如果主代理自己跑,当作自我指令)

你的任务是为字幕翻译做热词背景搜索。最终只返回干净的"关联实体清单",不要返回搜索过程或链接。

工作目录: <当前 cwd>
热词表原文:
<paste 热词表全文>

对每个热词执行以下步骤:
1. 用 WebSearch 工具搜索这个热词
2. 围绕该热词做"全景式扩散搜索":
   - 全称 / 正式名称
   - **该作品的全部声优阵容** — 主役、副役、客串、新人都列出来。字幕里可能出现任意一位声优名,不要只列核心几个。
   - **全部角色 + 对应声优** 的映射列表
   - 关联品牌 / 厂牌 / 子单元 / 组合
   - **具体活动 / 演唱会编号** (如 1st LIVE / 2nd LIVE / ... / 8th LIVE / 各 Tour 名 / 周年纪念活动名) — 字幕里常出现 "X th Live" 这种听写,实体清单必须能让主代理识别具体是哪场
   - 单曲名 / 专辑名 / 衍生作品名 / 周边企划名
3. 记录每个实体的"正字写法" — 用它的原文写法 (日文/英文/汉字, 视来源而定), 不要翻译

举例: 热词 "シャニマス" 应当扩散出:
- 全称 "アイドルマスター シャイニーカラーズ"
- 全部声优阵容: 关根瞳 / 田中摩美々 (CV: 菅沼千紗) / 大崎甘奈 / 涼本秋穂 / 凪原涼菜 / ... 等所有 PRODUCE 系列声优
- 全部活动: 1st LIVE 〜 8th LIVE 各场名称、SHHis 单独 Live、Brilliant Wing 系列等
- 品牌: L'Antica / illumination STARS / アルストロメリア / 放課後クライマックスガールズ / ストレイライト / ノクチル / SHHis / コメティック

返回格式 (Markdown):

## 热词: <热词原文>
- 全称: <如有, 否则留空>
- 声优 / 人物清单 (全): <逗号分隔, 写正字>
- 角色 → 声优映射: <列表>
- 关联品牌 / 团体: <列表>
- 演唱会 / 活动编号: <列表, 含序号>
- 衍生作品 / 其他重要实体: <列表>

如果某热词的某项搜不到, 该项留空。不要瞎编。

把 subagent (或主代理自身) 整理出的实体清单完整记下来,带入下一步。

建工作目录

搜索完成后,在原始字幕所在目录下新建一个工作目录,用来存放本次处理过程中产生的所有新文件(_fixed.srt、_zh.srt),避免污染用户的原工作目录。

命名规则: <主名>_work/,其中"主名"是字幕文件名去掉语言后缀和扩展名:

• chisa84-cut01_jpn.srt → 主名 chisa84-cut01 → 目录 chisa84-cut01_work/
• interview_eng.srt → 主名 interview → 目录 interview_work/
• xxx.srt (无语言后缀) → 主名 xxx → 目录 xxx_work/

沿用已有目录: 如果 <主名>_work/ 已经存在(说明之前的会话处理过同一字幕但没跑完),沿用该目录,不要重建或清空。可以审视目录里已有的中间产物(_fixed.srt 是否已生成、_zh.srt 是否半成品)决定从哪一步续上。但如果不确定已有产物是否合规,重做覆盖也行。

用 Bash 创建:

mkdir -p "<原字幕所在目录>/<主名>_work"

Step 2: 拼写纠错

把原始外语 SRT 全文读进来,带着上一步的实体清单逐一核对人名、作品名、活动名。

操作原则: 对照清单核对每一个人名 / 专有名词,而不是只挑"明显错的"

• 字幕里出现的每个疑似人名/作品名/品牌/活动名,都要在实体清单里查一下。如果清单里有发音相近/写法相近但不完全一致的项,优先采用清单里的正字。
• 转录模型对人名特别容易出错。比如清单里的"涼本秋穂"在字幕里可能被听写成"鈴本青葉"(鈴=涼 发音不同但形近,青葉=秋穂 季节性误识)、或"涼本あきほ"(汉字落了)。这两种都要改成 涼本秋穂。
• 活动名也要核对。比如清单里有"シャニマス 8th LIVE",字幕里出现"シャニマスの Ace Live"几乎确定是 "8th LIVE" 听错。"Ace" 在英文里没意义、シャニマス 也没有 Ace Live,所以可以放心改。

不要乱改普通词: 口语化表达、犹豫语气词 ("えーと"、"あの")、ASR 的 disfluency 保留 — 它们能反映说话节奏,对后续翻译有用。

判断启发式:

• 这个词在清单里有"发音 / 写法相似但不同"的对应词 → 改
• 这个词的出现语境符合该实体的语境(讨论角色的句子里出现的疑似人名)→ 改
• 实在判断不了正字, 但显然是误识: 在字幕里加 <?> 标注,翻译时按上下文处理

操作: 直接用 Edit 工具修改原始 SRT,把识别错误的写法替换为正字。可以一次性 replace_all,也可以逐条 Edit。

Step 3: 字幕结构规范化

原始转录字幕通常有两类结构问题,需要在翻译前修掉。这一步不直接 Edit 原始 `_jpn.srt`,而是基于原始字幕的内容,生成一份新文件放到工作目录:

Step 3 输出文件命名: 在原始字幕文件名的 .srt 之前插入 _fixed。

• chisa84-cut01_jpn.srt → <工作目录>/chisa84-cut01_jpn_fixed.srt
• interview_eng.srt → <工作目录>/interview_eng_fixed.srt
• xxx.srt (无语言后缀) → <工作目录>/xxx_fixed.srt

这样原文保留作 diff 参考,出问题可回滚。

问题 A: 相邻字幕被错切 (双向)

转录模型分条时常常会把句子边界切错,有两种相反的方向,都要识别和处理:

方向 A.1: 末尾溢出 — 某条字幕末尾混入了下一句的开头若干字。

识别特征:

• 该条结尾出现引号开头符 「 / " / ( 等,本条没有对应闭合
• 句末是"还没说完"的状态: 句子刚起头就被截断
• 末尾的几个字和本条前文脱节,但能接到下一条开头

例:

8
00:00:55,560 --> 00:01:00,920
「もうすぐ100回じゃない？」みたいな。「え、今回84。

9
00:01:00,920 --> 00:01:06,448
え、次回85。え、何か100回...

处理: 把 「え、今回84。 从第 8 条末尾剪到第 9 条开头。

方向 A.2: 开头错拿 — 某条字幕开头错拿了上一条字幕末尾的若干字。

识别特征:

• 该条开头有一两个字与本条主体语义脱节,但能接到上一条结尾
• 上一条的句子读起来"少了点东西、停得突兀",而下一条的开头那几个字正好能补上
• 常见模式: 上条句号还没出现就被截,本条开头是上句的尾音

例:

22
00:01:20,000 --> 00:01:23,500
そういう話を聞いて、私はとてもびっくりし

23
00:01:23,500 --> 00:01:26,200
ました。本当にすごいことだと思います。

处理: 把第 23 条开头的 ました。 剪到第 22 条末尾,使第 22 条变成 ... とてもびっくりしました。,第 23 条变成 本当にすごいことだと思います。。

两种方向都要扫: 不要只看末尾溢出而忽略开头错拿,反之亦然。读字幕时如果一条结尾感觉"没说完",检查下一条开头是不是它的延续(方向 A.1);如果一条开头感觉"突兀",检查它是不是该并到上一条(方向 A.2)。

时间码原则: 保留两条字幕原来的时间区段,只调整文字归属。如果迁移过去后某条明显变得过短/过长,可以小幅微调时间码,但通常不必。

问题 B: 同条字幕内被强行换行

转录模型有单行字数上限,长句被分成两行写在同一条字幕里。这种换行没有任何语义,纯粹是字符长度限制。

例:

3
00:00:31,300 --> 00:00:36,000
[拍手]はい、7歳です。
何か違和感ありますね。

第二行不是新句,而是同一句的续写。处理: 把同一条字幕内的换行合并 — 日文/英文之间用空格,合并后写成单行:

3
00:00:31,300 --> 00:00:36,000
[拍手]はい、7歳です。何か違和感ありますね。

怎么干

1. 把 Step 2 已经改完专有名词的 _jpn.srt 整文件读进来
2. 在内存里逐条扫描,识别方向 A.1 / A.2 / 问题 B,做相应迁移
3. 用 Write 工具把处理后的内容写到 <工作目录>/<原文件名>_fixed.srt(按上面的命名规则),不要 Edit 原文件
4. (可选) 抽几条核对修正前后,确认没改坏

如果字幕很长(几百条),也可以分批处理 — 但最终输出一份完整 _fixed.srt。

Step 4: 翻译并按规范输出

读 Step 3 生成的 _fixed.srt,逐条翻译为中文,保存为中文字幕到工作目录。

Step 4 输出文件命名: 把原文件名的语言后缀(如 _jpn / _eng)替换为 _zh;如果原文件没有语言后缀,直接在主名后加 _zh。

• chisa84-cut01_jpn.srt → <工作目录>/chisa84-cut01_zh.srt
• interview_eng.srt → <工作目录>/interview_zh.srt
• xxx.srt (无语言后缀) → <工作目录>/xxx_zh.srt

翻译风格

• 中文要自然,不要直译。日文敬语、终助词 (です/ます/ね/よ) 通常省略或改为合适的中文语气。
• 人名、作品名、品牌名以 Step 1 实体清单的正字为准。不要把日文/英文专有名词译成中文,除非用户明确要求。例: "シャニマス" 保留原文或写作 "シャイニーカラーズ",不要写"闪耀色彩"(除非用户要求中文化)。
• 昵称展开 — 首次全名,后续可以用昵称: 日文人名的口语昵称(如 "にごさん"、"ちゃんりお"、"えりち"、"姓 + ちゃん" 之类的)中文观众通常不认识。每个昵称在字幕里第一次出现时,写完整的本人名字(配合 Step 1 实体清单确认昵称指代的全名);后续条目里再次出现的同一个昵称,可以用昵称简称。例: 节目里说 "にごさん",首次翻译为 "仁後真耶子老师",后续 "にご老师" 或 "仁後老师" 都可以。
• 不要保留转录的方括号舞台提示: 转录模型常会在字幕里插入 [拍手] [笑い] [音楽] [BGM] 之类的方括号注释,这些不是说话内容,不出现在最终中文字幕里。翻译时直接省略;如果一条字幕除了方括号注释就没别的内容(整条都是 [拍手]),翻译时也整条略过即可。postprocess.py 会兜底再扫一遍清掉残余的 [xxx],并把变空的条目删掉。
• 无意义语气词不单独成条: 单独占一整条的"えーと"、"あの"、"うーん"、"うん"、"あ"、"えっ"、"へえ" 之类的纯犹豫词/惊叹词,整条略去(写空字符串,postprocess 会删掉空条)。但如果语气词出现在句首并接续了实际内容(如 "あ、そうそう、思い出した"、"えーと、それは違いますね"),整条保留,语气词作为口语风味译出(如"啊 对对 我想起来了"、"嗯 那个不对"等)。判断准则: 这条字幕去掉语气词后还剩多少内容? 几乎不剩 → 整条略去; 还剩一个完整句子 → 保留。
• 一条字幕的翻译尽量在一行内完成。即使原文是被换行的,翻译也只写一行。

翻译时正常带标点

翻译时按中文习惯加标点 (例: "你好,大家晚上好。"),不必担心末尾标点和中间标点 — 这些都由后处理脚本统一规范化。这样翻译更顺手,可读性也更好。

调用规范化脚本

翻译完成后,用 scripts/postprocess.py 做最后的规范化:

python "<skill_dir>/scripts/postprocess.py" <input.srt> <output.srt>

<skill_dir> 是本 skill 的安装目录,根据当前 SKILL.md 所在目录反推即可。

允许 input 和 output 是同一路径,即"原地规范化"。脚本会做以下事:

1. 删除方括号注释: 把 [拍手] [笑] [音楽] 等 [...] 形式的转录标记一律删掉(只处理半角 [],中文 【】 不动)
2. 每条字幕末尾如果有单个标点 (。 , ， ? ？ ! ！ 、 ; ； : ：等),去掉
3. 每条字幕中间的单个标点替换为空格;多个空格折叠为一个
4. 成对符号 《》 「」 "" '' () 等保留
5. 相邻两条字幕间隔在 (0, 300ms) 区间内的,把前一条的结束时间设为后一条的开始时间(时间无缝)
6. 同条字幕内的换行折叠为单行
7. 处理后变为空字符串的条目整条删除(并重新编号)

最终交付

工作目录下的 *_zh.srt 即是成品。原始 _jpn.srt 留在原位未动,_fixed.srt 作为中间产物保留在工作目录里供日后参考或回滚。除非用户明确说"清理中间文件",否则不要删除任何中间产物。

端到端示例 (在 E:\Download\菅沼千纱84\ 目录)

初始状态:

E:/Download/菅沼千纱84/
├── chisa84-cut01_jpn.srt   ← 原始转录字幕
└── 热词表.txt

执行流程:

1. Step 1: 读 热词表.txt → 派 subagent (或主代理自己) 围绕热词搜索,拿到 "L'Antica / 田中摩美々 / 涼本秋穂 / ... / 1st-8th LIVE / ..." 实体清单。然后 mkdir -p chisa84-cut01_work。

1. Step 2: 读 chisa84-cut01_jpn.srt,在原文件上直接 Edit 修正写错的专有名词(如 ランティカ → L'Antica、鈴本青葉 → 涼本秋穂)。

1. Step 3: 扫描修正后的 _jpn.srt,处理双向切分错误和换行问题,把结果用 Write 写入 chisa84-cut01_work/chisa84-cut01_jpn_fixed.srt(不动原文件)。

1. Step 4: 读 _fixed.srt,翻译为中文写入 chisa84-cut01_work/chisa84-cut01_zh.srt,然后:

   python "<skill_dir>/scripts/postprocess.py" \
     "E:/Download/菅沼千纱84/chisa84-cut01_work/chisa84-cut01_zh.srt" \
     "E:/Download/菅沼千纱84/chisa84-cut01_work/chisa84-cut01_zh.srt"

最终目录:

E:/Download/菅沼千纱84/
├── chisa84-cut01_jpn.srt              ← 原始 (Step 2 已做专有名词修正)
├── 热词表.txt
└── chisa84-cut01_work/
    ├── chisa84-cut01_jpn_fixed.srt    ← Step 3 输出 (结构规范化后的日语)
    └── chisa84-cut01_zh.srt           ← Step 4 最终成品 (规范化后的中文)

把 chisa84-cut01_work/chisa84-cut01_zh.srt 交给用户。

一些边界情况

• 热词表为空文件: 按"只有字幕"处理 — 询问用户提几个热词
• 字幕里没有专有名词: 实体清单可能用不上,直接进入 Step 3
• 字幕过长 (> 1000 条): 可以分批读取(Read 配合 offset/limit),但翻译和写入仍按完整 SRT 处理
• 多个外语字幕同时存在: 询问用户先处理哪个,一次只处理一个
• 用户在对话中粘了字幕内容而不是文件: 先存到临时 .srt 文件再走流程,最后输出文件交回

文件结构

subtitle-translator/
├── SKILL.md           本文件
├── scripts/
│   └── postprocess.py 规范化输出(去末尾标点 / 中间标点替换为空格 / 时间无缝)
└── evals/
    └── evals.json     测试用例