LibreTranslate Python Bindings

Warnings

• gotcha Public LibreTranslate instances (e.g., `libretranslate.com`) often require an API key for translation requests, which may not be immediately obvious. Without a valid key, requests can result in HTTP errors like `403 Forbidden` or `400 Bad Request`.
  Fix: Obtain an API key from a managed LibreTranslate service or ensure you are connecting to a self-hosted instance configured not to require an API key. Pass the key to the `LibreTranslateAPI` constructor using the `api_key` argument, preferably via an environment variable.
• gotcha `libretranslatepy` is a client library only. It does not include a LibreTranslate server. To perform translations, you must have access to a running LibreTranslate server instance, either self-hosted or a public one. Attempting to use the library without a reachable server will result in connection errors.
  Fix: Ensure a LibreTranslate server is running and accessible at the URL provided to `LibreTranslateAPI`. If self-hosting, follow the LibreTranslate server installation guides. If using a public instance, verify its uptime and accessibility.
• gotcha Translation quality can vary, and the underlying LibreTranslate models might occasionally return the original input, a partial translation, or corrupted text if specific language models are missing, faulty, or if the input contains complex structures (e.g., specific HTML, long numerical sequences, or placeholders). This can happen without explicit error messages from the API.
  Fix: Implement client-side validation on translated output (e.g., checking for character set changes, length differences, or known placeholder integrity). Ensure your LibreTranslate server has up-to-date and appropriate language models installed for your desired language pairs. Consider pre-processing text to handle sensitive elements (like HTML tags) before sending to the API.
• deprecated While `libretranslatepy`'s `setup.py` declares compatibility with Python `>=2.6`, Python 2.x is officially End-of-Life and is not supported by the core LibreTranslate server project (which requires Python `>=3.8`). Using `libretranslatepy` with Python 2.x is highly discouraged and likely to lead to compatibility issues or unsupported behavior with modern LibreTranslate servers.
  Fix: Always use Python 3.8 or newer for development and deployment involving `libretranslatepy` to ensure compatibility and leverage ongoing community support.

Install

• pip install libretranslatepy Install with pip

Imports

• LibreTranslateAPI

  from libretranslatepy import LibreTranslateAPI

Quickstart

This quickstart demonstrates how to initialize the `LibreTranslateAPI` client, translate text, detect language, and list supported languages. It highlights the use of environment variables for configuring the server URL and API key, which is crucial for interacting with public LibreTranslate instances that often require authentication.

import os
from libretranslatepy import LibreTranslateAPI

# Configure LibreTranslate server URL and optional API Key
# For public instances like libretranslate.com, an API key is often required.
# For a self-hosted instance, an API key might be optional depending on server configuration.
LIBRETRANSLATE_URL = os.environ.get('LIBRETRANSLATE_URL', 'https://libretranslate.com/')
LIBRETRANSLATE_API_KEY = os.environ.get('LIBRETRANSLATE_API_KEY', None)

# Initialize the API client
lt = LibreTranslateAPI(LIBRETRANSLATE_URL, api_key=LIBRETRANSLATE_API_KEY)

# Translate text from English to Spanish
text_to_translate = "Hello, how are you?"
source_lang = "en"
target_lang = "es"

try:
    translated_text = lt.translate(text_to_translate, source_lang, target_lang)
    print(f"Original ({source_lang}): {text_to_translate}")
    print(f"Translated ({target_lang}): {translated_text}")

    # Detect language
    detection_result = lt.detect("Hola mundo")
    print(f"Detected language for 'Hola mundo': {detection_result}")

    # List available languages
    languages = lt.languages()
    # print(f"Available languages: {languages}") # Uncomment to see all
    print(f"Number of available languages: {len(languages)}")

except Exception as e:
    print(f"An error occurred: {e}")
    if 'HTTP Error 403: Forbidden' in str(e) or 'HTTP Error 400: Bad Request' in str(e):
        print("\nHint: Public LibreTranslate instances often require an API key.")
        print("Set the LIBRETRANSLATE_API_KEY environment variable or ensure your server doesn't require one.")