JSON Translation AI (JTA)

A powerful CLI tool that automatically synchronizes and translates JSON translation files using multiple AI providers including OpenAI GPT, Anthropic Claude, and Google Gemini models. Perfect for maintaining consistent translations across multiple languages in your i18n projects.

✨ Features

🔒 Privacy & Security

• 100% Private: Your content never stored except communication with AI providers.
• Secure API Keys: Your API keys are only used for translation requests, never stored.

💰 Cost-Effective AI Models

• Smart Model Selection: Choose from cost-effective models like Claude Haiku, GPT-4o Mini, and Gemini Flash
• Intelligent Caching: Avoid re-translating existing content to minimize API costs
• Batch Processing: Optimize API usage with efficient batch translations
• Performance Presets: Configure for your API limits and budget

🚀 Advanced Translation Features

• Multi-Provider Support: OpenAI GPT, Anthropic Claude, and Google Gemini models
• Flexible Key Structures: Full support for both nested and flattened JSON key structures
• Custom System Messages: Provide specific context for better translation quality
• Parallel Processing: Multi-language processing with configurable concurrency
• Fallback Strategy: Automatic fallback to individual translations if batch processing fails
• Progress Tracking: Real-time progress bars and detailed logging
• Comprehensive Reporting: Detailed reports on translation success, failures, and missing keys

🚀 Quick Start

1. Installation

npm install -g json-translated-ai

2. Configure AI Provider

Set your API key in your environment or .env file:

PROVIDER_KEY=your_api_key_here


# Optional: Custom proxy endpoint
PROVIDER_PROXY_URL=https://your-proxy-endpoint.com/v1

3. Run Translation

# Use default settings with GPT-4.1
jta

# Specify a custom folder
jta --folder ./locales

# Use a specific AI model
jta --model claude-3-haiku-20240307
jta --model gemini-2.0-flash-exp

# Use performance preset
jta --preset FAST

# Specify API key and proxy URL directly
jta --key your_api_key --url https://your-proxy.com/v1

🤖 Supported AI Models

OpenAI Models

• GPT-4.1 ⭐💰💰 - Latest GPT-4 model with improved performance (default)
• GPT-4o 💰💰 - Fast and efficient GPT-4 model
• GPT-4o Mini 💰 - Cost-effective GPT-4 model
• GPT-3.5 Turbo 💰 - Fast and cost-effective model

Anthropic Models

• Claude 3.5 Sonnet ⭐💰💰 - Claude model with excellent performance
• Claude 3 Haiku ⭐💰 - Fast and cost-effective Claude model
• Claude 3 Opus 💰💰💰 - Most capable Claude model

Google Models

• Gemini 2.0 Flash ⭐💰 - Fast and efficient Gemini model
• Gemini 1.5 Flash 💰 - Balanced Gemini model
• Gemini 1.5 Pro 💰💰 - Capable Gemini model

🎯 Usage Examples

Basic Usage

# Translate all languages in the default locales folder container a en.json
jta

# Specify custom locales folder
jta --folder ./src/locales

# Use specific language file
jta --languages ./target-languages.txt

Model Selection

# Use Claude 3 Haiku for cost-effective translations
jta --model claude-3-haiku-20240307

# Use Gemini 2.0 Flash for fast processing
jta --model gemini-2.0-flash-exp

# Use GPT-4o for high-quality translations
jta --model gpt-4o

Performance Optimization

# Conservative preset for low API limits
jta --preset CONSERVATIVE

# Balanced preset for good performance
jta --preset BALANCED

# Fast preset for high API limits
jta --preset FAST

AI Provider Direct Configuration

# Override environment variables
jta --key your_api_key --url https://your-proxy.com/v1

# Custom system message for specific use case
jta --system "Translate for mobile app UI with friendly, casual tone"

# Combine options
jta --folder ./locales --model claude-3-haiku-20240307 --preset FAST --system "E-commerce website translations"

⚙️ Configuration

Environment Variables

Performance Presets

📊 Output

The tool provides comprehensive output including:

• Progress Tracking: Real-time progress bars for languages and batches
• Translation Logs: Detailed logs of each translation operation
• Success Reports: Summary of completed translations
• Failure Reports: Detailed report of failed translations
• Cache Statistics: Information about cache hits and misses

🔧 Advanced Features

Flexible Key Structures

JTA supports both nested and flattened JSON key structures, automatically handling the conversion between them:

Nested Structure (Recommended)

{
  "navigation": {
    "home": "Home",
    "about": "About Us",
    "services": "Services"
  },
  "hero": {
    "title": "Welcome to Our Platform",
    "subtitle": "The best solution for your needs",
    "cta": "Get Started"
  },
  "services": {
    "frontend": {
      "title": "Frontend Development",
      "features": ["Responsive Design", "Performance Optimization"]
    }
  }
}

Flattened Structure

{
  "navigation.home": "Home",
  "navigation.about": "About Us",
  "navigation.services": "Services",
  "hero.title": "Welcome to Our Platform",
  "hero.subtitle": "The best solution for your needs",
  "hero.cta": "Get Started",
  "services.frontend.title": "Frontend Development",
  "services.frontend.features.0": "Responsive Design",
  "services.frontend.features.1": "Performance Optimization"
}

Array Support

The tool automatically handles arrays with dot notation indexing:

• items.0, items.1 for simple arrays
• metrics.0.label, metrics.0.value for object arrays
• matrix.0.1 for nested arrays

Key Benefits

• Organized Structure: Use nested objects for better organization
• Flexible Processing: System converts nested structures to dot notation internally
• Array Handling: Automatic type conversion and array index support
• Backward Compatible: Works with existing flattened key structures

Custom Cache File

jta --cache /path/to/custom-cache.json

Language-Specific Processing

# Process only specific languages
echo "es\nfr" > languages.txt
jta --languages languages.txt

Custom System Messages

You can provide custom context for better translation quality:

# Mobile app UI translations
jta --system "Translate for mobile app UI with friendly, casual tone"

# E-commerce website
jta --system "E-commerce website translations, professional and trustworthy tone"

# Gaming application
jta --system "Gaming app translations, exciting and engaging tone"

# Technical documentation
jta --system "Technical documentation, precise and clear terminology"

The system message is prepended to the default translation instructions, allowing you to specify:

• Target audience (users, developers, customers)
• Tone and style (casual, professional, friendly, technical)
• Context (mobile app, website, documentation, gaming)
• Special requirements (brand voice, industry terminology)

🚨 Troubleshooting

Common Issues

1. API Key Not Found

   • Ensure PROVIDER_KEY is set in environment or .env file
   • Check that the old OPENAI_API_KEY is set if using backward compatibility

2. Rate Limiting

   • Use CONSERVATIVE preset for lower API limits
   • Reduce concurrent processing in performance config

3. Model Not Supported

   • Check available models with jta --help
   • Ensure you're using a supported model ID

4. Proxy Connection Issues

   • Verify PROVIDER_PROXY_URL is correct
   • Check network connectivity to proxy endpoint

🤝 Contributing

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

📄 License

This project is licensed under the Apache License 2.0.

💼 Support & Hiring

If this project is helpful to you, please help by sharing this tool or hiring me or using our service. Learn more about me. I, just like you are, need to support a family.

🙏 Acknowledgments

• The open-source community for various dependencies