ai-i18n-translator/README.md

AI-powered i18n auto-translation tool with pluggable extractors, translators, and organizers

# 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 custom translators)
- 📂 **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

```bash
npm install -g ai-i18n-translator
```

### As a dev dependency

```bash
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"`):
```javascript
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"`):
```javascript
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**:

```javascript
// 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**:

```bash
# If installed globally
ai-i18n

# If installed locally
npx ai-i18n

# Or add to package.json scripts
npm run translate
```

## Configuration

### Basic Configuration

```javascript
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: 'claude'
  
  // Translation settings
  batchSize: 10,
  
  // Language names for better context
  languageNames: {
    en: 'English',
    vi: 'Vietnamese',
    es: 'Spanish',
    fr: 'French'
  }
}
```

### Advanced Configuration with Custom Objects

```javascript
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
  })
}
```

## 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)

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

Structure:
```
messages/
  en.json    (all translations)
  vi.json
  es.json
```

### NamespaceFileOrganizer

```javascript
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

```javascript
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

```javascript
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

```javascript
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

```javascript
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

```javascript
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](https://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](https://github.com/yourusername/ai-i18n-translator/issues).