# 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
- ⚡ **Fast mode** for quick translations
- 🔧 **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
```bash
pip install lingodotdev
```
## 🎯 Quick Start
### Simple Translation
```python
import asyncio
from lingodotdev import LingoDotDevEngine
async def main():
# Quick one-off translation (handles context management automatically)
result = await LingoDotDevEngine.quick_translate(
"Hello, world!",
api_key="your-api-key",
target_locale="es"
)
print(result) # "¡Hola, mundo!"
asyncio.run(main())
```
### Context Manager (Recommended for Multiple Operations)
```python
import asyncio
from lingodotdev import LingoDotDevEngine
async def main():
config = {
"api_key": "your-api-key",
"api_url": "https://engine.lingo.dev" # Optional, defaults to this
}
async with LingoDotDevEngine(config) as engine:
# Translate text
text_result = await engine.localize_text(
"Hello, world!",
{"target_locale": "es"}
)
# Translate object with concurrent processing
obj_result = await engine.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)
```python
async def batch_example():
# Translate to multiple languages at once
results = await LingoDotDevEngine.quick_batch_translate(
"Welcome to our application",
api_key="your-api-key",
target_locales=["es", "fr", "de", "it"]
)
# Results: ["Bienvenido...", "Bienvenue...", "Willkommen...", "Benvenuto..."]
```
### Large Object Processing with Progress
```python
async def progress_example():
def progress_callback(progress, source_chunk, processed_chunk):
print(f"Progress: {progress}% - Processed {len(processed_chunk)} items")
large_content = {f"item_{i}": f"Content {i}" for i in range(1000)}
async with LingoDotDevEngine({"api_key": "your-api-key"}) as engine:
result = await engine.localize_object(
large_content,
{"target_locale": "es"},
progress_callback=progress_callback,
concurrent=True # Much faster for large objects
)
```
### Chat Translation
```python
async def chat_example():
chat_messages = [
{"name": "Alice", "text": "Hello everyone!"},
{"name": "Bob", "text": "How is everyone doing?"},
{"name": "Charlie", "text": "Great to see you all!"}
]
async with LingoDotDevEngine({"api_key": "your-api-key"}) as engine:
translated_chat = await engine.localize_chat(
chat_messages,
{"source_locale": "en", "target_locale": "es"}
)
# Names preserved, text translated
```
### Multiple Objects Concurrently
```python
async def concurrent_objects_example():
objects = [
{"title": "Welcome", "description": "Please sign in"},
{"error": "Invalid input", "help": "Check your email"},
{"success": "Account created", "next": "Continue to dashboard"}
]
async with LingoDotDevEngine({"api_key": "your-api-key"}) as engine:
results = await engine.batch_localize_objects(
objects,
{"target_locale": "fr"}
)
# All objects translated concurrently
```
### Language Detection
```python
async def detection_example():
async with LingoDotDevEngine({"api_key": "your-api-key"}) as engine:
detected = await engine.recognize_locale("Bonjour le monde")
print(detected) # "fr"
```
## ⚙️ Configuration Options
```python
config = {
"api_key": "your-api-key", # Required: Your API key
"api_url": "https://engine.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)
- **fast**: Enable fast mode for quicker translations
- **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
```python
async def error_handling_example():
try:
async with LingoDotDevEngine({"api_key": "invalid-key"}) as engine:
result = await engine.localize_text("Hello", {"target_locale": "es"})
except ValueError as e:
print(f"Invalid request: {e}")
except RuntimeError as e:
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](https://lingo.dev/docs)
- 🐛 [Issues](https://github.com/lingodotdev/sdk-python/issues)
- 💬 [Community](https://lingo.dev/discord)
Raw data
{
"_id": null,
"home_page": null,
"name": "lingodotdev",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "i18n, lingo.dev, localization, translation",
"author": null,
"author_email": "\"Lingo.dev Team\" <hi@lingo.dev>",
"download_url": "https://files.pythonhosted.org/packages/ec/1a/9ebc7b9d03862845e05c099c608bb3afb6f7beef0d6714874a03985af27d/lingodotdev-1.3.0.tar.gz",
"platform": null,
"description": "# Lingo.dev Python SDK\n\nA powerful async-first localization engine that supports various content types including plain text, objects, chat sequences, and HTML documents.\n\n## \u2728 Key Features\n\n- \ud83d\ude80 **Async-first design** for high-performance concurrent translations\n- \ud83d\udd00 **Concurrent processing** for dramatically faster bulk translations\n- \ud83c\udfaf **Multiple content types**: text, objects, chat messages, and more\n- \ud83c\udf10 **Auto-detection** of source languages\n- \u26a1 **Fast mode** for quick translations\n- \ud83d\udd27 **Flexible configuration** with progress callbacks\n- \ud83d\udce6 **Context manager** support for proper resource management\n\n## \ud83d\ude80 Performance Benefits\n\nThe async implementation provides significant performance improvements:\n- **Concurrent chunk processing** for large payloads\n- **Batch operations** for multiple translations\n- **Parallel API requests** instead of sequential ones\n- **Better resource management** with httpx\n\n## \ud83d\udce6 Installation\n\n```bash\npip install lingodotdev\n```\n\n## \ud83c\udfaf Quick Start\n\n### Simple Translation\n\n```python\nimport asyncio\nfrom lingodotdev import LingoDotDevEngine\n\nasync def main():\n # Quick one-off translation (handles context management automatically)\n result = await LingoDotDevEngine.quick_translate(\n \"Hello, world!\",\n api_key=\"your-api-key\",\n target_locale=\"es\"\n )\n print(result) # \"\u00a1Hola, mundo!\"\n\nasyncio.run(main())\n```\n\n### Context Manager (Recommended for Multiple Operations)\n\n```python\nimport asyncio\nfrom lingodotdev import LingoDotDevEngine\n\nasync def main():\n config = {\n \"api_key\": \"your-api-key\",\n \"api_url\": \"https://engine.lingo.dev\" # Optional, defaults to this\n }\n \n async with LingoDotDevEngine(config) as engine:\n # Translate text\n text_result = await engine.localize_text(\n \"Hello, world!\",\n {\"target_locale\": \"es\"}\n )\n \n # Translate object with concurrent processing\n obj_result = await engine.localize_object(\n {\n \"greeting\": \"Hello\",\n \"farewell\": \"Goodbye\",\n \"question\": \"How are you?\"\n },\n {\"target_locale\": \"es\"},\n concurrent=True # Process chunks concurrently for speed\n )\n\nasyncio.run(main())\n```\n\n## \ud83d\udd25 Advanced Usage\n\n### Batch Processing (Multiple Target Languages)\n\n```python\nasync def batch_example():\n # Translate to multiple languages at once\n results = await LingoDotDevEngine.quick_batch_translate(\n \"Welcome to our application\",\n api_key=\"your-api-key\",\n target_locales=[\"es\", \"fr\", \"de\", \"it\"]\n )\n # Results: [\"Bienvenido...\", \"Bienvenue...\", \"Willkommen...\", \"Benvenuto...\"]\n```\n\n### Large Object Processing with Progress\n\n```python\nasync def progress_example():\n def progress_callback(progress, source_chunk, processed_chunk):\n print(f\"Progress: {progress}% - Processed {len(processed_chunk)} items\")\n\n large_content = {f\"item_{i}\": f\"Content {i}\" for i in range(1000)}\n \n async with LingoDotDevEngine({\"api_key\": \"your-api-key\"}) as engine:\n result = await engine.localize_object(\n large_content,\n {\"target_locale\": \"es\"},\n progress_callback=progress_callback,\n concurrent=True # Much faster for large objects\n )\n```\n\n### Chat Translation\n\n```python\nasync def chat_example():\n chat_messages = [\n {\"name\": \"Alice\", \"text\": \"Hello everyone!\"},\n {\"name\": \"Bob\", \"text\": \"How is everyone doing?\"},\n {\"name\": \"Charlie\", \"text\": \"Great to see you all!\"}\n ]\n \n async with LingoDotDevEngine({\"api_key\": \"your-api-key\"}) as engine:\n translated_chat = await engine.localize_chat(\n chat_messages,\n {\"source_locale\": \"en\", \"target_locale\": \"es\"}\n )\n # Names preserved, text translated\n```\n\n### Multiple Objects Concurrently\n\n```python\nasync def concurrent_objects_example():\n objects = [\n {\"title\": \"Welcome\", \"description\": \"Please sign in\"},\n {\"error\": \"Invalid input\", \"help\": \"Check your email\"},\n {\"success\": \"Account created\", \"next\": \"Continue to dashboard\"}\n ]\n \n async with LingoDotDevEngine({\"api_key\": \"your-api-key\"}) as engine:\n results = await engine.batch_localize_objects(\n objects,\n {\"target_locale\": \"fr\"}\n )\n # All objects translated concurrently\n```\n\n### Language Detection\n\n```python\nasync def detection_example():\n async with LingoDotDevEngine({\"api_key\": \"your-api-key\"}) as engine:\n detected = await engine.recognize_locale(\"Bonjour le monde\")\n print(detected) # \"fr\"\n```\n\n## \u2699\ufe0f Configuration Options\n\n```python\nconfig = {\n \"api_key\": \"your-api-key\", # Required: Your API key\n \"api_url\": \"https://engine.lingo.dev\", # Optional: API endpoint\n \"batch_size\": 25, # Optional: Items per batch (1-250)\n \"ideal_batch_item_size\": 250 # Optional: Target words per batch (1-2500)\n}\n```\n\n## \ud83c\udf9b\ufe0f Method Parameters\n\n### Translation Parameters\n- **source_locale**: Source language code (auto-detected if None)\n- **target_locale**: Target language code (required)\n- **fast**: Enable fast mode for quicker translations\n- **reference**: Reference translations for context\n- **concurrent**: Process chunks concurrently (faster, but no progress callbacks)\n\n### Performance Options\n- **concurrent=True**: Enables parallel processing of chunks\n- **progress_callback**: Function to track progress (disabled with concurrent=True)\n\n## \ud83d\udd27 Error Handling\n\n```python\nasync def error_handling_example():\n try:\n async with LingoDotDevEngine({\"api_key\": \"invalid-key\"}) as engine:\n result = await engine.localize_text(\"Hello\", {\"target_locale\": \"es\"})\n except ValueError as e:\n print(f\"Invalid request: {e}\")\n except RuntimeError as e:\n print(f\"API error: {e}\")\n```\n\n## \ud83d\ude80 Performance Tips\n\n1. **Use `concurrent=True`** for large objects or multiple chunks\n2. **Use `batch_localize_objects()`** for multiple objects\n3. **Use context managers** for multiple operations\n4. **Use `quick_translate()`** for one-off translations\n5. **Adjust `batch_size`** based on your content structure\n\n## \ud83e\udd1d Migration from Sync Version\n\nThe async version is a drop-in replacement with these changes:\n- Add `async`/`await` to all method calls\n- Use `async with` for context managers\n- All methods now return awaitable coroutines\n\n## \ud83d\udcda API Reference\n\n### Core Methods\n- `localize_text(text, params)` - Translate text strings\n- `localize_object(obj, params)` - Translate dictionary objects\n- `localize_chat(chat, params)` - Translate chat messages\n- `batch_localize_text(text, params)` - Translate to multiple languages\n- `batch_localize_objects(objects, params)` - Translate multiple objects\n- `recognize_locale(text)` - Detect language\n- `whoami()` - Get API account info\n\n### Convenience Methods\n- `quick_translate(content, api_key, target_locale, ...)` - One-off translation\n- `quick_batch_translate(content, api_key, target_locales, ...)` - Batch translation\n\n## \ud83d\udcc4 License\n\nApache-2.0 License\n\n## \ud83e\udd16 Support\n\n- \ud83d\udcda [Documentation](https://lingo.dev/docs)\n- \ud83d\udc1b [Issues](https://github.com/lingodotdev/sdk-python/issues)\n- \ud83d\udcac [Community](https://lingo.dev/discord)",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Lingo.dev Python SDK",
"version": "1.3.0",
"project_urls": {
"Documentation": "https://lingo.dev/docs",
"Homepage": "https://lingo.dev",
"Issues": "https://github.com/lingodotdev/sdk-python/issues",
"Repository": "https://github.com/lingodotdev/sdk-python"
},
"split_keywords": [
"i18n",
" lingo.dev",
" localization",
" translation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "37925748f1a86abef8a965abc6a37a24276b8557bf5d46d8f92023ad32f6a095",
"md5": "3d545185bcf6441a8565c736aee20c20",
"sha256": "5a56888f6a9d020f77316345409d8907c25bb2eba6bd6d2e4de21bd814d3c881"
},
"downloads": -1,
"filename": "lingodotdev-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3d545185bcf6441a8565c736aee20c20",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 12846,
"upload_time": "2025-07-22T13:33:05",
"upload_time_iso_8601": "2025-07-22T13:33:05.914183Z",
"url": "https://files.pythonhosted.org/packages/37/92/5748f1a86abef8a965abc6a37a24276b8557bf5d46d8f92023ad32f6a095/lingodotdev-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ec1a9ebc7b9d03862845e05c099c608bb3afb6f7beef0d6714874a03985af27d",
"md5": "e6cdc7d22047b2542ef253f0a17a5186",
"sha256": "a53ecb00b6cc393cf4d296c6d7b54e8634067c6d4b536339330d7d7896ffe867"
},
"downloads": -1,
"filename": "lingodotdev-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "e6cdc7d22047b2542ef253f0a17a5186",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 18713,
"upload_time": "2025-07-22T13:33:07",
"upload_time_iso_8601": "2025-07-22T13:33:07.256196Z",
"url": "https://files.pythonhosted.org/packages/ec/1a/9ebc7b9d03862845e05c099c608bb3afb6f7beef0d6714874a03985af27d/lingodotdev-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-22 13:33:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lingodotdev",
"github_project": "sdk-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "lingodotdev"
}
JSON
