Translation Service Guide

The AI Content Processing API includes powerful translation capabilities using OpenAI GPT and Google Gemini APIs. This guide covers all translation features and provides practical examples.

🌐 Features

Single Text Translation: Translate individual texts between languages
Batch Translation: Translate multiple texts efficiently
Language Detection: Automatically detect the language of text
Auto-Detection: Use "auto-detect" as source language for automatic detection
Dual API Support: Choose between OpenAI and Gemini APIs
47+ Languages: Support for major world languages

📋 API Endpoints

1. Single Text Translation

POST /translate

Translate a single text from source language to target language.

curl -X POST http://localhost:8000/translate \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, how are you?",
    "source_language": "English",
    "target_language": "Spanish",
    "use_openai": true
  }'

Response:

{
  "request_id": "123e4567-e89b-12d3-a456-426614174000",
  "success": true,
  "original_text": "Hello, how are you?",
  "translated_text": "Hola, ¿cómo estás?",
  "source_language": "English",
  "target_language": "Spanish",
  "api_used": "OpenAI",
  "model_used": "gpt-3.5-turbo",
  "original_length": 18,
  "translated_length": 17,
  "processing_time": 1.23,
  "timestamp": "2024-01-15T10:30:00"
}

2. Batch Translation

POST /translate-batch

Translate multiple texts in a single request (up to 50 texts).

curl -X POST http://localhost:8000/translate-batch \
  -H "Content-Type: application/json" \
  -d '{
    "texts": [
      "Good morning!",
      "How can I help you?",
      "Thank you very much."
    ],
    "source_language": "English",
    "target_language": "French",
    "use_openai": true
  }'

Response:

{
  "batch_id": "batch_123e4567-e89b-12d3",
  "success": true,
  "total_texts": 3,
  "successful": 3,
  "failed": 0,
  "source_language": "English",
  "target_language": "French",
  "results": [
    {
      "index": 0,
      "original_text": "Good morning!",
      "success": true,
      "translated_text": "Bonjour !",
      "processing_time": 0.95
    }
  ],
  "processing_time": 2.87,
  "timestamp": "2024-01-15T10:30:00"
}

3. Language Detection

POST /detect-language

Detect the language of a given text.

curl -X POST http://localhost:8000/detect-language \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Bonjour, comment allez-vous?",
    "use_openai": true
  }'

Response:

{
  "request_id": "detect_123e4567-e89b-12d3",
  "success": true,
  "original_text": "Bonjour, comment allez-vous?",
  "detected_language": "French",
  "confidence": 0.95,
  "api_used": "OpenAI",
  "processing_time": 0.67,
  "timestamp": "2024-01-15T10:30:00"
}

4. Supported Languages

GET /supported-languages

Get list of all supported languages and API status.

curl http://localhost:8000/supported-languages

Response:

{
  "supported_languages": [
    "English", "Spanish", "French", "German", "Italian", "Portuguese",
    "Russian", "Chinese", "Japanese", "Korean", "Arabic", "Hindi"
  ],
  "total_languages": 47,
  "auto_detection_supported": true,
  "available_apis": {
    "openai": true,
    "gemini": true
  }
}

🔧 Request Parameters

Translation Request

Parameter	Type	Required	Description
`text`	string	Yes	Text to translate (max 10,000 chars)
`source_language`	string	Yes	Source language or "auto-detect"
`target_language`	string	Yes	Target language
`use_openai`	boolean	No	Use OpenAI (true) or Gemini (false). Default: true

Batch Translation Request

Parameter	Type	Required	Description
`texts`	array	Yes	Array of texts to translate (max 50 items)
`source_language`	string	Yes	Source language or "auto-detect"
`target_language`	string	Yes	Target language
`use_openai`	boolean	No	Use OpenAI (true) or Gemini (false). Default: true

Language Detection Request

Parameter	Type	Required	Description
`text`	string	Yes	Text to analyze (max 5,000 chars)
`use_openai`	boolean	No	Use OpenAI (true) or Gemini (false). Default: true

🌍 Supported Languages

The translation service supports 47+ languages including:

European Languages:

English, Spanish, French, German, Italian, Portuguese
Russian, Dutch, Swedish, Norwegian, Danish, Finnish
Polish, Czech, Hungarian, Romanian, Bulgarian
Croatian, Serbian, Slovak, Slovenian, Estonian
Latvian, Lithuanian, Greek, Turkish, Ukrainian
Catalan, Basque, Welsh, Irish

Asian Languages:

Chinese, Japanese, Korean, Thai, Vietnamese
Hindi, Bengali, Urdu, Persian, Arabic, Hebrew
Indonesian, Malay, Filipino

African Languages:

Swahili, Afrikaans, Amharic

💡 Usage Examples

Auto-Detection Translation

Use "auto-detect" as the source language to automatically detect the input language:

import requests

response = requests.post("http://localhost:8000/translate", json={
    "text": "¿Cómo estás hoy?",
    "source_language": "auto-detect",  # Will detect Spanish
    "target_language": "English",
    "use_openai": True
})

result = response.json()
print(f"Detected: {result['source_language']}")  # Spanish
print(f"Translation: {result['translated_text']}")  # How are you today?

Batch Processing

Process multiple texts efficiently:

import requests

texts = [
    "Good morning!",
    "How can I help you?",
    "Thank you very much.",
    "Have a great day!"
]

response = requests.post("http://localhost:8000/translate-batch", json={
    "texts": texts,
    "source_language": "English",
    "target_language": "Spanish",
    "use_openai": True
})

result = response.json()
for item in result["results"]:
    print(f"'{item['original_text']}' → '{item['translated_text']}'")

Language Detection

Identify the language of unknown text:

import requests

response = requests.post("http://localhost:8000/detect-language", json={
    "text": "Guten Tag, wie geht es Ihnen?",
    "use_openai": True
})

result = response.json()
print(f"Language: {result['detected_language']}")  # German
print(f"Confidence: {result['confidence']:.1%}")   # 95.0%

API Selection

Choose between OpenAI and Gemini APIs:

import requests

# Using OpenAI (default)
openai_result = requests.post("http://localhost:8000/translate", json={
    "text": "Hello world",
    "source_language": "English",
    "target_language": "French",
    "use_openai": True  # Use OpenAI
}).json()

# Using Gemini
gemini_result = requests.post("http://localhost:8000/translate", json={
    "text": "Hello world",
    "source_language": "English",
    "target_language": "French",
    "use_openai": False  # Use Gemini
}).json()

print(f"OpenAI: {openai_result['translated_text']}")
print(f"Gemini: {gemini_result['translated_text']}")

🔍 Error Handling

Common Error Responses

API Not Available:

{
  "detail": "Translation processor not available. Please check OpenAI or Gemini API configuration."
}

Invalid Language:

{
  "success": false,
  "error": "Translation failed: Unsupported language pair"
}

Text Too Long:

{
  "detail": [
    {
      "type": "string_too_long",
      "loc": ["body", "text"],
      "msg": "String should have at most 10000 characters"
    }
  ]
}

Error Handling Best Practices

import requests

def safe_translate(text, source_lang, target_lang):
    try:
        response = requests.post("http://localhost:8000/translate", json={
            "text": text,
            "source_language": source_lang,
            "target_language": target_lang
        })

        response.raise_for_status()  # Raise exception for HTTP errors
        result = response.json()

        if result.get("success"):
            return result["translated_text"]
        else:
            print(f"Translation failed: {result.get('error')}")
            return None

    except requests.exceptions.RequestException as e:
        print(f"Request failed: {e}")
        return None
    except Exception as e:
        print(f"Unexpected error: {e}")
        return None

# Usage
translation = safe_translate("Hello", "English", "Spanish")
if translation:
    print(f"Translation: {translation}")

🚀 Python Client Library

For easier integration, use the provided Python client:

from translation_examples import TranslationClient

# Initialize client
client = TranslationClient("http://localhost:8000")

# Single translation
result = client.translate_text(
    text="Hello world",
    source_language="English",
    target_language="Spanish"
)

# Batch translation
batch_result = client.translate_batch(
    texts=["Hello", "Goodbye", "Thank you"],
    source_language="English",
    target_language="French"
)

# Language detection
detection = client.detect_language("Bonjour le monde")

# Get supported languages
languages = client.get_supported_languages()

⚙️ Configuration

Environment Variables

The translation service requires at least one API key:

# .env file
OPENAI_API_KEY=your_openai_api_key_here
GOOGLE_API_KEY=your_gemini_api_key_here

API Models

OpenAI: Uses the model specified in OPENAI_MODEL (default: gpt-3.5-turbo)
Gemini: Uses gemini-2.5-flash model

🔒 Rate Limits & Best Practices

Rate Limiting

Follow the rate limits of your chosen API provider
Use batch endpoints for multiple translations to reduce API calls
Consider implementing client-side caching for frequently translated content

Performance Tips

Use auto-detection sparingly as it requires an additional API call
Batch similar translations together for better efficiency
Choose the appropriate API based on your use case:
- OpenAI: Better for formal/business text
- Gemini: Good for casual/conversational text

Text Length Limits

Single translation: 10,000 characters max
Language detection: 5,000 characters max
Batch translation: 50 texts max per request

🧪 Testing

Run the comprehensive examples:

# Run all translation examples
python translation_examples.py

# Test specific functionality
python -c "
from translation_examples import TranslationClient
client = TranslationClient()
result = client.translate_text('Hello', 'English', 'Spanish')
print(result)
"

📊 Response Fields

Translation Result Fields

request_id: Unique identifier for the request
success: Boolean indicating if translation succeeded
original_text: Input text
translated_text: Translated output (null if failed)
source_language: Source language used
target_language: Target language used
api_used: API provider used ("OpenAI" or "Gemini")
model_used: Specific model used
original_length: Character count of input
translated_length: Character count of output
error: Error message (null if successful)
processing_time: Time taken in seconds
timestamp: ISO timestamp of request

🆘 Troubleshooting

Common Issues

1. "Translation processor not available"

Ensure at least one API key (OpenAI or Gemini) is configured
Check that the API server started without errors

2. "Translation failed: Empty response"

Text might be too short or contain only special characters
Try with longer, more substantial text

3. Language detection inaccurate

Provide more text for better detection accuracy
Ensure text contains enough linguistic markers
Consider manually specifying the language if known

4. Slow response times

Large texts take longer to process
Use batch endpoints for multiple texts
Consider using Gemini for potentially faster responses

Debug Mode

Enable debug logging in the API server to see detailed processing information:

# Set logging level to DEBUG
export LOG_LEVEL=DEBUG
python api_server.py

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Translation Service Guide

🌐 Features

📋 API Endpoints

1. Single Text Translation

2. Batch Translation

3. Language Detection

4. Supported Languages

🔧 Request Parameters

Translation Request

Batch Translation Request

Language Detection Request

🌍 Supported Languages

💡 Usage Examples

Auto-Detection Translation

Batch Processing

Language Detection

API Selection

🔍 Error Handling

Common Error Responses

Error Handling Best Practices

🚀 Python Client Library

⚙️ Configuration

Environment Variables

API Models

🔒 Rate Limits & Best Practices

Rate Limiting

Performance Tips

Text Length Limits

🧪 Testing

📊 Response Fields

Translation Result Fields

🆘 Troubleshooting

Common Issues

Debug Mode

FilesExpand file tree

TRANSLATION_GUIDE.md

Latest commit

History

TRANSLATION_GUIDE.md

File metadata and controls

Translation Service Guide

🌐 Features

📋 API Endpoints

1. Single Text Translation

2. Batch Translation

3. Language Detection

4. Supported Languages

🔧 Request Parameters

Translation Request

Batch Translation Request

Language Detection Request

🌍 Supported Languages

💡 Usage Examples

Auto-Detection Translation

Batch Processing

Language Detection

API Selection

🔍 Error Handling

Common Error Responses

Error Handling Best Practices

🚀 Python Client Library

⚙️ Configuration

Environment Variables

API Models

🔒 Rate Limits & Best Practices

Rate Limiting

Performance Tips

Text Length Limits

🧪 Testing

📊 Response Fields

Translation Result Fields

🆘 Troubleshooting

Common Issues

Debug Mode