auto-i18n-cli

A command-line tool for automatically generating translation databases for use with the react-auto-i18n library. It scans your TypeScript source files for all __t() and __tv() calls and produces a JSON translation database.

NOTE: You must have a compatible version of python installed ^3.12

Installation

npm install -D auto-i18n-cli

Then run it directly with npx:

npx auto-i18n-cli [options]

Usage

auto-i18n-cli -i <input> -b <backend> [options]

Example — Azure (remote) backend

npx auto-i18n-cli \
  -i "./src" \
  -o "./assets/translations.json" \
  -s eng_Latn \
  -l spa_Latn fra_Latn deu_Latn \
  -b azure \
  --azureKey "YOUR_AZURE_KEY"

Example — NLLB (local) backend

npx auto-i18n-cli \
  -i "./src" \
  -o "./assets/translations.json" \
  -l spa_Latn jpn_Jpan \
  -b nllb

Options

| Flag | Alias | Required | Description | |---|---|---|---| | --input | -i | ✅ | Path to a TypeScript file or project directory to scan | | --backend | -b | ✅ | Translation backend: azure or nllb | | --languages | -l | | One or more target language codes to translate into (e.g. spa_Latn fra_Latn) | | --out | -o | | Output file path for the translation JSON (default: out.json) | | --sourceLang | -s | | The language your source strings are written in (default: eng_Latn) | | --maxTokens | -t | | Maximum tokens per translation chunk — must be ≥ 100 (default: 250) | | --azureKey | | ✅ (Azure) | Azure Translator API key | | --azureRegion | | | Azure Translator region (default: eastus) | | --azureEndpoint | | | Custom Azure Translator endpoint URL | | --nllbModel | | | NLLB model name (default: facebook/nllb-200-distilled-1.3B) | | --multiFile | -m | | Separate each language into its own file with a manifest (default: false) | | --help | -h | | Show help message |

Backends

Azure Translator

Uses Microsoft's Azure Cognitive Services Translator API. Requires an API key.

npx auto-i18n-cli -i "./src" -b azure --azureKey "YOUR_KEY" -l spa_Latn

Note: not all NLLB language codes have an Azure equivalent. The CLI will report an error if you specify an unsupported language for the Azure backend.

NLLB (Local)

Uses Meta's NLLB-200 model, running locally via Python. No API key required, but requires a compatible Python environment with the model available.

npx auto-i18n-cli -i "./src" -b nllb -l fra_Latn

You can specify a custom model with --nllbModel:

npx auto-i18n-cli -i "./src" -b nllb --nllbModel "facebook/nllb-200-1.3B" -l fra_Latn

Output

Single File Format (default)

The CLI produces a JSON file structured as an I18nDatabase, with one top-level key per language:

{
  "eng_Latn": {
    "greeting": "Hello!",
    "farewell": "Goodbye!"
  },
  "spa_Latn": {
    "greeting": "¡Hola!",
    "farewell": "¡Adiós!"
  },
  "fra_Latn": {
    "greeting": "Bonjour!",
    "farewell": "Au revoir!"
  }
}

This file can be imported directly and passed to I18nProvider in your React app:

import db from './assets/translations.json'
import { I18nProvider, SimpleI18nDb } from 'react-auto-i18n'

<I18nProvider defaultLang="eng_Latn" db={new SimpleI18nDb(db)}>
  <App />
</I18nProvider>

Or, you can also load the file if it is in your public folder.

import { I18nFileProvider } from 'react-auto-i18n'

<I18nFileProvider defaultLang="eng_Latn" path="./translations.json">
  <App />
</I18nFileProvider>

Multi-File Format (--multiFile)

When using the --multiFile (or -m) flag, translations are split into separate JSON files organized in a directory with a manifest:

translations/
├── manifest.json
├── eng_Latn.json
├── spa_Latn.json
└── fra_Latn.json

The manifest.json file contains:

{
  "langs": ["eng_Latn", "spa_Latn", "fra_Latn"]
}

Each language file contains only that language's translations:

{
  "greeting": "¡Hola!",
  "farewell": "¡Adiós!"
}

You can use I18nMultiFileProvider with the multi-file format:

import { I18nMultiFileProvider } from 'react-auto-i18n'

<I18nMultiFileProvider 
  defaultLang="eng_Latn" 
  path="./translations"
>
  <App />
</I18nMultiFileProvider>

How It Works

1. The CLI scans your TypeScript source files (or project directory) for all __t() and __tv() calls.
2. It extracts the key and message string from each call.
3. It sends those strings to the configured translation backend.
4. It writes the resulting translations to the output JSON file.

Because extraction is based on static analysis, both arguments to __t and __tv must be raw string literals — not variables or expressions.

// ✅ Valid — static string literals
__t("greeting", "Hello!")

// ❌ Invalid — cannot be statically extracted
const msg = "Hello!"
__t("greeting", msg)

Language Codes

Language codes follow the {lang}_{Script} format used by the NLLB-200 model (e.g. eng_Latn, spa_Latn, cmn_Hans). See the react-auto-i18n documentation for the full list of supported codes.