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

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

This version

2.0.7

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.7.tar.gz (16.6 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.7-py3-none-any.whl (11.3 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: translateplus_python-2.0.7.tar.gz
  • Upload date:
  • Size: 16.6 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.7.tar.gz
Algorithm Hash digest
SHA256 21b67856a8c89bdf7ad37f97d17b7649827b43868421df83ddc024da8d30ab20
MD5 46dd72b51c5cd9554c8a4829e882816b
BLAKE2b-256 004da5067af12ed05c9d6de620b19d7a28830db54aaa16a9830fd98e28082b34

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for translateplus_python-2.0.7-py3-none-any.whl
Algorithm Hash digest
SHA256 dca1a60c75b8ed0f05617b5806a27c7dca717b178ea4495a0043497e67e13db3
MD5 06fddd70875c14040a37f2716bb2f28e
BLAKE2b-256 c745d3ecae5010863cf77a59cef164bf5cfcaad2cb7c61efc573c025be056418

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