Lingo.dev Python SDK

A powerful async-first localization engine that supports various content types including plain text, objects, chat sequences, and HTML documents.

✨ Key Features

• 🚀 Async-first design for high-performance concurrent translations
• 🔀 Concurrent processing for dramatically faster bulk translations
• 🎯 Multiple content types: text, objects, chat messages, and more
• 🌐 Auto-detection of source languages
• 🔧 Flexible configuration with progress callbacks
• 📦 Context manager support for proper resource management

🚀 Performance Benefits

The async implementation provides significant performance improvements:

• Concurrent chunk processing for large payloads
• Batch operations for multiple translations
• Parallel API requests instead of sequential ones
• Better resource management with httpx

📦 Installation

pip install lingodotdev

🎯 Quick Start

Simple Translation

importasynciofromlingodotdevimportLingoDotDevEngineasyncdefmain():
# Quick one-off translation (handles context management automatically)result=awaitLingoDotDevEngine.quick_translate(
"Hello, world!",
api_key="your-api-key",
engine_id="your-engine-id",
target_locale="es"
)
print(result) # "¡Hola, mundo!"asyncio.run(main())

Context Manager (Recommended for Multiple Operations)

importasynciofromlingodotdevimportLingoDotDevEngineasyncdefmain():
config= {
"api_key": "your-api-key",
"engine_id": "your-engine-id", # Optional
}
asyncwithLingoDotDevEngine(config) asengine:
# Translate texttext_result=awaitengine.localize_text(
"Hello, world!",
{"target_locale": "es"}
)
# Translate object with concurrent processingobj_result=awaitengine.localize_object(
{
"greeting": "Hello",
"farewell": "Goodbye",
"question": "How are you?"
},
{"target_locale": "es"},
concurrent=True# Process chunks concurrently for speed
)
asyncio.run(main())

🔥 Advanced Usage

Batch Processing (Multiple Target Languages)

asyncdefbatch_example():
# Translate to multiple languages at onceresults=awaitLingoDotDevEngine.quick_batch_translate(
"Welcome to our application",
api_key="your-api-key",
engine_id="your-engine-id",
target_locales=["es", "fr", "de", "it"]
)
# Results: ["Bienvenido...", "Bienvenue...", "Willkommen...", "Benvenuto..."]

Large Object Processing with Progress

asyncdefprogress_example():
defprogress_callback(progress, source_chunk, processed_chunk):
print(f"Progress: {progress}% - Processed {len(processed_chunk)} items")
large_content= {f"item_{i}": f"Content {i}"foriinrange(1000)}
asyncwithLingoDotDevEngine({"api_key": "your-api-key", "engine_id": "your-engine-id"}) asengine:
result=awaitengine.localize_object(
large_content,
{"target_locale": "es"},
progress_callback=progress_callback,
concurrent=True# Much faster for large objects
)

Chat Translation

asyncdefchat_example():
chat_messages= [
{"name": "Alice", "text": "Hello everyone!"},
{"name": "Bob", "text": "How is everyone doing?"},
{"name": "Charlie", "text": "Great to see you all!"}
]
asyncwithLingoDotDevEngine({"api_key": "your-api-key", "engine_id": "your-engine-id"}) asengine:
translated_chat=awaitengine.localize_chat(
chat_messages,
{"source_locale": "en", "target_locale": "es"}
)
# Names preserved, text translated

Multiple Objects Concurrently

asyncdefconcurrent_objects_example():
objects= [
{"title": "Welcome", "description": "Please sign in"},
{"error": "Invalid input", "help": "Check your email"},
{"success": "Account created", "next": "Continue to dashboard"}
]
asyncwithLingoDotDevEngine({"api_key": "your-api-key", "engine_id": "your-engine-id"}) asengine:
results=awaitengine.batch_localize_objects(
objects,
{"target_locale": "fr"}
)
# All objects translated concurrently

Language Detection

asyncdefdetection_example():
asyncwithLingoDotDevEngine({"api_key": "your-api-key", "engine_id": "your-engine-id"}) asengine:
detected=awaitengine.recognize_locale("Bonjour le monde")
print(detected) # "fr"

⚙️ Configuration Options

config= {
"api_key": "your-api-key", # Required: Your API key"engine_id": "your-engine-id", # Optional: Your engine ID"api_url": "https://api.lingo.dev", # Optional: API endpoint"batch_size": 25, # Optional: Items per batch (1-250)"ideal_batch_item_size": 250# Optional: Target words per batch (1-2500)
}

🎛️ Method Parameters

Translation Parameters

• source_locale: Source language code (auto-detected if None)
• target_locale: Target language code (required)
• reference: Reference translations for context
• concurrent: Process chunks concurrently (faster, but no progress callbacks)

Performance Options

• concurrent=True: Enables parallel processing of chunks
• progress_callback: Function to track progress (disabled with concurrent=True)

🔧 Error Handling

asyncdeferror_handling_example():
try:
asyncwithLingoDotDevEngine({"api_key": "invalid-key", "engine_id": "your-engine-id"}) asengine:
result=awaitengine.localize_text("Hello", {"target_locale": "es"})
exceptValueErrorase:
print(f"Invalid request: {e}")
exceptRuntimeErrorase:
print(f"API error: {e}")

🚀 Performance Tips

1. Use concurrent=True for large objects or multiple chunks
2. Use batch_localize_objects() for multiple objects
3. Use context managers for multiple operations
4. Use quick_translate() for one-off translations
5. Adjust batch_size based on your content structure

🤝 Migration from Sync Version

The async version is a drop-in replacement with these changes:

• Add async/await to all method calls
• Use async with for context managers
• All methods now return awaitable coroutines

📚 API Reference

Core Methods

• localize_text(text, params) - Translate text strings
• localize_object(obj, params) - Translate dictionary objects
• localize_chat(chat, params) - Translate chat messages
• batch_localize_text(text, params) - Translate to multiple languages
• batch_localize_objects(objects, params) - Translate multiple objects
• recognize_locale(text) - Detect language
• whoami() - Get API account info

Convenience Methods

• quick_translate(content, api_key, target_locale, ...) - One-off translation
• quick_batch_translate(content, api_key, target_locales, ...) - Batch translation

📄 License

Apache-2.0 License

🤖 Support

• 📚 Documentation
• 🐛 Issues
• 💬 Community