Official Python client library for TranslatePlus API - Professional translation service for text, HTML, emails, subtitles, and i18n files

Navigation

Verified details

These details have been verified by PyPI
Maintainers
Avatar for translateplus from gravatar.com translateplus
Meta

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT License (MIT)
  • Author: TranslatePlus
  • Tags translation , api , translate , multilingual , i18n , localization
  • Requires: Python >=3.8
  • Provides-Extra: async
Classifiers
Report project as malware

Project description

TranslatePlus Python Client

PyPI version Python 3.8+ License: MIT

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-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

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

Project details

Verified details

These details have been verified by PyPI
Maintainers
Avatar for translateplus from gravatar.com translateplus
Meta

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT License (MIT)
  • Author: TranslatePlus
  • Tags translation , api , translate , multilingual , i18n , localization
  • Requires: Python >=3.8
  • Provides-Extra: async
Classifiers

Release history Release notifications | RSS feed

2.0.7

This version

2.0.5

2.0.3

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

translateplus_python-2.0.5.tar.gz (16.5 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

translateplus_python-2.0.5-py3-none-any.whl (11.3 kB view details)

Uploaded Python 3

File details

Details for the file translateplus_python-2.0.5.tar.gz.

File metadata

  • Download URL: translateplus_python-2.0.5.tar.gz
  • Upload date:
  • Size: 16.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.14.2

File hashes

Hashes for translateplus_python-2.0.5.tar.gz
Algorithm Hash digest
SHA256 b6e464e7b16a15b2dc8988912f1884cfb6f61a3a2544137ecbe1d23f3b7acd10
MD5 6af9720310427ac4d0adcc7dd9277612
BLAKE2b-256 1331775bfe00cbd068fb8f27ac25b23edebb9cd344576615cd37549a918e1ff9

See more details on using hashes here.

File details

Details for the file translateplus_python-2.0.5-py3-none-any.whl.

File metadata

File hashes

Hashes for translateplus_python-2.0.5-py3-none-any.whl
Algorithm Hash digest
SHA256 de23ceed71f5f71801327dcc7d80180a263783b7de80bf2d626327cf2f99f742
MD5 366d6ffae9bbcb085e3ab9684837bc1e
BLAKE2b-256 2adb42a10dbdc637ac95306e417635ccaa90d737db87e65cbb75d8d7dc4696b8

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page