Subtitle Translator

Translate subtitle files between languages with accuracy validation.

Scripts: All scripts are in scripts/ relative to this SKILL.md. CRITICAL: When running any bun scripts/... command, you MUST set the working directory (cwd) to this skill's base directory. Do NOT run from the user's project directory.

Workflow

- [ ] Step 1: Input validation (file exists, format supported)
- [ ] Step 2: Detect source language + confirm target language
- [ ] Step 3: Preprocess (VTT → SRT if needed)
- [ ] Step 4: Terminology scan (extract terms, build session glossary)
- [ ] Step 5: Translate subtitles (batch, with validation)
- [ ] Step 6: Review (optional, check consistency & quality)
- [ ] Step 7: Bilingual merge (optional)
- [ ] Step 8: Output report

Flow

Input → [Step 1: Validate] → File exists, format check
        ↓
[Step 2: Language] → Auto-detect source + confirm target
        ↓
[Step 3: Preprocess] → VTT → SRT convert (if needed)
        ↓
[Step 4: Term Scan] → Extract terms, build session glossary
        ↓
[Step 5: Translate] → Batch translate (20 lines) + count validation
        ↓
[Step 6: Review] → Consistency & quality check (optional)
        ↓
[Step 7: Merge] → Bilingual SRT (if requested)
        ↓
[Step 8: Report] → Output paths + counts

---

Step 1: Input Validation

Goal: Confirm subtitle file exists and format is supported

1. User provides subtitle file path
2. Supported formats: .srt, .vtt, .ass, .ssa
3. Verify file exists and is readable

---

Step 2: Language Detection

Goal: Determine source and target languages

1. Auto-detect source language:

   bun scripts/detect_language.ts "<subtitle_path>"
   

   • From filename (e.g., subtitles_en.srt → en)
   • From content (Chinese characters → zh, Latin → en, etc.)

2. Confirm with user if detection is uncertain

3. Confirm target language:

   • If user already specified → use it
   • Otherwise → ask user

Common language codes: en, zh, ja, ko, fr, de, es

---

Step 3: Preprocess

Goal: Ensure input is in SRT format for translation

If input is VTT format:

bun scripts/convert_vtt_to_srt.ts "<input.vtt>" "<output.srt>"

If input is already SRT → use directly.

---

Step 4: Terminology Scan

Goal: Before translating, scan the entire subtitle file to extract terms and build a session glossary for consistency.

1. Scan all subtitle text: Read through all subtitle entries, identify:

   • Proper nouns (person names, product names, company names)
   • Technical terms and jargon
   • Recurring phrases or expressions
   • Terms with non-obvious translations

2. Build session glossary: For each identified term, decide the translation upfront:

   • Check against the built-in Term Mapping below
   • Check against user-provided custom term mappings (highest priority)
   • For terms not in any glossary, determine the industry-standard translation
   • Record all decisions as a working term table

3. Use session glossary throughout: All batches in Step 5 must follow this glossary. Same term = same translation, no exceptions.

For short subtitle files (< 50 entries), this step can be done mentally while translating the first batch. For longer files, explicitly list the session glossary before starting translation.

Built-in Glossary

Load built-in glossary for the language pair: references/glossary-en-zh.md

Merge priority (highest → lowest): user-provided custom mappings > session glossary (extracted in scan) > built-in glossary

---

Step 5: Translate Subtitles

Goal: Translate all subtitle lines accurately

Output path: <output_dir>/<filename>_<target_lang>.srt

• Example: output/video_zh.srt
• Default output_dir: same directory as input file, under output/ subfolder

Translation Principles

1. Accuracy: Preserve original meaning faithfully — facts, data, and logic must match the original exactly
2. Meaning over words: Translate what the speaker means, not just what the words say. When a literal translation sounds unnatural, restructure freely to express the same meaning in idiomatic target language
3. Fluency: Natural target language word order and expression
4. Conciseness: Conversational tone, no redundancy — subtitles must be brief
5. Figurative language: Interpret metaphors, idioms, and figurative expressions by their intended meaning rather than word-for-word. Replace with natural target-language equivalents that convey the same idea
6. Emotional fidelity: Preserve the emotional connotations of word choices. Words that carry feelings (e.g., "alarming", "fascinating") should evoke the same response in target-language viewers
7. Consistency: Follow the session glossary from Step 4 — same term = same translation throughout the entire file
8. Punctuation: No period (。) at end of subtitle lines for Chinese (zh)

Batch Translation

• Translate 20 subtitle entries per batch
• Maintain SRT structure: preserve index numbers and timestamps exactly
• Only translate the text content lines

Count Validation (MUST execute)

After translation is complete, validate line counts:

grep -c "^[0-9]\+$" <original.srt>
grep -c "^[0-9]\+$" <translated.srt>

• Translated count MUST equal original count
• If mismatch → fix it immediately. NEVER say "only off by one, close enough"
• Re-run validation after fix

---

Step 6: Review (Optional)

Trigger: Automatically for files with 100+ entries. For shorter files, skip unless user requests "review" / "审校" / "检查".

Goal: Post-translation quality check

1. Terminology consistency: Scan the translated file — verify every occurrence of a term from the session glossary uses the same translation. Flag and fix any inconsistencies.

2. Missing translations: Check for any untranslated source-language text left in the output (e.g., a line accidentally skipped or left in English).

3. Subtitle length: For Chinese (zh) target, flag any subtitle line exceeding ~18 characters — these may be too long to read comfortably on screen. Suggest shorter alternatives.

4. Meaning spot-check: Sample 5-10 entries spread across the file, compare with source — verify meaning is preserved and expression is natural.

If issues are found → fix in place and re-run count validation.

---

Step 7: Bilingual Merge (Optional)

Trigger: User requests bilingual subtitles, or asks for both languages in one file.

Output path: <output_dir>/<filename>_bilingual.srt

bun scripts/merge_bilingual_subtitles.ts \
  "<top_subtitle.srt>" \
  "<bottom_subtitle.srt>" \
  "<output_dir>/<filename>_bilingual.srt"

Default order: Source language (original) on top, target language (translated) on bottom. User can specify the order.

---

Step 8: Output Report

Goal: Show results to user

1. Show:

   • Translated subtitle file path
   • Bilingual subtitle file path (if generated)
   • Total subtitle entry count
   • Source → Target language pair

2. Keep all generated files (translated SRT, bilingual SRT)

---

Error Handling

Issue	Solution
Unsupported format (.ass/.ssa)	Inform user, suggest converting to SRT first
Encoding error	Convert to UTF-8 before processing
Count mismatch after translation	Auto-fix and re-validate
Language detection fails	Ask user to specify source language

---

Examples

Basic translation:

User: 把这个英文字幕翻译成中文
→ Detect language (en) → Term scan → Translate → output/video_zh.srt

With bilingual output:

User: Translate to Chinese and make a bilingual version
→ Detect (en) → Term scan → Translate → Merge bilingual → output/video_zh.srt + output/video_bilingual.srt

Specify languages:

User: Translate this Japanese subtitle to English
→ Confirm (ja→en) → Term scan → Translate → output/video_en.srt

VTT input:

User: 翻译这个 VTT 字幕文件
→ Convert VTT→SRT → Detect language → Term scan → Translate → output/video_zh.srt