Cerlancism/chatgpt-subtitle-translator

Efficient translation tool based on ChatGPT or any OpenAI compatible LLM chat completion API

ChatGPT API SRT Subtitle Translator

What it is – A Node‑JS utility that calls the OpenAI ChatGPT (or compatible) API to translate subtitle files (SRT) or plain text line‑by‑line. It is built to keep the one‑to‑one correspondence between subtitle lines and translations while minimizing token waste.

Why it matters – Subtitles are often large collections of short lines with timestamps. Sending each line as a separate request would explode token usage and hit rate limits. This tool strips the SRT overhead, batches lines intelligently, and can use OpenAI’s structured output and prompt caching features to get compact, deterministic translations.

Core features (as described in the README)

Web UI + CLI – a browser‑based interface and a command‑line program (cli/translator.mjs).
Structured output – JSON‑array, object, or timestamp‑aware formats that force the model to return exactly the translated lines.
Prompt caching support – optional inclusion of recent translation history (--context) to reuse cached prompt fragments.
Batch‑wise line processing – groups many subtitle lines into a single request, reducing per‑line token overhead.
OpenAI moderation check – can pre‑filter inputs that the model would refuse (--use-moderator).
Streaming progress – live terminal feedback while the model streams its response.
Rate‑limit handling – respects OpenAI RPM limits and can resume interrupted jobs.
Agent mode – a multi‑pass workflow that first creates an overview of the file, plans a refined translation instruction, then translates; useful for long or complex subtitles.
Works with any OpenAI‑compatible endpoint – e.g., local Ollama servers.

Quick start (from the README)

# clone and install
git clone https://github.com/Cerlancism/chatgpt-subtitle-translator
cd chatgpt-subtitle-translator
npm install
chmod +x cli/translator.mjs

# set up API key
cp .env.example .env   # then edit .env and paste your OpenAI key

Translate a file

cli/translator.mjs --input mymovie.srt --from Japanese --to English

The tool writes a new *.srt file with the translated text.

One‑off plain‑text translation

cli/translator.mjs --plain-text "你好"

Outputs Hello.

How it works under the hood

Strip SRT metadata – indices and timestamps are removed (or compacted in timestamp mode) before sending to the model.
Batch creation – lines are grouped according to --batch-sizes or an automatic size derived from the --context token budget.
Prompt construction – a minimal system instruction like Translate to English (≈3 tokens) plus a JSON payload containing the batch lines.
Model call – the request can use structured output (json_schema) so the response is guaranteed to be an array/object of translations.
Re‑assembly – the returned translations are re‑inserted into the original SRT format, preserving timestamps (or merging entries when using the timestamp mode).
Retry logic – if the model returns a different line count, the batch size is reduced and the request retried, avoiding wasted tokens.

Notable options (selected)

-r, --structured <mode> – choose array (default), object, timestamp, agent, or none.
-c, --context <tokens> – how many tokens of prior translation history to include for prompt‑caching.
-b, --batch-sizes <sizes> – explicit list of batch sizes, e.g. 100,50,20.
--use-moderator – run the OpenAI moderation endpoint before sending a batch.
-m, --model <model> – default gpt-4o-mini; any model supported by the endpoint can be used.
-t, --temperature <value> – set to 0 for deterministic translation.
--no-prefix-number / --no-line-matching – relax strict line‑to‑line enforcement.

Limitations & considerations (from the README)

The tool relies on the OpenAI API (or compatible service) – you need a valid API key and will incur token costs.
Deterministic output is encouraged by setting temperature=0, but the model may still vary, especially for ambiguous text.
Structured output modes require the model to understand the supplied JSON schema; older or non‑ChatGPT models may not support it.
In timestamp mode the output line count may differ from the input (entries can be merged), so progress‑resume is disabled.
Large subtitle files may trigger multiple retries if batch sizes are too aggressive for the model’s context window.

Who might use it

Content creators who need quick, high‑quality translations of movie or video subtitles without paying for a dedicated translation service.
Developers building pipelines that ingest subtitles and want a programmable, API‑driven translation step.
Researchers experimenting with LLM‑based translation quality on line‑structured data.