CLI Reference

The i18nizer CLI is the primary interface for automating your internationalization workflow. This reference covers every command, flag, and environment variable available.

Global Flags

These flags can be applied to any command:

Flag	Description
`--help`, `-h`	Display help for the current command
`--version`, `-v`	Show i18nizer version
`--verbose`	Enable detailed debug logging
`--config <path>`	Path to a custom `i18nizer.config.yml`

i18nizer start

Initialize i18nizer in your project.

Usage

Terminal

i18nizer start [OPTIONS]

Options

Flag	Values	Description
`--framework`	`nextjs`, `react`, `custom`	Specify the framework
`--i18n`	`next-intl`, `react-i18next`, `i18next`, `custom`	Specify the i18n library
`--yes`, `-y`	Boolean	Skip interactive prompts
`--force`, `-f`	Boolean	Re-initialize existing project

Examples

Terminal

# Interactive mode (recommended)
i18nizer start

# Auto-detect with defaults
i18nizer start --yes

# Next.js with next-intl
i18nizer start --framework nextjs --i18n next-intl

# React with react-i18next
i18nizer start --framework react --i18n react-i18next

# Force re-initialization
i18nizer start --force

i18nizer translate

The core command of i18nizer. It analyzes your JSX/TSX files, extracts translatable strings, generates JSON files using AI, and rewrites your components to use i18n hooks.

Usage

Terminal

i18nizer translate [FILE_PATTERN] [OPTIONS]

Options

Flag	Type	Description
`--locales`	`string`	Comma-separated list of locale codes (e.g., `en,es,fr`)
`--all`	`boolean`	Scan and translate all components in the project
`--dry-run`	`boolean`	Preview extraction and translation without modifying files
`--show-json`	`boolean`	Print the generated translation JSON to the terminal
`--provider`	`string`	AI provider to use: `openai`, `gemini`, or `huggingface`
`--model`	`string`	Specify a specific model (e.g., `gpt-4o`, `gemini-1.5-pro`)
`--exclude`	`string`	Glob pattern to exclude files (e.g., `"*/.test.tsx"`)

Examples

Terminal

$ i18nizer translate src/components/Login.tsx --locales en,es
🔍 Analyzing src/components/Login.tsx...
📝 Found 3 translatable strings
🌍 Translating to: en, es
✓ messages/en/login.json
✓ messages/es/login.json
✅ Component rewritten successfully!

Terminal

$ i18nizer translate --all --locales en,es,fr
🔍 Scanning project...
📁 Found 12 components
🌍 Translating to: en, es, fr
✅ 12 files processed successfully

Terminal

$ i18nizer translate src/components/Login.tsx --dry-run
[DRY RUN] Would extract:
  - "Welcome back" → welcomeBack
  - "Sign in" → signIn
[DRY RUN] No files will be modified.

i18nizer extract (Legacy)

[!WARNING] This command is deprecated. Use i18nizer translate for an end-to-end workflow.

Legacy command for extracting strings without full component rewriting.

Usage

Terminal

i18nizer extract FILE [OPTIONS]

Options

Flag	Description
`--locales`	Languages to generate (default: `en,es`)
`--provider`	AI provider to use

Example

Terminal

i18nizer extract src/components/Login.tsx --locales en,es,fr --provider openai

i18nizer keys

Manage API keys for AI providers.

Usage

Terminal

i18nizer keys [OPTIONS]

Options

Flag	Description
`--setOpenAI KEY`	Set OpenAI API key
`--setGemini KEY`	Set Google Gemini API key
`--setHF KEY`	Set Hugging Face API key

Examples

Terminal

# Set OpenAI key
i18nizer keys --setOpenAI sk-your-openai-key

# Set Gemini key
i18nizer keys --setGemini your-gemini-key

# Set Hugging Face key
i18nizer keys --setHF your-hf-key

# View configured keys
i18nizer keys

API Key Storage

Keys are stored in: [HOME]/.i18nizer/api-keys.json

Terminal

{
  "openai": "sk-...",
  "gemini": "...",
  "huggingface": "..."
}

i18nizer regenerate

Rebuild the auto-generated aggregator file.

Usage

Terminal

i18nizer regenerate

This command regenerates the i18n/messages.generated.ts file by scanning all JSON files in your messages directory.

When to Use

You manually add or remove translation JSON files
You rename JSON files
The aggregator becomes out of sync with your messages
After bulk edits to translation files

Example

Terminal

# Regenerate aggregator
i18nizer regenerate

# Output
✓ Scanning messages directory...
✓ Found 15 translation files
✓ Generated i18n/messages.generated.ts

Common Workflows

Initial Setup

Terminal

# 1. Initialize project
i18nizer start

# 2. Set API key
i18nizer keys --setOpenAI sk-your-key

# 3. Test with one component
i18nizer translate src/components/Header.tsx --dry-run

# 4. Apply if satisfied
i18nizer translate src/components/Header.tsx --locales en,es,fr

Incremental Translation

Terminal

# Translate new components as you build
i18nizer translate src/components/NewFeature.tsx --locales en,es,fr

# Review changes
git diff src/components/NewFeature.tsx

# Commit
git add .
git commit -m "Add i18n to NewFeature component"

Project-Wide Translation

Terminal

# Preview all changes
i18nizer translate --all --dry-run

# Apply to entire project
i18nizer translate --all --locales en,es,fr,de,ja,zh

# Regenerate aggregator
i18nizer regenerate

Adding New Locales

Terminal

# Translate existing components to new locales
i18nizer translate --all --locales ko,pt,it

# This will create new locale directories with all translations

Advanced Usage

Custom Provider Configuration

In i18nizer.config.yml:

Terminal

ai:
  provider: openai
  model: gpt-4

Then translate:

Terminal

i18nizer translate src/components/App.tsx --locales en,es

Filtering Components

Terminal

# Translate only specific patterns
i18nizer translate "src/components/Auth/**/*.tsx" --all --locales en,es

# Exclude certain directories
i18nizer translate src --all --locales en,es --exclude "**/*.test.tsx"

CI/CD Integration

Terminal

# GitHub Actions example
- name: Translate new components
  run: |
    i18nizer start --yes
    i18nizer keys --setOpenAI ${{ secrets.OPENAI_API_KEY }}
    i18nizer translate --all --locales en,es,fr
    i18nizer regenerate

Exit Codes

Code	Meaning
0	Success
1	General error
2	Configuration error
3	API error
4	File system error

Environment Variables

Variable	Description	Example
`I18NIZER_API_KEY_OPENAI`	OpenAI API key	`sk-...`
`I18NIZER_API_KEY_GEMINI`	Gemini API key	`...`
`I18NIZER_API_KEY_HF`	Hugging Face API key	`...`
`I18NIZER_CONFIG`	Custom config file path	`/path/to/config.yml`

Tips

Always use --dry-run first to preview changes
Commit before translating so you can review diffs
Use specific locale codes following ISO 639-1 standard
Check the cache at .i18nizer/cache/translations.json
Review AI output for accuracy and context
Use --show-json to verify translations before writing

For more examples, see the Examples page.