Langvex

A CLI tool for translating documents (Markdown, plain text, and more) into other languages using Google Gemini (gemini-3.5-flash-lite) via the @google/genai SDK.

Translations are saved to a new file — the original is never modified.

Features

• Translate any text file into <name>_<lang>.<extension> output files
• Multi-language translation in a single run: --lang "ru uk en ja pl"
• Parallel translation is on by default: fast mode runs up to 2 languages at a time per API key (the API processes about 2 concurrent requests per key for this model), slow mode sends all languages at once. Use --sequential to translate one by one, or LANGVEX_CONCURRENCY to cap the number of concurrent workers
• Multiple API keys for real parallelism: store several keys with langvex --api-key <key> --add (or set LANGVEX_API_KEYS="key1,key2,...") — the API's concurrent-request limit is per key, so N keys give N× parallelism
• Automatic retry on rate-limit errors: the request waits (using the API's suggested delay, otherwise 60s) and retries up to LANGVEX_MAX_RETRIES times (default 3). Optional request pacing via LANGVEX_RATE_LIMIT per second (off by default — requests are sent as one burst, which the API schedules in parallel)
• Streaming responses: tokens arrive as they are generated (no timeouts on long documents), with live per-language progress percentages on a terminal
• Preserves Markdown structure: headings, lists, tables, links, code blocks
• API key stored securely in the system secret store
• Encrypted file fallback for systems without a keychain

Requirements

• Node.js 18+
• Google AI API key (https://aistudio.google.com/apikey)

Installation

npm install
npm run build

For global use as a command:

npm install -g .

Quick Start

# 1. Save your API key (once)
langvex --api-key "AIza..."

# 2. Translate a file
langvex --file README.md --lang ru

Alternatively, set the key via environment variable:

export GEMINI_API_KEY="AIza..."

Commands

| Command | Description | | --- | --- | | langvex --file <file> --lang "<langs>" | Translate a file into one or more languages (all languages in parallel by default) | | langvex --file <file> --lang "<langs>" --sequential | Translate languages one by one | | langvex --api-key <key> | Save the API key in the system secret store (replaces stored keys) | | langvex --api-key <key> --add | Add another API key to the store — the API's concurrent-request limit is per key, so N keys give N× parallelism | | langvex --remove-api-key | Remove all stored API keys |

Examples

| Command | Result | | --- | --- | | langvex --file README.md --lang ru | README_ru.md | | langvex --file docs/api.md --lang de | docs/api_de.md | | langvex --file README.md --lang "ru uk en" | README_ru.md, README_uk.md, README_en.md | | langvex --file config.json --lang fr | config_fr.json |

Languages are specified as codes (ISO 639-1), e.g. ru, uk, en, ja, pl, de, fr, es.

API Key Storage

The key is stored in the system secret store:

• Linux — Secret Service
• Windows — Credential Manager
• macOS — Keychain

If the store is unavailable, an encrypted file (AES-256-GCM) is used instead:

• Linux/macOS — ~/.config/langvex/config.json
• Windows — %APPDATA%\langvex\config.json

Multiple keys are stored together and used round-robin across requests.

Modes

Select the translation model with --mode:

| Mode | Model | Speed | Daily document limit | | --- | --- | --- | --- | | fast (default) | gemini-3.5-flash-lite | 255 tokens/sec | ~250 docs/day | | slow | gemma-4-31b-it | 5 tokens/sec | ~7,000 docs/day |

• fast — for everyday use: fast translations, thinking enabled. Good for short-to-medium documents and interactive work.
• slow — high volume per day but much slower. Writes with gemma-4-31b-it, the verification pass runs on the faster MoE gemma-4-26b-a4b-it. Thinking is not supported by these models, so it is disabled automatically.

langvex --file README.md --lang ru --mode fast
langvex --file README.md --lang "ru uk en" --mode slow --parallel

Translation pipeline

In fast mode, thinking (thinkingBudget: 30) is enabled on the verification pass only; thoughts are excluded from the output document.

Each translation goes through two passes:

1. Translation pass (no thinking)
2. Verification pass: the same model compares the original with the translation, fixes errors and returns the corrected document

Config constants live in src/translator.ts (MODEL_FAST, MODEL_SLOW, THINKING_BUDGET).

Development

src/
├── index.ts              # entry point, command orchestration
├── cli-args.ts           # argument parsing + usage
├── config-paths.ts       # config and storage paths
├── api-key-store.ts      # save/load/remove API key
├── keychain.ts           # system keychain wrapper
├── crypto.ts             # AES-256-GCM encryption
├── translator.ts         # Gemini calls (model + prompt)
├── rate-limit.ts         # optional request pacing
└── file-utils.ts         # file reading, output path building

npm run build   # compile TypeScript into dist/
npm start       # run dist/index.js