Quick Start

Get up and running with i18nizer in minutes.

1. Installation

Install i18nizer globally to use it across all your projects.

Terminal

# npm
npm install -g i18nizer

# yarn
yarn global add i18nizer

2. API Key Setup

Configure your preferred AI provider to enable automated translations.

Terminal

# OpenAI
i18nizer keys --setOpenAI sk-...

# Google Gemini
i18nizer keys --setGemini ...

# Hugging Face
i18nizer keys --setHF ...

3. Initialization

Run the interactive setup in your project root. i18nizer will auto-detect your framework and i18n library.

Terminal

i18nizer start

4. Run First Translation

Transform your first component with a single command.

Terminal

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

Initialize Your Project

i18nizer offers multiple ways to initialize your project based on your workflow.

Interactive Mode (Recommended)

Run the interactive setup which will auto-detect your framework and i18n library:

Terminal

i18nizer start

This command will:

🔍 Auto-detect your framework (Next.js or React)
🔍 Auto-detect your i18n library (next-intl, react-i18next, i18next)
❓ Ask you to confirm or change the detected settings
✅ Create i18nizer.config.yml with optimal defaults
📁 Set up .i18nizer/ directory for caching
📂 Create messages/ directory for translation files

Example interactive session:

Terminal

? Framework detected: nextjs. Is this correct? (Y/n)
? i18n library detected: next-intl. Is this correct? (Y/n)
? Which locales do you want to support? en,es,fr
✓ Configuration created: i18nizer.config.yml
✓ Created .i18nizer directory
✓ Created messages directory

Non-Interactive Mode

For CI/CD pipelines or automated setups:

Terminal

i18nizer start --yes

This will use auto-detected values without prompting.

Manual Configuration

Specify framework and i18n library explicitly:

Terminal

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

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

# Custom setup
i18nizer start --framework custom --i18n custom

Available options:

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

Your First Translation

Now that your project is initialized, let's translate your first component!

Translate a Single File

Let's translate a simple React component:

Terminal

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

What happens:

✅ Extracts all translatable strings from the component
✅ Generates translation keys using AI
✅ Creates translation JSON files for English, Spanish, and French
✅ Rewrites the component to use t() function

Example output:

Terminal

🔍 Analyzing src/components/Login.tsx...
📝 Found 3 translatable strings
🔑 Generating keys...
🌍 Translating to: en, es, fr
💾 Writing JSON files...
✓ messages/en/login.json
✓ messages/es/login.json
✓ messages/fr/login.json
✅ Component updated: src/components/Login.tsx

Preview Changes First

Use dry-run mode to see what would change without modifying files:

Terminal

i18nizer translate src/components/Login.tsx --dry-run

This shows you:

Which strings will be extracted
What keys will be generated
How the component will be rewritten

Example dry-run output:

Terminal

[DRY RUN] Would extract:
  - "Welcome back" → welcomeBack
  - "Please sign in to continue" → pleaseSignInToContinue
  - "Sign in" → signIn

[DRY RUN] Would create:
  - messages/en/login.json
  - messages/es/login.json

[DRY RUN] Would update:
  - src/components/Login.tsx

Show Generated JSON

Preview the JSON output before writing files:

Terminal

i18nizer translate src/components/Login.tsx --show-json

This displays the exact JSON that will be generated for each locale.

Translate Multiple Files

Translate all components in your project at once:

Terminal

i18nizer translate --all --locales en,es,fr,de

Advanced patterns:

Terminal

# Translate specific directory
i18nizer translate src/components --all --locales en,es,fr

# Translate with specific AI provider
i18nizer translate src/components --all --provider gemini

# Dry-run for entire project
i18nizer translate --all --dry-run

Understanding the Output

After running i18nizer, your project structure will look like this:

Terminal

your-project/
├── i18nizer.config.yml       # Configuration
├── .i18nizer/
│   ├── cache/
│   │   └── translations.json # Translation cache
│   └── ...
├── i18n/
│   └── messages.generated.ts # Auto-generated aggregator
└── messages/                 # Translation files
    ├── en/
    │   ├── login.json
    │   ├── dashboard.json
    │   └── settings.json
    ├── es/
    │   ├── login.json
    │   ├── dashboard.json
    │   └── settings.json
    └── fr/
        ├── login.json
        ├── dashboard.json
        └── settings.json

JSON File Format

Each JSON file follows this structure:

Terminal

{
  "ComponentName": {
    "translationKey": "Translation text",
    "anotherKey": "Another translation"
  }
}

Example (messages/en/login.json):

Terminal

{
  "Login": {
    "welcomeBack": "Welcome back",
    "pleaseSignInToContinue": "Please sign in to continue",
    "emailPlaceholder": "Email address",
    "passwordPlaceholder": "Password",
    "signIn": "Sign in",
    "forgotPassword": "Forgot password?",
    "dontHaveAccount": "Don't have an account?",
    "signUp": "Sign up"
  }
}

Aggregator File

The auto-generated i18n/messages.generated.ts imports all your translation files:

Terminal

// Auto-generated by i18nizer
import Login_en from '../messages/en/login.json'
import Login_es from '../messages/es/login.json'
import Dashboard_en from '../messages/en/dashboard.json'
import Dashboard_es from '../messages/es/dashboard.json'

export const messages = {
  en: {
    ...Login_en,
    ...Dashboard_en,
  },
  es: {
    ...Login_es,
    ...Dashboard_es,
  },
}

Regenerating the Aggregator

If you manually add or remove JSON files, regenerate the aggregator:

Terminal

i18nizer regenerate

Real-World Workflow Example

Here's a complete workflow from start to finish:

Step 1: Initialize Project

Terminal

cd my-nextjs-app
i18nizer start

Step 2: Configure API Key

Terminal

i18nizer keys --setOpenAI sk-your-api-key-here

Step 3: Preview One Component

Terminal

i18nizer translate src/components/Header.tsx --dry-run

Step 4: Translate Component

Terminal

i18nizer translate src/components/Header.tsx --locales en,es,fr,de

Step 5: Review Changes

Terminal

git diff src/components/Header.tsx
cat messages/en/header.json

Step 6: Translate Entire Project

Terminal

i18nizer translate --all --locales en,es,fr,de,ja,zh

Step 7: Regenerate Aggregator (if needed)

Terminal

i18nizer regenerate

Step 8: Test in Your App

Terminal

npm run dev
# Test switching between languages

Troubleshooting

Command Not Found

If you get "command not found" after installation:

Terminal

# Check npm global bin path
npm config get prefix

# Add to PATH (Unix/Linux/macOS)
export PATH=$PATH:$(npm config get prefix)/bin

# Or reinstall globally
npm install -g i18nizer

API Key Not Working

Verify your API key is configured:

Terminal

i18nizer keys

Check the stored keys file:

Terminal

cat ~/.i18nizer/api-keys.json

Translations Not Generated

Ensure you have:

Configured an API key
Internet connection
Valid API key with credits/quota

Component Not Updated

Check the i18nizer.config.yml configuration:

Terminal

behavior:
  autoInjectT: true  # Should be true for automatic injection

For Next.js Server Components, you may need to manually add the translation hook.

Next Steps

Now that you have i18nizer set up:

Learn about CLI commands and options
Configure project settings
Explore real-world examples
Understand the architecture
Contribute to the project

Best Practices

Commit before translating - Always commit your changes before running i18nizer
Use dry-run first - Preview changes with --dry-run before applying
Review AI translations - AI translations are good but not perfect
Cache is your friend - The cache prevents duplicate API calls
Consistent keys - Let i18nizer generate keys for consistency
Version control - Commit both code and JSON files together

Need help? Check out our GitHub Discussions or open an issue.