AI Translation System for ERPNext

Complete Documentation

📚 Table of Contents

1. Overview

2. Features

3. Installation

4. Configuration

5. Usage

6. API Reference

7. Troubleshooting

8. Advanced Configuration

9. Performance & Costs

10. Contributing

🌟 Overview

The AI Translation System is a powerful ERPNext app that provides automatic translation of Sales Invoice item descriptions using multiple AI providers. It seamlessly integrates with your ERPNext workflow to deliver natural, context-aware translations in 19+ languages.

🎯 Key Benefits

• Multi-Provider Support: 5 AI providers with automatic fallback

• Bulk Translation: Translate hundreds of items in seconds

• Natural Quality: Business-focused, context-aware translations

• Cost-Effective: Free options available (Groq)

• Zero Configuration: Works out-of-the-box with API keys

✨ Features

🤖 AI Providers

🌍 Supported Languages

• Arabic (ar) - العربية

• Spanish (es) - Español

• French (fr) - Français

• German (de) - Deutsch

• Italian (it) - Italiano

• Portuguese (pt) - Português

• Russian (ru) - Русский

• Japanese (ja) - 日本語

• Korean (ko) - 한국어

• Chinese Simplified (zh) - 中文

• Chinese Traditional (zh-tw) - 中文(繁體)

• Hindi (hi) - हिन्दी

• Urdu (ur) - اردو

• Turkish (tr) - Türkçe

• Dutch (nl) - Nederlands

• Swedish (sv) - Svenska

• Danish (da) - Dansk

• Norwegian (no) - Norsk

• Finnish (fi) - Suomi

🛠️ Core Features

• ✅ Smart AI Translate - Advanced translation with options

• ⚡ Quick AI Translate - One-click bulk translation

• 🔬 Provider Testing - Real-time provider validation

• 📊 Translation Statistics - Usage analytics

• 🧹 Clear Translations - Reset translated content

• ⚙️ Setup Guide - Step-by-step configuration

• 🔄 Auto-Fallback - Automatic provider switching on failure

⚙️ Configuration

Step 1: API Keys Setup

Choose and configure one or more AI providers by adding their API keys to your site_config.json:

{
  "groq_api_key": "gsk_your_groq_api_key_here",
  "openai_api_key": "sk-your_openai_api_key_here",
  "claude_api_key": "sk-ant-your_claude_api_key_here",
  "deepseek_api_key": "sk-your_deepseek_api_key_here",
  "perplexity_api_key": "pplx-your_perplexity_api_key_here"
}

Step 2: Get API Keys

🏆 Recommended: Groq (Free & Fast)

1. Go to console.groq.com

2. Sign up with your email

3. Navigate to API Keys

4. Create a new key

5. Copy the key (starts with gsk_)

Other Providers

🚀 Usage

Quick Start

1. Open a Sales Invoice with items that have descriptions

2. Set Translation Settings:

   • Translation Language: Choose target language (e.g., Arabic)

   • AI Provider: Select your preferred provider (e.g., groq)

3. Click "⚡ Quick AI Translate" to translate all items instantly

Detailed Workflow

1. Smart AI Translation

For advanced control:

1. Click "🧠 Smart AI Translate"

2. Configure options:

   • AI Provider: Choose specific provider

   • Target Language: Select language

   • Overwrite Existing: Replace existing translations

   • Skip Empty Descriptions: Ignore items without descriptions

3. Click "Start AI Translation"

2. Provider Testing

Before translating:

1. Click "🔬 Test AI Providers"

2. Review test results:

   • ✅ Working: Provider is configured and functional

   • ⚙️ Not Configured: API key not set

   • ❌ Failed: Provider error (check API key)

3. Translation Management

• View Stats: Click "📊 Translation Stats" for usage analytics

• Clear All: Click "🧹 Clear All Translations" to reset

• Setup Guide: Click "⚙️ AI Setup Guide" for configuration help

Translation Results

After translation, you'll see: - Success Rate: Percentage of successful translations - Processing Time: Average time per translation - Cost Estimate: Approximate API costs - Provider Used: Which AI service was used

🔧 Advanced Configuration

Environment Variables

Alternative to site_config.json is to use environment variables in your Frappe Cloud private bench:

GROQ_API_KEY="your_key_here"
OPENAI_API_KEY="your_key_here"

📊 Performance & Costs

Performance Metrics

Cost Analysis

Free Options

• Groq: Completely free, 6,000 requests/minute

• DeepSeek: Good free tier, 300 requests/minute

Paid Options (per 1K tokens)

• OpenAI GPT-3.5: ~$0.002

• Claude Haiku: ~$0.0025

• Perplexity: ~$0.001

Cost Estimation

• 100 items: ~$0.10-0.25

• 1,000 items: ~$1.00-2.50

• 10,000 items: ~$10.00-25.00

Optimization Tips

1. Use Groq for bulk operations (free and fast)

2. Use premium providers for important documents

3. Batch translations during off-peak hours

4. Cache translations to avoid re-processing

5. Set up rate limiting for large batches