node-translator-os

CLI for translating JSON and Markdown files into multiple locales. Install as a devDependency.

Installation

npm install -D node-translator-os

Quick start in a consumer project

{
  "devDependencies": {
    "node-translator-os": "^1.0.3"
  },
  "scripts": {
    "i18n": "node-translator translate --dir i18n/locales --all --exclude ru",
    "i18n:md": "node-translator translate-md --dir blog/translates --all --exclude ru",
    "i18n:status": "node-translator status --dir i18n/locales"
  }
}

Project layout:

my-app/
├── i18n/locales/
│   ├── en.json              # source
│   ├── ru.json              # ← generated
│   ├── es.json              # ← generated
│   └── .translation-hashes.json
└── blog/translates/
    ├── en.md                # source
    ├── ru.md                # ← generated
    └── es.md                # ← generated

Unified command format

Both commands work the same way: --dir points to the directory containing the English source file. Translations are written into the same directory.

JSON

node-translator translate --dir i18n/locales --all
node-translator translate --dir i18n/locales --all --exclude ru
node-translator translate --dir i18n/locales -l ru,es,fr --exclude ru
node-translator translate --dir i18n/locales --all -f

• Reads i18n/locales/en.json
• Writes i18n/locales/ru.json, es.json, ...
• Hashes: i18n/locales/.translation-hashes.json
• Default provider: Google (no API key required)

Markdown

node-translator translate-md --dir blog/translates --all
node-translator translate-md --dir blog/translates --all --exclude ru
node-translator translate-md --dir blog/translates -l ru,es --exclude ru
node-translator translate-md --dir blog/translates --all -f

• Reads blog/translates/en.md
• Writes blog/translates/ru.md, es.md, ...
• Requires an OpenAI API key

Providers

| Provider | When | API key | |----------|------|---------| | google | Default for JSON | Not required | | gpt | -p gpt (JSON) or translate-md | OpenAI |

API key resolution order:

1. -k/--key
2. OPENAI_API_KEY environment variable
3. key.txt in the project root

# JSON via Google
node-translator translate --dir i18n/locales -l ru,es

# JSON via GPT
node-translator translate --dir i18n/locales -l ru -p gpt -k $OPENAI_API_KEY

Common flags

| Flag | Description | Default | |------|-------------|---------| | --dir | Directory with en.json / en.md | required | | -l, --locales | Comma-separated locales | ru,es,fr,de | | --all | All locales except en | — | | --exclude | Locales to skip | — | | -f, --force | Re-translate everything / overwrite existing files | — | | -t, --threads | Parallel threads | 5 | | -k, --key | OpenAI API key | env / key.txt | | -m, --model | GPT model | gpt-4o-mini |

Additional flags for translate: -p, --provider (google / gpt)

Additional flags for translate-md: --temperature (0–2, default 1)

Utility commands

node-translator status --dir i18n/locales
node-translator clean --dir i18n/locales
node-translator info

clean removes {locale}.json, {locale}.md, and .translation-hashes.json from the directory. It does not touch en.json or en.md.

Programmatic API

import Translator from 'node-translator-os';

const translator = new Translator({ provider: 'google', maxConcurrent: 5 });
await translator.translateJsonFile('i18n/locales/en.json', ['ru', 'es'], 'i18n/locales');

License

MIT