Cerlancism/chatgpt-subtitle-translator

ChatGPT API SRT Subtitle Translator

What it is – A Node‑JS utility that calls the OpenAI ChatGPT (or any OpenAI‑compatible) API to translate subtitle files (SRT) or plain text. It is built to keep a strict one‑to‑one line correspondence so the timing of subtitles stays intact.

Why it matters – Translating subtitles with a large language model can be expensive because each line carries SRT overhead (indices, timestamps). This tool strips that overhead, batches lines intelligently, and optionally uses OpenAI’s structured output and prompt caching features to minimise token usage while preserving line order.

Key features

• Web UI (hosted at https://cerlancism.github.io/chatgpt-subtitle‑translator) and a full‑featured CLI.
• Supports OpenAI‑structured responses (array, object, timestamp, agent, none).
• Prompt‑caching support via --context to reuse translation history.
• Works with any OpenAI‑compatible endpoint (e.g., local Ollama).
• Line‑based batching to stay under model token limits and reduce waste.
• Optional moderation check to avoid sending disallowed content.
• Streaming progress output, RPM rate‑limit handling, and resumable CLI runs.
• “Agent mode” that performs a multi‑pass workflow: language detection → planning summaries → refined translation instruction → final translation.

How it works

1. Pre‑processing – SRT indices and timestamps are stripped or compacted (Toon format) so only the raw text is sent.
2. Batching – Lines are grouped into JSON arrays (or other schemas) that fit within a token budget. The default system prompt is just Translate to <target> (≈3 tokens).
3. API call – The batch is sent to the ChatGPT model (default gpt‑4o‑mini). Structured output forces the model to return a matching JSON structure, guaranteeing line‑by‑line correspondence.
4. Post‑processing – The JSON response is re‑assembled into an SRT file, reinserting the original timestamps and indices.
5. Agent mode (optional) – Runs a quick scan to infer source language, generate a content overview, and produce a refined instruction before the actual translation pass.

Typical usage

# Translate a Japanese SRT to English (CLI)
cli/translator.mjs --input subtitles.srt --from Japanese --to English

# One‑off plain‑text translation
cli/translator.mjs --plain-text "你好" --to English

# Use structured output as an object
cli/translator.mjs -r object -i subtitles.srt -o out.srt

Setup – Requires Node ≥ 20. After cloning, run npm install, copy .env.example to .env, add your OpenAI (or compatible) API key, and make the CLI script executable.

Who it’s for – Anyone who needs to translate subtitle files quickly without paying for unnecessary tokens, from hobbyist video editors to developers building larger media‑localisation pipelines.