srt-translator

SRT Subtitle Translation Assistant

Translate SRT subtitle files into a specified language while keeping the timeline, sequence numbers, and format unchanged.

When to use

• The user requests translation of a .srt file
• Need to convert subtitles into other languages
• Batch translate multiple subtitle files
• Translate video subtitles for multilingual publishing

Execution steps

1. Read and parse the SRT file

Use the read tool to read the source file and parse it in the following format:

序号
时间轴 (HH:MM:SS,mmm --> HH:MM:SS,mmm)
字幕文本（可有多行）
空行（分隔条目）

Parsing rules:

• Sequence number line: pure number
• Timeline line: contains --> to separate start and end times
• Text line: subtitle content, may contain [说话人X] markers
• Blank line: indicates the end of one subtitle entry

2. Extract text to be translated

Extract text content from each subtitle entry:

• Skip sequence number lines and timeline lines
• Extract text lines
• Preserve speaker markers (such as [说话人1]), and translate only the actual content after the marker

3. Terminology extraction and management (key step)

Before translation, first extract terminology to ensure terminology consistency throughout the text:

Step 3a: Extract candidate terminology Read all subtitle text and identify possible technical terms, personal names, product names, technical nouns, etc.

Step 3b: Generate glossary Request terminology translations from the LLM:

请从以下字幕内容中提取专业术语、技术名词、人名、产品名等，
并给出{目标语言}的标准译法。格式：原文|译文

字幕内容：
[全部字幕文本]

要求：
1. 技术术语优先采用业界通用译法
2. 品牌名/产品名可选择保留原文或音译
3. 缩写词首次出现时给出全称
4. 歧义项列出所有可能译法并标注推荐
5. **中文中已出现的英文术语**（如 AI、GPU、API 等）：英文字幕中直接沿用，不重复翻译

Step 3c: Save glossary Save the glossary to the project directory, file name:{srt文件名}_glossary_{语言代码}.md

Format example:

# 术语表：test1 → English

| 原文 | 译文 | 备注 |
|------|------|------|
| 大模型 | AI model | |
| 豆包 | Doubao | 产品名，保留原文 |
| 播客 | podcast | |
| AI | AI | 中文中已出现的英文术语，直接沿用 |

Step 3d: User confirms glossary (optional but recommended)

• If there are uncertain translations in the glossary, show them to the user for confirmation
• The user can modify, add, or delete glossary entries
• The confirmed glossary is used for subsequent translation

4. Translate text

Use the LLM to translate the extracted text and inject the glossary to ensure consistency:

Efficient translation strategy (must be followed for large files >100 entries)：

1. Script preprocessing to merge sentences: before translation, use a script to calculate merge groups and reduce the number of translation entries

   # 基于同说话人+间隙<300ms+语义不完整自动合并
   python merge_srt.py video_en.srt _merged_groups.txt
   

   After merging, entries are usually reduced by 40-60%, greatly reducing the translation workload.

2. Batch parallel translation: split the merged entries into 3-4 batches, 40-60 entries per batch, and start subtasks in parallel for translation

   • Each batch task works independently and does not depend on the others
   • After translation is complete, use a script to merge into the final SRT

3. Script handles number conversion: do not manually convert numbers entry by entry during translation; after translation is complete, use merge_srt.py's num_to_chinese() for batch processing

4. Centralized translation, reduce back-and-forth: translate each batch once and write directly, without repeatedly using edit to append

   • ✅ 50 entries per batch → write once
   • ❌ 50 entries per batch → 5 edit appends

Translation Strategy：

• Translate in batches (20-30 entries per batch to avoid exceeding context length)
• Include a glossary with each translation, and also include the source text of the previous and next entries as context
• Keep speaker labels unchanged
• Handle colloquial expressions (podcasts, interviews)
• Technical terms must strictly follow the glossary
• ⚠️ Colloquialism first: Use natural expressions of Chinese netizens, do not translate literally Example:extremely bullish → 涨疯了, not 极度看涨；reversed lower → 反手就跌了
• ⚠️ Non-technical English is not retained: Industry-standard abbreviations such as AI/GPU/ETF/MACD are retained, but ordinary English words ("setup"/"anyway") must be translated
• ⚠️ Word count timing: Control the translated word count according to the subtitle timeline, calculated at normal Chinese speech rate of about 4 characters/second Example: timeline 3 seconds → maximum 12 characters | 5 seconds → maximum 20 characters | 8 seconds → maximum 32 characters If over time, must condense; rather split than let TTS be forced to speed up

Prompt Template：

请将以下字幕翻译成{目标语言}。

【术语表】（必须严格遵循）：
{术语表内容}

【翻译要求】：
1. 保持 [说话人X] 标记不变
2. ⚠️ 口语化优先：用中国网民的日常表达，不要直译。反例："极度看涨"→正例："涨疯了"
3. 术语必须严格使用术语表中的译法
4. ⚠️ 字数控时：按中文语速 4 字/秒计算最大字数。时长3秒→最多12字，5秒→20字，超时精简
5. 同一概念在全文中翻译必须一致
6. ⚠️ 数字转文字：所有数字翻译成中文全文字形式。2%→百分之二，2026年→二零二六年，50,000→五万
7. ⚠️ 语义不截断：如果原文一句话被拆到多条字幕中，合并为一条完整语义
8. ⚠️ 同人不截断：同一说话人、间隙<300ms，合并为一条
9. ⚠️ 非术语英文不留：翻译结果中不能有非术语英文单词。金融术语（如 AI、GPU、ETF、MACD）保留，
   但普通英文词（如 "setup"、"anyway"、"basically"）必须翻译成中文

【字幕列表】：
1. [原文1]
2. [原文2]
...

5. Reconstruct the SRT file

Replace the translated text back into the original positions:

• Sequence number → unchanged
• Timeline → unchanged
• Text → translated content
• Blank line → unchanged

6. Post-processing of subtitles for dubbing (key step)

After translation is complete and before output, performdubbing optimizationprocessing on the subtitles.

Why this step is necessary: Original subtitles are for people to read, and visually they can be understood across lines. But dubbing is for the TTS engine to hear, and each subtitle entry will be cloned independently—if the content of one subtitle entry is half a sentence (such as "...discovered"), TTS will end with the wrong intonation, making the dubbing unnatural.

Step 6a: Identify incomplete entries

Traverse all subtitle entries and mark the following cases:

• Entries whose text does not end with sentence-ending punctuation (。！？…) → semantically incomplete
• Time gap with the next entry < 300ms and the text can connect naturally → same person speaking continuously
• Text contains Arabic numerals (0-9) → needs number-to-text conversion

Step 6b: Merge rules

Condition	Operation
Previous entry incomplete + next entry can connect	Merge into one entry, timeline takes the start of the previous entry → the end of the next entry
2 consecutive incomplete entries	Continue merging downward until sentence-ending punctuation is encountered (merge at most 4 entries)
Gap < 300ms + same semantics	Merge, even if the previous entry has sentence-ending punctuation (the speaker did not pause)

Step 6c: Number-to-text conversion

After merging is complete, replace all Arabic numerals with the full-text form in the target language:

English	Chinese
2%	two percent
5.5%	five point five percent
2026	twenty twenty-six (year) / two thousand and twenty-six (quantity)
50,000	fifty thousand
1.5	one point five
#1 / No.1	first
$100	one hundred dollars
3rd	third

Step 6d: Output the merged SRT

• Renumber (1, 2, 3... consecutively)
• File name:{原文件名}_dub.srt(such as video_zh_dub.srt）
• At the same time, keep the unmerged original SRT (for burning subtitles with subburn)

Step 7: Output files

Step 7: Output Files

• Generate the dubbing-optimized SRT file
• Filename format:原文件名_{语言代码}_dub.srt(e.g. video_zh_dub.srt）
• Encoding: UTF-8 with BOM
• Line endings: keep LF

⚠️ Do not output the original subtitles (the unmerged-sentence version), because the subsequent align-video will cause timestamp drift. The final subtitles used for burning are regenerated by volc-srt in step 11.

Language Codes

Language	Code
Chinese	zh
English	en
Japanese	ja
Korean	ko
French	fr
German	de
Spanish	es
Russian	ru
Portuguese	pt
Italian	it
Arabic	ar

Speaker Marker Handling

Keep markers：

• Original:[说话人1] 欢迎收听
• Translation:[说话人1] Welcome to

Marker format：

• Square bracket format:[说话人X]、[Speaker X]
• Can be automatically detected based on the source language

Colloquial Translation Guide

Common Handling

Chinese source text	Suggested English translation
Let's	let's / we
Hello	hello / hi
ah / uh	uh / um (or omit)
Let's take a look	let's take a look
let's chat	let's talk about
quite...	quite / pretty

Podcast/Interview Style

• Keep the dialogue natural and fluent
• Appropriately omit meaningless filler words
• Keep sentences short (suitable for subtitle reading)

Terminology Management Guide

Why terminology management is needed

In long subtitle files (such as podcasts and courses), the same term may appear dozens of times:

• Without a glossary: Entry 3 is translated as "大语言模型", entry 50 is translated as "大规模语言模型", and entry 120 becomes "LLM" again—inconsistent throughout
• With a glossary: All occurrences are uniformly translated as "large language model (LLM)", professional and consistent

Timing for Terminology Extraction

Automatic extraction: Automatically scan all subtitles before translation and generate a glossary draft User additions: Users can add entries missing from the glossary Later reuse: Multiple subtitle files in the same project can share a glossary

Glossary Location

By default, it is saved to the same directory as the source SRT file:

test/
├── test1.srt              # 源文件
├── test1_en.srt           # 翻译后文件
└── test1_glossary_en.md   # 术语表

Quality Check List

After translation is complete, check:

• Timeline format is correct (HH:MM:SS,mmm --> HH:MM:SS,mmm）
• Sequence numbers are continuous with no omissions
• Blank lines separate each entry
• Speaker markers are preserved
• Terminology consistency: The same term is translated consistently throughout the text
• Text length is appropriate (no more than 40 characters per line)
• Encoding is correct (UTF-8)
• Glossary has been saved (if applicable)

Examples

Example 1: Single-file translation (including terminology management)

Input：test/test1.srt

1
00:00:01,790 --> 00:00:03,950
[说话人1] 欢迎收听豆包 AI 播客节目。

Execution Process：

1. Read subtitles: Extract all 8 subtitle texts
2. Extract terminology：
   • Doubao → Doubao (product name)
   • podcast → podcast
   • large model → AI model
   • AI → AI (English term already appearing in Chinese, use it directly)
3. Generate glossary: save as test1_glossary_en.md
4. Translate subtitles: use the glossary for consistent translation
5. Output file: save as test1_en.srt

Glossary：test/test1_glossary_en.md

# 术语表：test1 → English

| 原文 | 译文 | 备注 |
|------|------|------|
| 豆包 | Doubao | 字节跳动产品名，保留拼音 |
| 播客 | podcast | |
| 大模型 | large language model | 首次出现可写全称 |
| 人工智能 | artificial intelligence (AI) | |
| 技术突破 | breakthrough | |

Output：test/test1_en.srt

1
00:00:01,790 --> 00:00:03,950
[Speaker 1] Welcome to the Doubao AI Podcast.

Example 2: Batch translation

User request: "Translate all srt files in the test directory to English"

Execution steps:

1. Scan all .srt files in the directory
2. Read, translate, and save one by one
3. Output as *_en.srt

Output format

After translation is complete, report to the user:

✅ 翻译完成
📄 源文件: {原路径}
💾 输出文件: {新路径}
📖 术语表: {术语表路径}（如适用）
🎯 目标语言: {语言}
📊 翻译条目: {N} 条
📋 术语数量: {N} 个

Notes

1. Back up the original files: confirm the original files have been backed up before translating
2. Check encoding: ensure the output is UTF-8 to avoid garbled text
3. Line length: subtitle text is recommended to be no more than 40 characters per line
4. Timeline unchanged: translate only the text, never modify the timeline
5. Keep blank lines: there must be a blank line between each subtitle entry
6. Do not use Python scripts to generate translation output: 🚨 Absolutely do not write translated content into SRT files via bash + Python scripts. Reason:
   • Chinese escapes in Python strings are extremely error-prone under Windows PowerShell
   • This leads to many debugging retries and wastes time
   • Correct approach: directly use write or edit tools to write the translated SRT file
   • Even for hundreds of subtitles, directly output in batches using write tools; do not take a detour through Python

Large file translation guide

When there are more than 100 subtitle entries, adopt the following strategy:

1. Write in batches, not one by one: 30-50 entries per batch, append to the target file using write tools
2. Write the glossary first, then translate the main text: immediately after finishing the glossary, save it using write ; do not wait until all translation is complete
3. Use edit tools to append: for subsequent batches, use edit to append new content at the end of the file
4. Prohibited operations：
   • ❌ bash + Python script to generate translations → PowerShell escaping hell
   • ❌ Translating 200+ entries at once without writing in batches → risk of losing progress
   • ❌ Using bash 's echo to write Chinese content → garbled encoding

---

Version: v1.0 Last updated: 2026-05-03 Maintainer: Claude Code