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

bun add @ccgp/i18n-ai
# or
npm install @ccgp/i18n-ai

Usage

CLI

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

1. Initialize configuration:

bun x i18n-ai init

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

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

2. Run synchronization:

bun x i18n-ai sync

CLI Options

The sync command supports these options:

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

Example with custom options:

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

Environment Variables

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

Create a .env file:

OPENROUTER_API_KEY=your_api_key

Automate with GitHub Actions

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

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

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:

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