I18n-ai NPM | npm.io

i18n-ai

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.

Features

🤖 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

Installation

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

Quick Start

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

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

Set up your API key in .env:

OPENAI_API_KEY=your_api_key_here

Run the translation:

npx i18n-ai translate

Basic CLI Commands

# 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

Configuration Options

Option	Description	Default
`source.path`	Path to source language file	Required
`source.code`	Source language code	Required
`targets`	Array of target language configurations	Required
`provider`	AI provider (`openai`, `anthropic`, etc.)	`openai`
`model`	Model name for selected provider	Provider default
`chunkSize`	Number of keys per translation chunk	50
`concurrency`	Number of concurrent translation requests	3
`overwrite`	Whether to overwrite existing translations	false
`description`	Project context for better translations	-
`tone`	Desired tone (e.g., "formal", "casual")	-
`ignoreKeys`	Array of keys to ignore during translation	-
`customProvider`	Configuration for a custom translation API	-
`stopOnError`	Whether to stop the process when error occurs	true

Advanced Usage

Translation Context and Tone

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

Ignoring Keys

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

Using a Custom Translation Provider

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.

Configuration Options:

Option	Description	Default
`url`	API endpoint URL	Required
`method`	HTTP method (GET or POST)	POST
`headers`	HTTP headers (including your auth headers)	{}
`body`	Request body template with placeholders	Default format
`responsePath`	JSON path to extract translation from response	-

How It Works:

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

CSV Import/Export Options

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

Programmatic Usage

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