#Command-line translation (CLI)

The engine behind all three translation tools is platform-agnostic TypeScript, and the command-line entry point reuses the same pipeline and the same format parsing/assembly code as the web app — batching, concurrency, retries, 429 cooldown, glossary, context translation and per-line caching behave identically. Only the browser-specific pieces are swapped for Node equivalents (fetch / file cache / Ctrl-C cancellation).

Good for: running a whole season of subtitles or an entire docs/ tree through in one go, wiring translation into your own scripts or CI, and machines without a browser.

Nothing extra to install — tsx is already in devDependencies:

yarn cli --help          # full parameter list
yarn cli --list-formats  # which formats this checkout supports
yarn cli --list-methods  # available translation services

#Examples

# Simplest: writes movie.zh.srt right next to movie.srt
yarn cli -i movie.srt -t zh

# Output directory + multiple targets → out/movie.ja.srt, out/movie.ko.srt
yarn cli -i movie.srt -t ja -t ko -o out/

# Mixed formats in one run
yarn cli -i a.srt -i b.md -i c.json -t zh -o out/

# Bilingual subtitles (converted to ASS by default) → movie.zh_bilingual.ass
yarn cli -i movie.srt -t zh --bilingual
yarn cli -i movie.srt -t zh --bilingual --bilingual-format srt
yarn cli -i movie.srt -t zh --bilingual --original-first   # original on top

# Use the settings exported from the web UI (API key, prompts, glossary, retry params)
yarn cli -i README.md -t ja -s ~/translate-settings.json

# Point straight at a local LM Studio / Ollama
yarn cli -i locale.json -t zh -m llm --url http://localhost:11434/v1 --model qwen3

# Dedicated local MT models (translategemma / milmmt) have no auto-detect, so -f is required
yarn cli -i movie.srt -f en -t zh -m milmmt --url http://localhost:1234/v1 --model MiLMMT-46-4B-v1.0

# Force a format when the extension is unreliable; translate Markdown line-by-line with no protection
yarn cli -i notes.txt -t zh --format markdown --md-raw

#Configure in the web UI, then load it with -s

The settings file (-s) is exactly the JSON that the web UI's "Export settings" downloads — set up the service, key, prompts and glossary in the interface, then let the CLI read it instead of restating everything with flags. Both shells run the same sanitizer, so out-of-range values and malformed presets are dropped identically.

#Where output goes

#Parameters

Subtitle-only: --bilingual, --original-first, --bilingual-format <ass|srt> (default ass), --no-context (context batching is ON by default, matching the web app; this switch turns it off).

Markdown-only (defaults match the web app item for item): --md-raw (translate whole lines, no placeholder protection); --context (context batching is OFF by default, this turns it on and implies --md-raw — context mode and placeholder protection are mutually exclusive); --md-no-link-text (link text is translated by default, this keeps the original); --md-translate-frontmatter / --md-translate-code / --md-translate-latex (all three are protected by default; opt in as needed).

#Supported formats

All three are built into the CLI itself, so every checkout carries them — yarn cli inside a single-tool subproject can still translate Markdown and JSON.

#Exit codes

#Differences from the web app

• Encoding detection is identical: the CLI also auto-detects GBK / Big5 / UTF-16 and friends. When detection fails it reports ✖ … cannot read and counts toward exit code 1 — it never guesses an encoding and writes mojibake.
• Bilingual ASS always uses the default style: ASS styling is a web-app local preference and is not part of the exported settings file. Use the web app when you need custom ASS styles.