International Files Translator

A high-performance CLI tool for synchronizing and translating internationalization (i18n) JSON files using the DeepL API. Automatically detects missing translation keys and translates them in batches for optimal efficiency.

Features

• 🚀 Batch Translation - Translates multiple keys in single API calls (up to 50x faster than sequential translation)
• 🎯 Smart Synchronization - Only translates missing keys, preserving existing translations
• 📊 Character Tracking - Monitors DeepL API usage to stay within free tier limits (500,000 chars/month)
• ⚡ Rate Limiting - Configurable delays between requests to prevent API throttling
• 🌍 Multi-locale Support - Translate to multiple target locales simultaneously
• 🔧 Environment-based Configuration - No hardcoded values, fully configurable via .env
• 📈 Progress Reporting - Real-time progress and detailed statistics

Installation

# Clone the repository
git clone <repository-url>
cd intl-files-translator

# Install dependencies
npm install

# Build the project (optional)
npm run build

Configuration

1. Create a .env file from the example:

cp .env.example .env

2. Configure your settings in .env:

# DeepL API Configuration
DEEPL_API_KEY=your-api-key-here

# Locale Configuration
SOURCE_LOCALE=ru
TARGET_LOCALES=en,et

# Performance Tuning
DEEPL_BATCH_SIZE=50
DEEPL_REQUEST_DELAY_MS=100
DEEPL_CHAR_LIMIT=500000

# Paths
OUTPUT_DIR=./output

Configuration Options

Variable	Description	Default	Example
DEEPL_API_KEY	Your DeepL API key (required)	-	abc123...
SOURCE_LOCALE	Source language code	ru	ru, en, de
TARGET_LOCALES	Comma-separated target locales	en,et	en,et,de,fr
DEEPL_BATCH_SIZE	Texts per API request	50	25, 100
DEEPL_REQUEST_DELAY_MS	Delay between requests (ms)	100	50, 200
DEEPL_CHAR_LIMIT	Monthly character limit	500000	500000
OUTPUT_DIR	Directory with translation files	./output	./translations

Usage

1. Prepare Your Translation Files

Create the output directory and add your source translation file:

mkdir output

Add your source file (e.g., output/ru.json):

{
  "common": {
    "hello": "Привет",
    "goodbye": "До свидания",
    "welcome": "Добро пожаловать"
  },
  "auth": {
    "login": "Войти",
    "logout": "Выйти",
    "signup": "Зарегистрироваться"
  }
}

Target files (en.json, et.json) can be:

• Empty (will create all translations)
• Partially filled (will add only missing keys)
• Non-existent (will create the file)

2. Run the Translator

# Development mode (with hot reload)
npm run dev

# Production mode
npm start

# Or run the compiled version
npm run build
node dist/main.js

3. Review the Results

The tool will:

1. Scan your source file for all translation keys
2. Compare with target files to find missing translations
3. Batch translate missing keys via DeepL API
4. Write updated translations back to files
5. Display detailed statistics

Example output:

Starting translation synchronization...
Source locale: ru
Target locales: en, et
Batch size: 50
Request delay: 100ms
Character limit: 500000

Found 150 keys in source locale

============================================================
Processing locale: en
============================================================
Total keys in source: 150
Existing keys in target: 100
Missing translations: 50
Total characters to translate: 1,250

Translating 50 texts in 1 batch(es)...
Batch 1/1: 50 texts (1250 characters)
✓ Translated 50 new keys
✓ Wrote translations to en.json

============================================================
Translation Summary
============================================================
en: 50 translations (1250 chars)
et: 50 translations (1250 chars)
------------------------------------------------------------
Total: 100 translations (2500 characters)
Session usage: 2500 characters
============================================================

DeepL API Usage:
  Characters used: 45,230
  Character limit: 500,000
  Percentage used: 9.05%

✓ Translation synchronization completed successfully!

File Structure

intl-files-translator/
├── src/
│   ├── main.ts                  # Entry point
│   ├── config.ts                # Configuration loader
│   ├── types.ts                 # TypeScript type definitions
│   ├── translation-manager.ts   # Main orchestration logic
│   ├── deepl-client.ts         # DeepL API wrapper
│   ├── file-handler.ts         # File I/O operations
│   ├── object-utils.ts         # Utility functions
│   └── rate-limiter.ts         # Rate limiting logic
├── output/                      # Translation files (configurable)
│   ├── ru.json                 # Source locale
│   ├── en.json                 # Target locale
│   └── et.json                 # Target locale
├── .env                        # Your configuration (not in git)
├── .env.example                # Configuration template
└── package.json

How It Works

flowchart TB
    Start([Start]) --> LoadConfig[Load Configuration]
    LoadConfig --> ReadSource[Read Source Locale File]
    ReadSource --> CheckEmpty{Source File Empty?}
    CheckEmpty -->|Yes| Error[Display Error & Exit]
    CheckEmpty -->|No| ProcessTargets[Process Each Target Locale]

    ProcessTargets --> ReadTarget[Read Target File]
    ReadTarget --> Flatten[Flatten Both JSON Objects]
    Flatten --> FindMissing[Find Missing Keys]
    FindMissing --> AnyMissing{Missing Keys?}

    AnyMissing -->|No| SkipLocale[Skip - Already Synced]
    AnyMissing -->|Yes| CheckLimit{Within Char Limit?}

    CheckLimit -->|No| LimitError[Error - Limit Exceeded]
    CheckLimit -->|Yes| BatchTranslate[Batch Translate Missing Keys]

    BatchTranslate --> Merge[Merge Translations]
    Merge --> Unflatten[Unflatten JSON Structure]
    Unflatten --> WriteFile[Write Updated File]

    WriteFile --> MoreLocales{More Locales?}
    SkipLocale --> MoreLocales
    MoreLocales -->|Yes| ProcessTargets
    MoreLocales -->|No| ShowStats[Display Statistics]

    ShowStats --> ShowUsage[Show DeepL API Usage]
    ShowUsage --> End([Complete])

    Error --> End
    LimitError --> End

Loading

Performance Tips

Optimizing Batch Size

• Larger batches (e.g., 100): Fewer API calls, faster completion
• Smaller batches (e.g., 25): More reliable, better for unstable connections
• Default (50): Good balance for most use cases

Managing API Limits

DeepL Free Tier: 500,000 characters/month

Character estimation:

• Short key (~10 chars): "Cancel", "Save"
• Medium key (~30 chars): "Please enter your email"
• Long key (~100 chars): Full sentences and paragraphs

Example calculation:

• 1,000 short keys ≈ 10,000 characters
• 1,000 medium keys ≈ 30,000 characters
• 100 long keys ≈ 10,000 characters

Monitor your usage with DEEPL_CHAR_LIMIT and the tool will warn you before exceeding limits.

Rate Limiting

Adjust DEEPL_REQUEST_DELAY_MS:

• 50ms: Aggressive (use for one-time large migrations)
• 100ms: Balanced (default recommendation)
• 200ms+: Conservative (use if experiencing rate limit errors)

Supported Languages

DeepL supports many languages including:

bg (Bulgarian), cs (Czech), da (Danish), de (German), el (Greek), en (English), es (Spanish), et (Estonian), fi (Finnish), fr (French), hu (Hungarian), id (Indonesian), it (Italian), ja (Japanese), ko (Korean), lt (Lithuanian), lv (Latvian), nb (Norwegian), nl (Dutch), pl (Polish), pt (Portuguese), ro (Romanian), ru (Russian), sk (Slovak), sl (Slovenian), sv (Swedish), tr (Turkish), uk (Ukrainian), zh (Chinese)

See DeepL documentation for the complete list.

Getting a DeepL API Key

1. Sign up for a free DeepL API account: https://www.deepl.com/pro-api
2. Choose the DeepL API Free plan (500,000 characters/month)
3. Copy your API key from the account settings
4. Add it to your .env file

Troubleshooting

"Missing required environment variable: DEEPL_API_KEY"

Make sure you've created a .env file and added your DeepL API key.

"Source locale file is empty or doesn't exist"

Check that your source file exists at the correct path:

• Default: ./output/ru.json (or whatever SOURCE_LOCALE is set to)
• File must contain valid JSON with translation keys

"Translation would exceed character limit"

You're approaching your monthly DeepL API limit. Options:

• Wait until next month for limit reset
• Upgrade to DeepL API Pro
• Increase DEEPL_CHAR_LIMIT if you have a higher limit

Rate Limit Errors

If you see 429 errors, increase DEEPL_REQUEST_DELAY_MS to add more delay between requests.

Development

# Development mode with hot reload
npm run dev

# Build TypeScript to JavaScript
npm run build

# Run compiled version
node dist/main.js

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.