AI-powered translation tool for i18n JSON files. Translates while preserving nested structure, supports multiple AI providers, and offers CSV import/export for easy management.

• 🤖 Multiple AI providers: OpenAI, Anthropic, Gemini, DeepSeek, XAI
• 🔌 Support for custom translation API endpoints
• 🔄 Preserves JSON structure and handles large files with chunking
• 🔧 Customizable translation settings (models, tone, context)
• 📊 CSV import/export for reviewing translations
• ⚙️ Smart handling of existing translations

npm install --save-dev i18n-ai
# or
yarn add -D i18n-ai

1. Create a config file (translator.config.json):

{
  "source": {
    "path": "./locales/en.json",
    "code": "en"
  },
  "targets": [
    {
      "path": "./locales/es.json",
      "code": "es"
    }
  ],
  "provider": "openai"
}

2. Set up your API key in .env:

OPENAI_API_KEY=your_api_key_here

3. Run the translation:

npx i18n-ai translate

# Translate using config file
npx i18n-ai translate

# Use custom config
npx i18n-ai translate --config custom-config.json

# Force overwrite existing translations
npx i18n-ai translate --overwrite

# List available providers and their details
npx i18n-ai providers

# List available models
npx i18n-ai models
npx i18n-ai models --provider openai

# Export translations to CSV
npx i18n-ai export --output ./exports/translations.csv

# Import translations from CSV
npx i18n-ai import -i ./data/translations.csv

{
  "description": "A business dashboard application with professional terminology",
  "tone": "formal"
}

{
  "ignoreKeys": ["app.constants", "validation.regex"]
}

You can integrate with any translation API by configuring a custom provider. With this approach, you take full control of the request format and authentication:

{
  "customProvider": {
    "url": "https://api.your-translation-service.com/translate",
    "method": "POST",
    "headers": {
      "Content-Type": "application/json",
      "Authorization": "Bearer YOUR_API_KEY_HERE",
      "X-Custom-Header": "value"
    },
    "body": {
      "text": "{{text}}",
      "source": "{{sourceLang}}",
      "target": "{{targetLang}}",
      "format": "json"
    },
    "responsePath": "data.translations[0].translatedText"
  }
}

When customProvider is specified, it takes precedence over the regular provider setting.

1. Request Body: The package will replace these placeholders in your request body:

   • {{text}} - The text to translate
   • {{sourceLang}} - The source language code
   • {{targetLang}} - The target language code

2. Response Handling:

   • If responsePath is specified, the package will extract the translation using that path
   • If not specified, the entire response body will be treated as the translation

3. Error Logging:

   • When errors occur with the custom provider, detailed logs are automatically created
   • Log files are saved in the i18n_ai_logs directory at the root of your project

{
  "export": {
    "outputPath": "./exports/translations.csv",
    "delimiter": ";"
  }
}

import {
  translateFiles,
  exportTranslationsToCSV,
  importTranslationsFromCSV,
  getAvailableProviders,
} from "i18n-ai";

// Translation
await translateFiles({
  configPath: "./custom-config.json",
  overwrite: false,
});

// CSV Export
await exportTranslationsToCSV(config, {
  outputPath: "./exports/translations.csv",
  delimiter: ",",
});

// CSV Import
await importTranslationsFromCSV(config, {
  inputPath: "./imports/translations.csv",
  delimiter: ",",
  skipHeader: true,
  overwrite: false,
});

// Get available providers and models
const providers = getAvailableProviders();
console.log("Available providers:", providers.providers);
console.log("Default model for OpenAI:", providers.defaultModels.openai);
console.log("All OpenAI models:", Object.keys(providers.models.openai));

The package currently supports the following AI providers:

• OpenAI (API key: OPENAI_API_KEY)
• Anthropic (API key: ANTHROPIC_API_KEY)
• Gemini (API key: GEMINI_API_KEY)
• DeepSeek (API key: DEEPSEEK_API_KEY)
• XAI (API key: XAI_API_KEY)
• Custom (Define your own translation API endpoint)

You can get a list of all supported providers and their models using the getAvailableProviders() function or the providers CLI command.

If you find this package useful, please consider:

• ⭐ Giving it a star on GitHub: https://github.com/dalisys/i18n-ai
• 🔧 Contributing with bug reports, feature requests, or pull requests
• 📣 Sharing it with other developers who might find it helpful

Contributions of all kinds are welcome!

MIT