Official Python client library for TranslatePlus API - Professional translation service for text, HTML, emails, subtitles, and i18n files
Project description
TranslatePlus Python Client
Official Python client library for TranslatePlus API - Professional translation service for text, HTML, emails, subtitles, and i18n files in 100+ languages.
Features
- ✅ Simple & Intuitive API - Easy to use, Pythonic interface
- ✅ All Endpoints Supported - Text, batch, HTML, email, subtitles, and i18n translation
- ✅ Concurrent Requests - Built-in support for parallel translations
- ✅ Error Handling - Comprehensive exception handling with detailed error messages
- ✅ Type Hints - Full type annotations for better IDE support
- ✅ Production Ready - Retry logic, rate limiting, and connection pooling
- ✅ 100+ Languages - Support for all languages available in TranslatePlus
Installation
pip install translateplus
For async support (optional):
pip install translateplus[async]
Quick Start
from translateplus import TranslatePlusClient
# Initialize client
client = TranslatePlusClient(api_key="your-api-key")
# Translate a single text
result = client.translate(
text="Hello, world!",
source="en",
target="fr"
)
print(result["translations"]["translation"])
# Output: "Bonjour le monde !"
# Translate multiple texts
texts = ["Hello", "Goodbye", "Thank you"]
result = client.translate_batch(texts, source="en", target="fr")
for translation in result["translations"]:
print(translation["translation"])
# Translate HTML
html = "<p>Hello <b>world</b></p>"
result = client.translate_html(html, source="en", target="fr")
print(result["html"])
# Output: "<p>Bonjour <b>monde</b></p>"
Documentation
Authentication
from translateplus import TranslatePlusClient
client = TranslatePlusClient(
api_key="your-api-key",
base_url="https://api.translateplus.io", # Optional, defaults to production
timeout=30, # Request timeout in seconds
max_retries=3, # Maximum retries for failed requests
max_concurrent=5, # Maximum concurrent requests
)
Text Translation
Single Translation
result = client.translate(
text="My client speaks only French. Will you translate for me?",
source="en",
target="fr"
)
print(result["translations"]["translation"])
print(result["translations"]["source"]) # Detected source language
print(result["translations"]["target"]) # Target language
Batch Translation
texts = [
"Hello, how are you?",
"What is your name?",
"Thank you very much!"
]
result = client.translate_batch(
texts=texts,
source="en",
target="fr"
)
print(f"Total: {result['total']}")
print(f"Successful: {result['successful']}")
print(f"Failed: {result['failed']}")
for translation in result["translations"]:
if translation["success"]:
print(f"{translation['text']} -> {translation['translation']}")
else:
print(f"Error: {translation.get('error', 'Unknown error')}")
Concurrent Translation
For better performance when translating many texts:
texts = ["Hello", "Goodbye", "Thank you", "Please", "Sorry"]
# Translate all texts concurrently
results = client.translate_concurrent(
texts=texts,
source="en",
target="fr",
max_workers=5 # Optional, defaults to max_concurrent
)
for result in results:
if "error" not in result:
print(result["translations"]["translation"])
HTML Translation
html_content = """
<html>
<body>
<h1>Welcome</h1>
<p>This is a <strong>test</strong> paragraph.</p>
</body>
</html>
"""
result = client.translate_html(
html=html_content,
source="en",
target="fr"
)
print(result["html"])
# HTML structure is preserved, only text content is translated
Email Translation
result = client.translate_email(
subject="Welcome to our service",
email_body="<p>Thank you for signing up!</p><p>We're excited to have you.</p>",
source="en",
target="fr"
)
print(result["subject"]) # Translated subject
print(result["html_body"]) # Translated HTML body
Subtitle Translation
srt_content = """1
00:00:01,000 --> 00:00:02,000
Hello world
2
00:00:03,000 --> 00:00:04,000
How are you?
"""
result = client.translate_subtitles(
content=srt_content,
format="srt", # or "vtt"
source="en",
target="fr"
)
print(result["content"])
# Timestamps are preserved, only text is translated
Language Detection
result = client.detect_language("Bonjour le monde")
print(result["language_detection"]["language"]) # "fr"
print(result["language_detection"]["confidence"]) # 0.99
Supported Languages
languages = client.get_supported_languages()
for code, name in languages["languages"].items():
print(f"{code}: {name}")
Account Information
summary = client.get_account_summary()
print(f"Credits remaining: {summary['credits_remaining']}")
print(f"Current plan: {summary['plan_name']}")
print(f"Concurrency limit: {summary['concurrency_limit']}")
i18n Translation Jobs
Create Job
result = client.create_i18n_job(
file_path="locales/en.json",
target_languages=["fr", "es", "de"],
source_language="en",
webhook_url="https://your-app.com/webhook" # Optional
)
job_id = result["job_id"]
print(f"Job created: {job_id}")
Check Job Status
status = client.get_i18n_job_status(job_id)
print(f"Status: {status['status']}") # pending, processing, completed, failed
print(f"Progress: {status.get('progress', 0)}%")
List Jobs
jobs = client.list_i18n_jobs(page=1, page_size=20)
for job in jobs["results"]:
print(f"Job {job['id']}: {job['status']}")
Download Translated File
# Download French translation
content = client.download_i18n_file(job_id, "fr")
with open("locales/fr.json", "wb") as f:
f.write(content)
Delete Job
client.delete_i18n_job(job_id)
Error Handling
The library provides specific exception types for different error scenarios:
from translateplus import (
TranslatePlusClient,
TranslatePlusError,
TranslatePlusAPIError,
TranslatePlusAuthenticationError,
TranslatePlusRateLimitError,
TranslatePlusInsufficientCreditsError,
TranslatePlusValidationError,
)
client = TranslatePlusClient(api_key="your-api-key")
try:
result = client.translate("Hello", source="en", target="fr")
except TranslatePlusAuthenticationError:
print("Invalid API key")
except TranslatePlusInsufficientCreditsError:
print("Insufficient credits")
except TranslatePlusRateLimitError:
print("Rate limit exceeded")
except TranslatePlusAPIError as e:
print(f"API error: {e.message}")
print(f"Status code: {e.status_code}")
except TranslatePlusError as e:
print(f"Error: {e}")
Context Manager
The client supports Python's context manager protocol:
with TranslatePlusClient(api_key="your-api-key") as client:
result = client.translate("Hello", source="en", target="fr")
print(result["translations"]["translation"])
# Session is automatically closed
Advanced Usage
Custom Base URL
For testing or using a different environment:
client = TranslatePlusClient(
api_key="your-api-key",
base_url="https://staging-api.translateplus.io"
)
Adjusting Concurrency
# Allow up to 10 concurrent requests
client = TranslatePlusClient(
api_key="your-api-key",
max_concurrent=10
)
Retry Configuration
# Retry up to 5 times for failed requests
client = TranslatePlusClient(
api_key="your-api-key",
max_retries=5
)
Examples
Translate a List of Documents
documents = [
"Document 1 content...",
"Document 2 content...",
"Document 3 content...",
]
results = client.translate_concurrent(
documents,
source="en",
target="fr"
)
for i, result in enumerate(results):
if "error" not in result:
print(f"Document {i+1}: {result['translations']['translation']}")
Translate HTML Email Template
email_template = """
<html>
<body>
<h1>Welcome {{name}}!</h1>
<p>Thank you for joining us.</p>
</body>
</html>
"""
# Translate to multiple languages
languages = ["fr", "es", "de"]
translations = {}
for lang in languages:
result = client.translate_html(email_template, source="en", target=lang)
translations[lang] = result["html"]
Batch Process Subtitles
import os
subtitle_files = ["subtitle1.srt", "subtitle2.srt", "subtitle3.srt"]
for file_path in subtitle_files:
with open(file_path, "r") as f:
content = f.read()
result = client.translate_subtitles(
content=content,
format="srt",
source="en",
target="fr"
)
# Save translated subtitle
output_path = file_path.replace(".srt", "_fr.srt")
with open(output_path, "w") as f:
f.write(result["content"])
Requirements
- Python 3.8+
- requests >= 2.31.0
License
MIT License - see LICENSE file for details.
Support
- Documentation: https://docs.translateplus.io
- API Reference: https://docs.translateplus.io/reference/v2/translation/translate
- Issues: GitHub Issues
- Email: support@translateplus.io
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Changelog
2.0.0 (2024-01-12)
- Initial release
- Support for all TranslatePlus API endpoints
- Concurrent translation support
- Comprehensive error handling
- Full type hints
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file translateplus_python-2.0.3.tar.gz.
File metadata
- Download URL: translateplus_python-2.0.3.tar.gz
- Upload date:
- Size: 16.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.14.2
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
6aed997bd30b3bf115797008886145b9ab3df99b777c17785d4b578fae00c2be
|
|
| MD5 |
541daf5374df93b657c5b93d0606bc20
|
|
| BLAKE2b-256 |
c7748000362541af4fe54ab36d0897bc0f4ceb89cfb8c65adbf9efc774de994b
|
File details
Details for the file translateplus_python-2.0.3-py3-none-any.whl.
File metadata
- Download URL: translateplus_python-2.0.3-py3-none-any.whl
- Upload date:
- Size: 11.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.14.2
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c47111cd798d2d06dae789b9d904ef2a874328b86270969ca457571acef643e7
|
|
| MD5 |
75df03569379210a932a15a1125ce453
|
|
| BLAKE2b-256 |
6de5c3bcc49e84743c9f8761daec4be8004d99f65084a62152997f91ea54463c
|
