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

1. 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.

2. 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).

3. 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.

4. 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.

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

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

1. The tool prints the blocked URL
2. Open the URL in your browser and solve the CAPTCHA
3. Copy the GOOGLE_ABUSE_EXEMPTION=... cookie from DevTools (see COOKIE.md)
4. 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.