---
name: 字幕双语本地化
description: 将常见字幕文件或粘贴的字幕文本转换为适合视频观看的中英双语字幕。用户只要提到字幕翻译、双语字幕、SRT、VTT、字幕本地化、字幕中英对照、把字幕改成双语、字幕文件翻译等需求，就应主动使用此技能。支持常见字幕格式输入，默认保留原字幕格式与结构，输出字幕文件与纯文本预览版。对于长字幕或高完整性要求场景，也应使用本技能，并配合内置脚本进行解析、分批处理、重建、结构校验、长度风险检查与回归测试，避免漏块、断号、时间轴损坏、输出截断或字幕过长影响观看。
---

# 字幕双语本地化

用于把单语字幕转换为适合视频观看的中英双语字幕，并尽量保证结构稳定、结果完整、适合直接用于视频。

## 适用场景

当用户出现以下意图时，主动使用本技能：
- 翻译字幕文件
- 生成中英双语字幕
- 处理 `.srt`、`.vtt` 等常见字幕文件
- 做字幕本地化
- 将粘贴的字幕文本整理成双语字幕
- 要求保留字幕编号、时间轴、分块顺序
- 强调不能漏字幕、不能截断输出
- 字幕内容较长，需要安全分批再整合
- 强调字幕要适合视频观看、不要太长、不要太满

## 核心目标

接收常见字幕文件，或接收用户直接粘贴的字幕文本；基于上下文理解，将原始字幕转换为适合视频观看的中英双语字幕。

默认规则：
- 输出中英双语字幕
- 英文在上，中文在下
- 中文翻译优先自然、准确、适合字幕观看
- 严格保留原结构，包括：
  - SRT 编号
  - 时间轴
  - WEBVTT 头
  - 原有分块顺序
- 默认输出两份结果：
  - 字幕文件
  - 纯文本预览版

## 可用脚本

本技能附带脚本，用于提高稳定性。需要时先阅读 `references/format-rules.md`。

### `scripts/parse_subtitles.py`
当你需要先把字幕转成结构化数据，再逐块处理、批处理或重建时，使用这个脚本。它适合：
- 将 `.srt` / `.vtt` 解析成 JSON
- 保留 `format`、`header`、`blocks`
- block 中保留 `block_position`、SRT `index` / VTT `cue_id`、`timecode`、`lines`、`raw`、`valid`、`error`
- 为后续翻译、校验和重建提供稳定中间层

如果任务较长、结构要求严格，优先考虑先解析再处理。

### `scripts/rebuild_subtitles.py`
当你已经有结构化 JSON，或已经对字幕块完成逐项修改后，使用这个脚本重建字幕文件。它适合：
- 从 JSON 恢复为 `.srt` 或 `.vtt`
- 按 JSON 中原始格式输出，或使用 `--format` 覆盖输出格式
- 在批处理后重新生成完整字幕文件
- 减少手工拼接造成的结构错误

### `scripts/validate_subtitles.py`
当你已经拿到原字幕和生成后的双语字幕时，使用这个脚本做完整性校验。它适合检查：
- 是否漏块
- 是否断号
- 时间轴是否损坏
- `WEBVTT` 头是否丢失
- 每块是否至少包含英文和中文两行正文
- 支持输出 JSON report，失败返回非 0

该脚本已做过最小兼容修复，可正确处理双语字幕块内部出现空行的场景，避免把一个字幕块误拆成多个 block。

如果校验失败，不要直接把结果当作最终交付。

### `scripts/split_merge_batches.py`
当字幕过长、一次处理有截断风险时，使用这个脚本：
- 先切分长字幕为多个批次
- 生成 `manifest.json`
- 分别处理每个批次
- 再合并为完整文件
- 合并后再校验

如果用户特别强调“不要输出不全”，优先采用这个脚本辅助流程。

### `scripts/length_check.py`
当用户强调字幕要适合视频观看、不要太长、不要过满时，使用这个脚本检查风险。它适合提示：
- 单条英文是否偏长
- 单条中文是否偏长
- 中文字幕阅读速度是否过高
- 是否存在双语两行缺失
- 支持输出 JSON report，失败返回非 0

默认阈值：
- 中文 22 字/块
- 英文 48 字/块
- 中文 8.0 字/秒

长度检查主要用于提醒需要复核和优化的字幕块，不代替上下文翻译判断。

## 输入要求

支持以下输入形式：
- 用户上传字幕文件
- 用户直接粘贴字幕文本

支持的常见字幕格式包括但不限于：
- `.srt`
- `.vtt`
- 其他结构与 SRT/VTT 接近的常见字幕文本

如果输入格式不标准，但仍能识别出字幕块、时间轴与正文，应尽量修复并继续处理；如果无法可靠识别，再明确告诉用户具体问题。

## 输出要求

### 1. 字幕文件输出
- 默认尽量保持原始字幕格式
- 输入是 `.srt`，优先输出 `.srt`
- 输入是 `.vtt`，优先输出 `.vtt`
- 保留原有编号、时间轴、块顺序和头部信息
- 每个字幕块正文改为：
  - 第一行：英文原文
  - 第二行：中文译文

### 2. 纯文本预览版
同时提供纯文本预览，便于用户快速检查。

纯文本预览应按原字幕块顺序展示，并保留时间轴信息，格式可更易读，但不能丢块。

## 处理原则

### 上下文理解优先
翻译前先理解上下文，不要逐词硬译。对于代词、省略、口语、术语、语气和上下句衔接，要结合前后文判断。

### 面向视频观看优化
译文应适合视频字幕，不追求逐字直译。优先满足：
- 自然
- 准确
- 简洁
- 易读
- 节奏合适

### 控制字幕长度
注意单条字幕的可读性，避免中文过长导致观看负担明显增加。

如果原文很长，仍然不得破坏整体字幕结构。可采用以下方式优化：
- 压缩不必要的冗余表达
- 使用更自然、更短的中文说法
- 保持关键信息完整

必要时可在交付前使用 `scripts/length_check.py` 做风险检查，优先处理被标记为过长或阅读速度过高的字幕块。

不要为了缩短而删除实质信息，也不要因为追求完整复述而让字幕明显不适合视频观看。

### 结构保持优先
除非用户明确要求重切字幕，否则不要：
- 合并字幕块
- 拆分字幕块
- 修改时间轴
- 改动编号顺序
- 删除任何字幕块

本技能默认是结构保持型转换，而不是重新制轴。

## 长内容处理策略

当字幕内容很多、整份文件较长时：
- 允许在内部按批次处理，以降低遗漏风险
- 处理长字幕时，优先考虑使用 `scripts/parse_subtitles.py` 建立结构化中间层
- 如有必要，再使用 `scripts/split_merge_batches.py` 切分批次
- 最终必须重新整合为一个完整结果后再交付
- 如经过结构化处理，优先使用 `scripts/rebuild_subtitles.py` 重建最终文件
- 交付前优先使用 `scripts/validate_subtitles.py` 做校验
- 如用户特别在意观看体验，再使用 `scripts/length_check.py` 检查长度风险
- 不要把未整合的半成品直接当最终答案交给用户
- 不要因为输出过长而只给前半部分

交付前必须自检：
- 是否包含全部字幕块
- 起始块和结束块是否齐全
- 编号是否连续（对 SRT）
- 时间轴是否完整保留
- 是否保留 WEBVTT 头（对 VTT）
- 是否存在明显过长、过满、不利于观看的字幕块

如果由于系统限制无法在当前轮次安全输出完整结果，应明确说明风险，并优先采用“内部完成后一次性交付”的方式，而不是静默截断。

## 推荐工作流程

### 普通字幕任务
1. 识别输入类型：文件或粘贴文本
2. 判断字幕格式：SRT、VTT 或其他近似格式
3. 提取完整字幕结构
4. 通读并理解上下文与语气
5. 逐块生成双语字幕：英文在上，中文在下
6. 检查中文长度是否适合视频观看
7. 复核全文件完整性与结构一致性
8. 输出字幕文件与纯文本预览版

### 长字幕或高风险任务
1. 识别格式并保留原始文件
2. 使用 `scripts/parse_subtitles.py` 解析字幕结构
3. 视情况使用 `scripts/split_merge_batches.py split` 切分批次
4. 逐块或逐批完成双语转换
5. 使用 `scripts/split_merge_batches.py merge` 或 `scripts/rebuild_subtitles.py` 重建结果
6. 使用 `scripts/validate_subtitles.py` 校验完整性
7. 视情况使用 `scripts/length_check.py` 检查可读性风险
8. 通过校验后再输出字幕文件与纯文本预览版

### 修改脚本后的推荐回归动作
如果修改了以下任一脚本：
- `scripts/parse_subtitles.py`
- `scripts/rebuild_subtitles.py`
- `scripts/validate_subtitles.py`
- `scripts/split_merge_batches.py`
- `scripts/length_check.py`

优先执行完整回归：

```bash
cd /mnt/user-data/outputs/字幕双语本地化
python tests/run_regression_tests.py --verbose
```

预期行为：
- 运行前清空并重建 `tests/tmp/`
- 所有中间文件与 JSON report 输出到 `tests/tmp/`
- 汇总结果写入 `tests/tmp/summary.json`
- 任一测试失败返回退出码 `1`
- 全部通过返回退出码 `0`

推荐将“先补 fixture，再补回归，再做最小修复”作为默认维护方式，而不是直接扩大脚本主体改动。

## 回归测试覆盖

当前 `tests/run_regression_tests.py` 已覆盖 9 项真实可运行测试：
- `test_parse_rebuild_srt`
- `test_parse_rebuild_vtt`
- `test_split_merge_srt`
- `test_validate_pass_srt`
- `test_validate_fail_missing_cn`
- `test_validate_fail_broken_index`
- `test_validate_fail_missing_webvtt_header`
- `test_length_check_pass`
- `test_length_check_fail`

对应 fixture 包括：
- `tests/fixtures/source_basic.srt`
- `tests/fixtures/bilingual_basic.srt`
- `tests/fixtures/bilingual_missing_cn.srt`
- `tests/fixtures/source_basic.vtt`
- `tests/fixtures/bilingual_basic.vtt`
- `tests/fixtures/source_long.srt`
- `tests/fixtures/bilingual_length_ok.srt`
- `tests/fixtures/bilingual_length_fail.srt`
- `tests/fixtures/bilingual_missing_header.vtt`
- `tests/fixtures/bilingual_broken_index.srt`

这些样本当前已能验证：
- 基础 SRT 双语输出
- WEBVTT 头保留
- 长字幕完整交付
- SRT parse → rebuild 结构不变
- VTT parse → rebuild 保留 `WEBVTT`
- `validate_subtitles.py` 双语两行要求
- `length_check.py` 长度/阅读速度风险
- `split_merge_batches.py` 切分与回拼完整性
- 高可靠推荐流程说明可落到真实测试链路

## 评测覆盖建议

`evals/evals.json` 应至少覆盖以下几类场景：
- 基础 SRT 双语输出
- WEBVTT 头保留
- 长字幕完整交付
- SRT parse → rebuild 结构不变
- VTT parse → rebuild 后 `WEBVTT` 头保留
- validate 检查双语两行缺失
- length_check 标记过长与阅读速度风险
- split → merge 后块数一致、可继续校验
- 完整推荐流程可被模型正确说明

这样可以把评测从“只测翻译结果”扩展到“测脚本辅助工作流是否被正确使用”。

## 质量检查清单

在交付前，检查以下项目：
- 是否漏掉任何字幕块
- 是否保留全部时间轴
- 是否保留原有头部信息
- 是否保持原有块顺序
- 是否为每个字幕块都生成了双语内容
- 是否统一为“英文在上，中文在下”
- 中文是否自然、准确、适合视频观看
- 是否存在过长、拗口或明显机器直译的表达
- 是否存在阅读速度过高的字幕块
- 最终结果是否完整而非截断

## 与用户沟通的默认方式

如果用户没有额外说明，默认按本技能规则直接处理。

若遇到以下情况，再主动补充说明：
- 字幕格式损坏严重
- 文件编码异常导致正文不可读
- 用户要求与默认规则冲突，例如要求改时间轴、改为中文在上、只输出纯文本等

## 输出模板

### 字幕文件
按原格式输出完整字幕内容。

### 纯文本预览版
可使用如下结构：

```text
[字幕块 1]
00:00:01,000 --> 00:00:03,000
English line
中文译文

[字幕块 2]
00:00:03,500 --> 00:00:06,000
English line
中文译文
```

## 示例

### 示例 1
输入：
```srt
1
00:00:01,000 --> 00:00:03,000
This is a good example.
```

输出：
```srt
1
00:00:01,000 --> 00:00:03,000
This is a good example.
这是一个很好的例子。
```

### 示例 2
输入：
```vtt
WEBVTT

00:00:01.000 --> 00:00:03.000
I don't think that's true.
```

输出：
```vtt
WEBVTT

00:00:01.000 --> 00:00:03.000
I don't think that's true.
我不认为那是真的。
```

## 失败规避

不要：
- 只翻译前面一部分字幕
- 因内容太长而静默截断
- 丢失编号或时间轴
- 把整份字幕改写成摘要
- 把双语字幕变成仅中文或仅英文
- 在未获授权时擅自重切时间轴或重组字幕结构

用户真正需要的是：完整、可用、适合视频、结构稳定的中英双语字幕结果。