i18n-ai

AI-powered internationalization (i18n) translation and synchronization library. This tool automates the translation of your JSON message files using AI, keeping them synchronized with your base locale.

Features

- 🤖 AI-Powered: Uses Google Gemini (via OpenRouter) to generate context-aware translations.
- ⚡ Parallel Processing: Translations run concurrently for maximum speed (5x faster).
- 🔄 Smart Synchronization: Detects new, modified, and obsolete keys.
- ⛔ Variable Protection: Automatically preserves variables like {name} or {count}.
- 🔒 Lock File System: Prevents unnecessary re-translations of already translated content.
- 🧩 Framework Agnostic: Works with any i18n library that uses JSON files (next-intl, react-i18next, etc.).

Installation

``bash
bun add @ccgp/i18n-ai


or


npm install @ccgp/i18n-ai
`

Usage

$3

The easiest way to use i18n-ai is via the CLI.

1. Initialize configuration:

`bash
bun x i18n-ai init
`

This will create an i18n-ai.config.json file:

`json
{
"defaultLocale": "en",
"locales": ["en", "es", "fr"],
"messagesDir": "messages"
}
`

2. Run synchronization:

`bash
bun x i18n-ai sync
`

$3

The sync command supports these options:

| Option | Description |
|--------|-------------|
| -d, --dir | Messages directory (default: messages) |
| -l, --locales | Comma-separated list of locales |
| --default | Default locale (default: en) |
| --lock | Lock file path (default: translation-lock.json) |
| --api-key | OpenRouter API key (or set OPENROUTER_API_KEY) |
| --model | AI model to use (default: google/gemini-2.5-flash) |

Example with custom options:

`bash
bun x i18n-ai sync --locales es,fr,de --model anthropic/claude-3-haiku
`

$3

You need to provide an API key for the AI provider.

Create a .env file:

`env
OPENROUTER_API_KEY=your_api_key
`

$3

You can automate translations whenever you push changes to your default locale.

Create .github/workflows/i18n-translate.yml:

`yaml
name: AI Translation Sync

on:
push:
paths:
- 'public/messages/en.json' # Monitor ONLY source locale

jobs:
translate:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@v4
- uses: oven-sh/setup-bun@v1
- run: bun install
- run: bun x i18n-ai sync --api-key ${{ secrets.OPENROUTER_API_KEY }}
- run: |
git config --global user.name "github-actions[bot]"
git config --global user.email "github-actions[bot]@users.noreply.github.com"
if [[ -n $(git status -s) ]]; then
git add public/messages/*.json translation-lock.json
git commit -m "chore(i18n): update translations [skip ci]"
git push
fi
`

Programmatic Usage

You can also use the library programmatically:

`typescript
import { TranslationService } from '@ccgp/i18n-ai';
import { resolve } from 'path';

const service = new TranslationService({
locales: ['en', 'es', 'fr'],
defaultLocale: 'en',
messagesDir: resolve(process.cwd(), 'messages'),
lockFilePath: resolve(process.cwd(), 'translation-lock.json'),
apiKey: process.env.OPENROUTER_API_KEY
});

await service.sync();
``

License

ISC