i18n AI Translator

An AI-powered i18n translation library using Vercel AI SDK and OpenAI.

Features

• AI-powered translation with OpenAI models
• Support for multiple target languages
• Incremental translation (only translates new/changed content)
• Section-by-section translation for better context
• Progress tracking with detailed status
• Maintains JSON structure and key order
• Custom translation prompts support
• Environment variables support
• TypeScript support

Installation

npm install i18n-ai-translator

Prerequisites

1. OpenAI API key
2. Create a .env file in your project root:

OPENAI_API_KEY=your_api_key_here

Usage

const {defineConfig} = require('i18n-ai-translator')
async function translate() {
  await defineConfig({
    // Source language files directory
    entry: './locales/en',
    // Source language code
    entryLocale: 'en',
    // OpenAI model to use
    modelName: 'gpt-4',
    // Output directory for translations
    output: './locales',
    // Target languages to translate into
    outputLocales: ['zh-CN', 'ja', 'ko'],
    // Optional custom translation requirements
    prompt: "Technical terms like 'API' should not be translated",
  })
}
translate()

Configuration Options

| Option | Type | Description | Required | Default | | ------------ | -------- | ------------------------------------ | -------- | ------- | | entry | string | Source language files directory | Yes | - | | entryLocale | string | Source language code | Yes | - | | modelName | string | OpenAI model name | No | gpt-4 | | output | string | Output directory for translations | Yes | - | | outputLocales| string[] | Target language codes | Yes | - | | prompt | string | Custom translation requirements | No | '' | | concurrency | number | Max concurrent translations (1-50) | No | 5 |

File Structure

project/
├── locales/
│ ├── en/
│ │ ├── common.json
│ │ └── home.json
│ ├── zh-CN/
│ ├── ja/
│ └── ko/
└── translate.js

Implementation Details

• Uses Vercel AI SDK for OpenAI integration
• Splits large JSON files into sections for better translation quality
• Maintains context across translations
• Preserves JSON structure and key order
• Handles nested objects and arrays
• Supports incremental updates
• Concurrent translation with rate limiting
• Progress tracking per language and section

Error Handling

• Validates configuration options
• Checks for missing API keys
• Handles API rate limits
• Reports failed translations
• Maintains partial progress on errors

Best Practices

1. Keep source JSON files well-structured
2. Use descriptive keys
3. Provide context in custom prompts
4. Test with smaller files first
5. Review translations before deployment

Limitations

• Requires OpenAI API access
• Translation quality depends on AI model
• API costs based on token usage
• Rate limits apply based on OpenAI plan

License

MIT

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.