TranslatePlus Python Client
Official Python client library for Translation 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-python
For 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 same
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
Metadata
Release files for translateplus-python 2.0.7
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| translateplus_python-2.0.7.tar.gz | 16.6 kB | Without provenance | Details for translateplus_python-2.0.7.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| translateplus_python-2.0.7-py3-none-any.whl | Python 3 | none | any | Details for translateplus_python-2.0.7-py3-none-any.whl |
Total release size: 27.8 kB
Release files / translateplus_python-2.0.7.tar.gz
| Download URL | translateplus_python-2.0.7.tar.gz |
|---|---|
| Size | 16.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
21b67856a8c89bdf7ad37f97d17b7649827b43868421df83ddc024da8d30ab20
|
|
BLAKE2b-256 checksum How to use checksums |
004da5067af12ed05c9d6de620b19d7a28830db54aaa16a9830fd98e28082b34
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.2
|
Release files / translateplus_python-2.0.7-py3-none-any.whl
| Download URL | translateplus_python-2.0.7-py3-none-any.whl |
|---|---|
| Size | 11.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dca1a60c75b8ed0f05617b5806a27c7dca717b178ea4495a0043497e67e13db3
|
|
BLAKE2b-256 checksum How to use checksums |
c745d3ecae5010863cf77a59cef164bf5cfcaad2cb7c61efc573c025be056418
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.2
|
Security for translateplus-python 2.0.7
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.