Official Python client library for Translation API - Professional translation service for text, HTML, emails, subtitles, and i18n files in 100+ languages.
- âś… 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
pip install translateplus-pythonFor async support (optional):
pip install translateplus-python[async]Note: The package name on PyPI is translateplus-python, but the import name is still translateplus:
from translateplus import TranslatePlusClient # Import name stays the samefrom 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>"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
)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 languagetexts = [
"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')}")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_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 translatedresult = 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 bodysrt_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 translatedresult = client.detect_language("Bonjour le monde")
print(result["language_detection"]["language"]) # "fr"
print(result["language_detection"]["confidence"]) # 0.99languages = client.get_supported_languages()
for code, name in languages["languages"].items():
print(f"{code}: {name}")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']}")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}")status = client.get_i18n_job_status(job_id)
print(f"Status: {status['status']}") # pending, processing, completed, failed
print(f"Progress: {status.get('progress', 0)}%")jobs = client.list_i18n_jobs(page=1, page_size=20)
for job in jobs["results"]:
print(f"Job {job['id']}: {job['status']}")# Download French translation
content = client.download_i18n_file(job_id, "fr")
with open("locales/fr.json", "wb") as f:
f.write(content)client.delete_i18n_job(job_id)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}")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 closedFor testing or using a different environment:
client = TranslatePlusClient(
api_key="your-api-key",
base_url="https://staging-api.translateplus.io"
)# Allow up to 10 concurrent requests
client = TranslatePlusClient(
api_key="your-api-key",
max_concurrent=10
)# Retry up to 5 times for failed requests
client = TranslatePlusClient(
api_key="your-api-key",
max_retries=5
)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']}")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"]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"])- Python 3.8+
- requests >= 2.31.0
MIT License - see LICENSE file for details.
TranslatePlus provides official client libraries for multiple programming languages:
- JavaScript/TypeScript: translateplus-js - Official npm package
- PHP: translateplus-php - Official Composer package
All libraries provide the same comprehensive API support and features.
- Documentation: https://docs.translateplus.io
- API Reference: https://docs.translateplus.io/reference/v2/translation/translate
- Issues: GitHub Issues
- Email: support@translateplus.io
Contributions are welcome! Please feel free to submit a Pull Request.
- Initial release
- Support for all TranslatePlus API endpoints
- Concurrent translation support
- Comprehensive error handling
- Full type hints