Translomatic CLI

Auto-scan and translate your entire project from the command line.

Works with react-i18next, next-intl, vue-i18n, angular, svelte-i18n, and any JSON-based i18n setup.

Install

npm install -g translomatic-cli

Quick Start

# 1. Initialize — auto-detect your i18n setup
translomatic init

# 2. Set your API key
export TRANSLOMATIC_API_KEY=tr_live_YOUR_KEY

# 3. (Optional) Auto-analyze context for smarter translations
translomatic analyze

# 4. Translate all missing strings
translomatic translate

# 5. Check translation coverage
translomatic status

Commands

translomatic init

Scans your project to auto-detect the i18n framework, locale directory, and existing languages. Creates a .translomaticrc.json config file.

translomatic init          # Scan and create config
translomatic init --force  # Overwrite existing config

Auto-detects:

• Framework: react-i18next, next-intl, vue-i18n, angular, svelte-i18n
• Locale directory: locales/, messages/, src/locales/, etc.
• File pattern: {lang}.json or {lang}/{namespace}.json
• Source language and existing translations

translomatic translate

Translates all missing strings in your project. Only translates new/changed strings by default — existing translations are preserved.

translomatic translate                          # Translate all missing strings
translomatic translate --force                  # Re-translate everything
translomatic translate -m transloai-pro         # Use a specific model
translomatic translate -l vi,ja                 # Only translate specific languages
translomatic translate -n common                # Only translate specific namespaces
translomatic translate --dry-run                # Preview without changes
translomatic translate -v                       # Verbose output

Features:

• Smart batching (50 strings per API call)
• Progress bar with real-time updates
• Preserves existing translations (use --force to re-translate)
• Context-aware translation using AI models
• Per-language glossary support

translomatic models

Lists all available translation models with speed, quality, and feature information.

translomatic models      # List all models
translomatic models -v   # Include plan tier details

Example output:

  TransloFlash — Fast Translation

  Model ID              Speed       Quality       Tier        Features
  ───────────────────────────────────────────────────────────────────────
  transloflash-lite     ⚡ fastest   ☆ good        free        translation
  transloflash          ⚡ fast      ☆ high        pro         translation
  translomax            ◆ moderate  ★ very high   pro         translation

  TransloAI — AI-Powered Context-Aware

  Model ID              Speed       Quality       Tier        Features
  ───────────────────────────────────────────────────────────────────────
  transloai-nano        ⚡ fast      ☆ good        business    translation, context, glossary
  transloai-lite        ⚡ fast      ☆ high        business    translation, context, glossary
  transloai-base        ◆ moderate  ★ very high   business    translation, context, glossary
  transloai-pro         ◆ moderate  ★ excellent   enterprise  translation, context, glossary
  transloai-ultra       ◇ slow      ★ best        enterprise  translation, context, glossary

translomatic analyze

Uses AI to analyze your source strings and auto-generate:

• Context description: What your app is about (e.g., "mobile app store")
• Recommended model: Best translation model for your domain
• Per-language glossaries: Term mappings for accurate translations

translomatic analyze      # Analyze and update config
translomatic analyze -v   # Verbose output

This solves the common problem of ambiguous translations:

• "Free" → "Miễn phí" (not "Tự do") for an app store
• "Home" → "Trang chủ" (not "Nhà") for a website

translomatic status

Shows translation coverage for all configured target languages.

translomatic status      # Show coverage table
translomatic status -v   # Include namespace breakdown

Example output:

  Translation Status
  ────────────────────────────────────────
  ℹ Source strings: 150

  Lang    Coverage       Translated     Missing
  ─────────────────────────────────────────────
  vi      ████████░░ 80%  120/150       30
  ja      ██████████ 100% 150/150       0
  ko      ██████░░░░ 60%  90/150        60
  fr      ░░░░░░░░░░ 0%   0/150        150

Config File

.translomaticrc.json — created by translomatic init, edit as needed:

{
  "apiKey": "tr_live_YOUR_KEY",
  "sourceLang": "en",
  "targetLangs": ["vi", "ja", "ko", "fr", "es"],
  "localesDir": "./locales",
  "fileFormat": "nested-json",
  "filePattern": "{lang}.json",
  "framework": "react-i18next",
  "namespaces": ["common", "home", "settings"],
  "model": "transloai-pro",
  "context": "This is a mobile app store website...",
  "glossary": {
    "vi": { "Free": "Miễn phí", "Home": "Trang chủ" },
    "ja": { "Free": "無料", "Home": "ホーム" }
  }
}

| Field | Description | |-------|-------------| | apiKey | API key (or use TRANSLOMATIC_API_KEY env var) | | sourceLang | Source language code (default: "en") | | targetLangs | Languages to translate to | | localesDir | Path to locale files directory | | fileFormat | "json" (flat) or "nested-json" (nested keys) | | filePattern | File naming: "{lang}.json" or "{lang}/{namespace}.json" | | framework | Detected i18n framework (informational) | | namespaces | Namespace list for multi-file setups | | model | Translation model ("transloai-pro" for context-aware) | | context | Domain description for AI translation | | glossary | Per-language forced term mappings |

Supported Frameworks

| Framework | Detection | Default Locale Dir | |-----------|-----------|-------------------| | react-i18next | react-i18next in deps | locales/ or public/locales/ | | next-intl | next-intl in deps | messages/ | | vue-i18n | vue-i18n in deps | locales/ or src/locales/ | | Angular i18n | @angular/localize in deps | src/assets/i18n/ | | svelte-i18n | svelte-i18n in deps | src/locales/ | | Generic | Any JSON locale files | Auto-detected |

Supported File Patterns

Single file per language

locales/
├── en.json       ← source
├── vi.json       ← auto-generated
├── ja.json       ← auto-generated
└── ko.json       ← auto-generated

Config: "filePattern": "{lang}.json"

Namespace files per language

locales/
├── en/
│   ├── common.json
│   ├── home.json
│   └── settings.json
├── vi/
│   ├── common.json    ← auto-generated
│   ├── home.json      ← auto-generated
│   └── settings.json  ← auto-generated

Config: "filePattern": "{lang}/{namespace}.json"

Nested JSON Support

The CLI handles nested JSON structures automatically:

{
  "common": {
    "buttons": {
      "save": "Save",
      "cancel": "Cancel"
    }
  },
  "home": {
    "title": "Welcome",
    "subtitle": "Get started today"
  }
}

All leaf strings are extracted, translated, and written back preserving the nested structure.

Environment Variables

| Variable | Description | |----------|-------------| | TRANSLOMATIC_API_KEY | API key (alternative to config file) |

Requirements

• Node.js 18.17 or later
• A Translomatic API key

License

MIT