trxsrt

trxsrt

A free command-line tool for translating SRT subtitle files using Google Translate and DeepLX. No API key required. Supports 70+ languages.

🦞 OpenClaw-ready — OpenClaw and AI CLI tools like Claude Code, Codex CLI, and Gemini CLI can learn it as a skill and use it whenever you ask.

Table of Contents

• Prerequisites
• Usage
  • Arguments
  • Examples
  • Output Files
  • Progress Display
• Use with AI CLI Tools
• Supported Languages
• How It Works
• CAPTCHA Recovery
• Error Handling
• Notes

Prerequisites

• Node.js >= 20.9.0

Usage

npx trxsrt <file.srt> -f <language> -t <language>
npx trxsrt <file.srt> -f <language> --all-languages

Arguments

Argument	Short	Description
<file>		SRT file path (required, must be .srt)
--from <language>	-f	Source language — name or code (required)
--to <language>	-t	Target language — name or code (required unless --all-languages)
--all-languages	-a	Translate to all supported languages (excludes source)
--concurrency <n>	-c	Max concurrent API requests (default: 10)
--output <dir>	-o	Output directory (default: same directory as input file)
--cookie <cookie>		Google abuse exemption cookie (GOOGLE_ABUSE_EXEMPTION=...)

Examples

Translate to Greek using language name:

npx trxsrt movie.srt -f english -t greek

Translate to Greek using language code:

npx trxsrt movie.srt -f en -t el

Translate to all languages, output to a custom directory:

npx trxsrt movie.srt -f en --all-languages -o ./translated

Lower concurrency to avoid rate limits:

npx trxsrt movie.srt -f en -t el -c 5

Output Files

Output files are named <filename>.<lang-code>.srt and placed in the same directory as the input file (or the directory specified by --output).

movie.srt           # input
movie.el.srt        # Greek output
movie.ja.srt        # Japanese output
movie.zh-hant.srt   # Traditional Chinese output

Progress Display

The tool shows real-time progress for each language:

Parsed 120 subtitle lines from movie.srt
Translating from English (en) to 1 language(s)

[1/1] Greek (el)
  [el] Translating... 45/120 lines

When translating to all languages, a final summary is shown:

Done! 85 succeeded, 0 failed.

Use with AI CLI Tools

If you use an AI-powered CLI (like Claude Code, Copilot CLI, etc.), you can feed the tool instructions directly:

The skill.md file contains structured instructions that help LLMs understand how to use trxsrt on your behalf. You can pipe it into any AI-powered CLI:

Claude Code:

read  https://raw.githubusercontent.com/VasilisPlavos/trxsrt/main/skill.md and learn how to translate subtitles

OpenAI Codex CLI:

read  https://raw.githubusercontent.com/VasilisPlavos/trxsrt/main/skill.md and learn how to translate subtitles

Google Gemini CLI:

read  https://raw.githubusercontent.com/VasilisPlavos/trxsrt/main/skill.md and learn how to translate subtitles

Or simply paste the URL into any AI chat and ask it to translate your subtitles.

Supported Languages

Languages can be specified by full name (case-insensitive) or code.

Code	Language	Code	Language
en	English	nl	Dutch
el	Greek	he	Hebrew
zh	Simplified Chinese	sv	Swedish
zh-hant	Traditional Chinese	da	Danish
es	Spanish	nb	Norwegian
de	German	is	Icelandic
pt-br	Portuguese (Brazil)	af	Afrikaans
pt-pt	Portuguese (Portugal)	ro	Romanian
fr	French	ca	Catalan
ja	Japanese	uk	Ukrainian
ko	Korean	pl	Polish
ru	Russian	cs	Czech
it	Italian	sk	Slovak
ar	Arabic	bg	Bulgarian
vi	Vietnamese	sr	Serbian
hi	Hindi	hr	Croatian
id	Indonesian	bs	Bosnian
yue	Cantonese	sl	Slovenian
mk	Macedonian	ka	Georgian
be	Belarusian	tr	Turkish
hu	Hungarian	fa	Persian
fi	Finnish	ur	Urdu
lt	Lithuanian	uz	Uzbek
lv	Latvian	kk	Kazakh
et	Estonian	ky	Kyrgyz
sq	Albanian	tk	Turkmen
mt	Maltese	az	Azerbaijani
hy	Armenian	tg	Tajik
mn	Mongolian	ta	Tamil
bn	Bengali	te	Telugu
mr	Marathi	gu	Gujarati
kn	Kannada	pa	Punjabi
ml	Malayalam	ne	Nepali
bho	Bhojpuri	lo	Lao
th	Thai	my	Burmese
ms	Malay	jv	Javanese
fil	Filipino (Tagalog)	sw	Swahili
ha	Hausa	ug	Uyghur
am	Amharic

How It Works

• Parse — The SRT file is read and split into structural lines (subtitle numbers, timecodes, blank lines) and content lines. Only content lines are sent for translation; the SRT structure is preserved exactly.

• Preflight — A single test request is sent before bulk translation to verify API access. If Google returns a CAPTCHA, the tool pauses and prompts you to solve it in your browser and paste the cookie (see CAPTCHA Recovery).

• Translate — Each content line is translated individually using two translation backends in a round-robin pattern: even-indexed lines go through Google Translate (GTX), odd-indexed lines go through DeepLX. This distributes the load across both services and reduces rate-limit errors. Requests run concurrently (default 10 at a time) using p-limit.

• Retry — Failed requests are retried up to 3 times with exponential backoff (2s base, 2x factor, 60s max, randomized jitter). Network errors, 5xx, and 429 responses are retried. Auth errors (401, 403) and CAPTCHA responses are not.

• Rebuild — Translated lines are placed back into the original SRT structure at their original positions, preserving subtitle numbers, timecodes, and formatting.

• Write — The translated SRT is written to disk. In multi-language mode, each file is written as soon as its translation completes, with a 500ms delay between languages.

CAPTCHA Recovery

When Google rate-limits you, the tool will detect it and interactively guide you through recovery:

• The tool prints the blocked URL
• Open the URL in your browser and solve the CAPTCHA
• Copy the GOOGLE_ABUSE_EXEMPTION=... cookie from DevTools (see COOKIE.md)
• Paste it in the terminal when prompted

The cookie is saved automatically for future runs (stored via conf in your OS config directory). On the next run, the saved cookie is loaded automatically — no need to paste it again unless it expires.

You can also pass a cookie directly via the --cookie flag, which takes priority over any saved cookie.

Error Handling

• Invalid file path or non-.srt extension: exits with an error message
• Unrecognized language name/code: exits with the full list of available languages
• CAPTCHA / rate-limiting: detected automatically, pauses and prompts for a cookie (see CAPTCHA Recovery)
• Translation API failures: retried automatically, with per-language error reporting in the final summary
• If any languages fail in --all-languages mode, the tool exits with code 1 and lists all failures

Notes

• Completely free — no API key or account needed.
• Uses two translation backends (Google Translate GTX and DeepLX) in round-robin to distribute load and reduce rate-limit errors.
• Rate limits may still apply on heavy usage — lower the --concurrency value if you encounter 429 errors.
• If rate-limited by Google, the tool will prompt you for a cookie and save it for future runs.
• Only .srt files are supported.