AI i18n Translator

AI-powered internationalization (i18n) auto-translation tool with pluggable extractors, translators, and organizers.

Features

• 🔍 Auto-extraction of translation keys from your codebase
• 🤖 AI-powered translation using Claude CLI or OpenAI GPT
• 📂 Multiple organization strategies for translation files
• 🔌 Pluggable architecture - customize extractors, translators, and organizers
• 🌍 Plural forms support with automatic generation
• 📦 Namespace support for better organization

Installation

As a global CLI tool

npm install -g ai-i18n-translator

As a dev dependency

npm install --save-dev ai-i18n-translator

Quick Start

1. Create configuration file:

Choose the format that matches your project:

ES Module (auto-translate.config.mjs or auto-translate.config.js with "type": "module"):

export default {
  extensions: ['.tsx', '.ts', '.jsx', '.js'],
  excludedDirs: ['node_modules', '.git', 'dist'],
  messagesDir: 'messages',
  supportedLocales: ['en', 'vi', 'es'],
  sourceLocale: 'en'
}

CommonJS (auto-translate.config.cjs or auto-translate.config.js without "type": "module"):

module.exports = {
  extensions: ['.tsx', '.ts', '.jsx', '.js'],
  excludedDirs: ['node_modules', '.git', 'dist'],
  messagesDir: 'messages',
  supportedLocales: ['en', 'vi', 'es'],
  sourceLocale: 'en'
}

💡 Tip: Use .mjs for ES modules or .cjs for CommonJS to avoid Node.js warnings

2. Use t2() function in your code:

// Simple translation
t2("Welcome to our app")

// With context
t2("Submit", { description: "Button to submit form" })

// With parameters
t2("Hello {{name}}", { name: userName })

// With namespace
t2("Login", { ns: "auth" })

// With plurals
t2("You have {{count}} messages", { 
  count: messageCount,
  plural: true  // Auto-generates plural forms
})

3. Run the translator:

# If installed globally (defaults to Claude)
ai-i18n

# Use OpenAI / GPT for this run (requires OPENAI_API_KEY)
ai-i18n --translator gpt

# If installed locally
npx ai-i18n

# Or add to package.json scripts
npm run translate

Configuration

Basic Configuration

export default {
  // File extensions to scan
  extensions: ['.tsx', '.ts', '.jsx', '.js'],
  
  // Directories to exclude
  excludedDirs: ['node_modules', '.git', '.next', 'dist'],
  
  // Output directory for translations
  messagesDir: 'messages',
  
  // Supported languages
  supportedLocales: ['en', 'vi', 'es', 'fr'],
  
  // Source language
  sourceLocale: 'en',
  
  // Choose organizer (default: 'json')
  organizer: 'folder',  // 'json' | 'namespace' | 'folder'
  
  // Optional: organizer-specific options
  organizerOptions: {
    prettify: true,
    indent: 2,
    sortKeys: true,
    rootFileName: 'common.json'  // for folder organizer (default: 'common.json')
  },
  
  // Components (currently have single implementations)
  extractor: 't2',      // default: 't2'
  translator: 'claude',  // default; use 'openai' or 'gpt' for OpenAI (value is trimmed)

  // Optional global context file for AI prompts
  contextFile: 'context.md',
  
  // Translation settings
  batchSize: 10,
  
  // Language names for better context
  languageNames: {
    en: 'English',
    vi: 'Vietnamese',
    es: 'Spanish',
    fr: 'French'
  }
}

Advanced Configuration with Custom Objects

import { FolderNamespaceOrganizer } from 'ai-i18n-translator';

export default {
  // ... basic config ...
  
  // Pass custom instances for full control
  organizer: new FolderNamespaceOrganizer({
    prettify: true,
    indent: 2,
    sortKeys: true
  })
}

Global Context File

Add an optional context.md beside your config file to give translators shared background (product info, tone, glossary). If present, the CLI reads the file and appends its content to every AI prompt so the provider can stay consistent across locales.

• Use contextFile to point to a different location (e.g., docs/translation-context.md).
• When using the folder organizer, the tool also inlines the current namespace’s English JSON so models see the latest copy.

Translator Options

• Claude (default): set translator: 'claude' or use new ClaudeTranslator(). The claude CLI must be installed and authenticated.
• OpenAI / GPT: set translator: 'openai' or translator: 'gpt' (the value is trimmed and case-insensitive) and provide OPENAI_API_KEY. Optionally include a model in the config, e.g. model: 'gpt-4o-mini'.
• CLI override: run ai-i18n --translator openai (or -t gpt) to override the config for a single run.
• Custom translator: supply an object implementing the translator interface (see translators/base-translator.js).

Organizers

Available Organizer Types

| Type | Config Value | File Structure | |------|-------------|----------------| | JSONOrganizer | 'json' | Single file per locale | | NamespaceFileOrganizer | 'namespace' | Flat files with namespace prefix | | FolderNamespaceOrganizer | 'folder' | Folder per locale with namespace files |

JSONOrganizer (Default)

export default {
  organizer: 'json'  // or omit for default
}

Structure:

messages/
  en.json    (all translations)
  vi.json
  es.json

NamespaceFileOrganizer

export default {
  organizer: 'namespace'
}

Structure:

messages/
  en.json           (root keys)
  en.auth.json      (auth namespace)
  en.dashboard.json (dashboard namespace)
  vi.json
  vi.auth.json
  vi.dashboard.json

FolderNamespaceOrganizer

export default {
  organizer: 'folder',
  organizerOptions: {
    rootFileName: 'common.json'  // optional, default: 'common.json'
  }
}

Structure:

messages/
  en/
    common.json     (default/root translations)
    auth.json       (auth namespace)
    dashboard.json  (dashboard namespace)
  vi/
    common.json
    auth.json
    dashboard.json

Programmatic API

import TranslationManager from 'ai-i18n-translator';

const manager = new TranslationManager({
  messagesDir: 'locales',
  supportedLocales: ['en', 'fr', 'de'],
  sourceLocale: 'en'
});

await manager.run();

Creating Custom Components

Custom Extractor

import BaseExtractor from 'ai-i18n-translator/extractors/base-extractor.js';

class MyExtractor extends BaseExtractor {
  extractKeysFromFile(filePath) {
    // Your extraction logic
    return [{
      key: 'translation.key',
      file: filePath,
      line: 10,
      namespace: 'common'
    }];
  }
}

Custom Translator

import BaseTranslator from 'ai-i18n-translator/translators/base-translator.js';

class MyTranslator extends BaseTranslator {
  async translateBatch(texts, sourceLang, targetLang) {
    // Your translation logic
    return translations;
  }
}

Custom Organizer

import BaseOrganizer from 'ai-i18n-translator/organizers/base-organizer.js';

class MyOrganizer extends BaseOrganizer {
  loadLocale(locale) {
    // Your loading logic
  }
  
  saveLocale(locale, data) {
    // Your saving logic
  }
}

Requirements

• Node.js >= 14.0.0
• Claude CLI (for AI translations) - Install from claude.ai/cli

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and feature requests, please create an issue.