git:20260312.203291a to git:20260327.38c81a4

---

name: daftai-subtitle-translator

description: >

Translate subtitle files (SRT/VTT) between languages. Auto-detect source language,

batch translate with count validation, optional bilingual merge output.

Use when user asks to "translate subtitles", "翻译字幕", "subtitle translation",

or needs subtitles converted to another language.

---

# Subtitle Translator

Translate subtitle files between languages with accuracy validation.

> **Scripts**: All scripts are in `scripts/` relative to this SKILL.md.

## 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:

```bash

```

- 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:

```bash

```

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](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:

```bash

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`

```bash

"<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

```