subtitles_translation_workflow v1.0.0

name: "subtitles-translation-workflow" description: "Translate and localize subtitle files (SRT, ASS) without breaking timing: timestamp-preserving translation workflow, line-length and reading-speed (CPS) checks, timing-drift fixes, machine-translation QA passes, and right-to-left language handling. Use when asked to translate subtitles, fix subtitle timing after translation, or QA translated captions."

Subtitles Translation Workflow

Purpose

Translate SRT or ASS subtitle files into another language while keeping the file valid, the timing intact, and the text readable at normal viewing speed. The default mode preserves every timecode exactly and reflows text to fit the existing cues; a separate, explicitly chosen retiming pass handles cases where translation genuinely needs new timings.

Workflow

1. Intake. Read the source file and note format (.srt or .ass), encoding (must be UTF-8), cue count, and the source language's script family (Latin / CJK / RTL). Run the intake check:

bash
   python3 bin/subcheck.py intake source.srt
   

Record any pre-existing problems (overlaps, too-fast cues, broken numbering). Problems inherited from the source are reported, not silently fixed, in the final report.

1. Glossary. Before translating, extract proper nouns, brand names, technical terms, and recurring phrases into a small glossary. These get locked: translated once, identically, everywhere. Machine-translation output gets its names and brands verified against this glossary line by line.

1. Translate in context, cues in order. Translate cue by cue in chronological order, with neighboring cues visible. A thought often spans cues; pronouns, tense, and formality depend on what came before. In ASS files, translate only the text after the final comma of each Dialogue: line. Never touch style tables, override tags ({\b1}, {\i1}, {\pos(x,y)}), karaoke timings, or the \N line-break markers.

1. Reflow text without moving timecodes. After translation, fix every cue for readability: break lines at phrase boundaries (after punctuation, before a conjunction or preposition; never split an article from its noun or a first name from a last name). Prefer a bottom-heavy shape: the longer line goes second. See references/reading-speed-and-timing.md for the line-length and CPS limits.

1. Timing-drift repair (no retiming yet). Translated text often runs 20-30% longer than the source (French, German, Spanish vs English), so cues go too fast. Fix in this order, before cutting any words: (a) extend the cue's end into the following silence, keeping about 2 frames / 80 ms of gap before the next cue and never exceeding the max duration; (b) merge short neighboring cues from the same speaker when the result fits the character and duration limits; (c) only then condense: cut fillers, false starts, and redundancies, keeping meaning, names, and numbers. Never stretch a timecode to fit text. If the words still will not fit after condensation, stop: that is a retiming pass.

1. Optional retiming pass. Only when the user or the report asks for it: re-anchor timecodes to the audio. This is a separate, tracked change. In preserve mode the cue count and every timestamp line must stay byte-identical to the source.

1. Machine-translation QA pass. If the translation came from MT, run references/mt-qa-pass.md in full: a named checklist, not a skim. At minimum: glossary consistency, untranslated source-language leakage, digit/number formats, punctuation direction, and a CPS sweep.

1. RTL handling. If the target language is Arabic, Hebrew, Persian, or Urdu, apply references/rtl-bidi.md: check bidi marks (RLM/LRM) around mixed-direction runs (names, brands, numbers, punctuation), and verify direction behavior on the actual player.

1. Verify. Run the verification and fix every error; work warnings until they stop falling:

bash
   python3 bin/subcheck.py verify source.srt translated.srt
   

Errors: cue-count mismatch, timestamp mismatch, unclosed/missing tags, invalid timecodes, broken numbering. Warnings: over-long lines, CPS violations, cues under 1 second or over 7 seconds, overlaps, gap under 2 frames. A handful of cues will resist (the shortest true phrasing is still over budget). Keep the meaning and note the trade-off in the report: a translation decision, not a defect to hide.

Output Contract

Deliver:

• The translated .srt/.ass file, UTF-8 encoded, named by replacing the source language code with the target (Show.en.srt to Show.it.srt).
• A short QA report: cue count in/out, errors fixed (list), warnings remaining (list, with the ones inherited from the source flagged as inherited), and any translation trade-offs made under step 5 or 9.

Operating Rules

1. Every factual claim in this skill's own numbers comes from a primary source. The limits quoted here are from Netflix's Timed Text Style Guides and the W3C accessibility guidance, cross-checked across independent write-ups. Do not invent tighter or looser limits to make a file pass.
2. Never raise a reading-speed threshold to silence a warning. The warning means the viewer cannot finish reading; the fix is shorter text or better timing.
3. Never delete words to hit a character budget unless the meaning survives. Condensation removes filler, not facts.
4. Preserve-mode check is strict: same cue count, same timestamp lines. If timestamps had to move, the file is a retimed translation and the report says so plainly.
5. Character-per-second thresholds follow the script on screen, not the source language. An English translation of a Chinese video is checked against the English (Latin) limits.
6. No em dashes in generated subtitle text unless the target language's typography genuinely uses them. In English subtitles, use double hyphens or commas instead.