i18n-ai
Version:
AI-powered translation tool for i18n JSON files
251 lines (191 loc) • 7.49 kB
Markdown
[](https://www.npmjs.com/package/i18n-ai)
[](https://opensource.org/licenses/MIT)
[](https://www.npmjs.com/package/i18n-ai)
[](https://github.com/dalisys/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.
- 🤖 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
```bash
npm install --save-dev i18n-ai
# or
yarn add -D i18n-ai
```
## Quick Start
1. Create a config file (`translator.config.json`):
```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`:
```env
OPENAI_API_KEY=your_api_key_here
```
3. Run the translation:
```bash
npx i18n-ai translate
```
```bash
npx i18n-ai translate
npx i18n-ai translate --config custom-config.json
npx i18n-ai translate --overwrite
npx i18n-ai providers
npx i18n-ai models
npx i18n-ai models --provider openai
npx i18n-ai export --output ./exports/translations.csv
npx i18n-ai import -i ./data/translations.csv
```
| 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
```json
{
"description": "A business dashboard application with professional terminology",
"tone": "formal"
}
```
```json
{
"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:
```json
{
"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.
| 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 | - |
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
```json
{
"export": {
"outputPath": "./exports/translations.csv",
"delimiter": ";"
}
}
```
```typescript
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