libretranslate-aio

Synchronous and asynchronous Python client for the LibreTranslate API, built on httpx.

Installation

pip install libretranslate-aio

Quick start (sync)

from libretranslate_aio import LibreTranslate

with LibreTranslate() as client:
    result = client.translate("Hello world!", source="en", target="pt")
    print(result.translated_text)  # Olá mundo!

Quick start (async)

import asyncio
from libretranslate_aio import AsyncLibreTranslate


async def main():
    async with AsyncLibreTranslate() as client:
        result = await client.translate("Hello world!", source="en", target="pt")
        print(result.translated_text)


asyncio.run(main())

Configuration

LibreTranslate(
    base_url="https://libretranslate.com",  # or your self-hosted instance
    api_key="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",  # optional
    timeout=30.0,
)

Environment variables (used by the CLI):

• LIBRETRANSLATE_URL — API base URL
• LIBRETRANSLATE_API_KEY — API key

API

Method	Description
translate(q, source, target, format="text", alternatives=0)	Translate text (str or list[str])
translate_file(file, source, target)	Translate a file
detect(q)	Detect the text language
languages()	List supported languages
suggest(q, s, source, target)	Submit a translation suggestion
frontend_settings()	Frontend settings
health()	Health check (True if ok)

CLI

# Translate
libretranslate translate "Hello world!" --source en --target pt

# Detect language
libretranslate detect "Bonjour le monde"

# List languages
libretranslate languages

# Translate a file
libretranslate translate-file document.txt --source en --target es -o output.txt

# Global options
libretranslate --url https://my-instance.local --api-key KEY translate "Hi" -t pt

Development

uv sync --all-extras
uv run ruff check .
uv run pytest
uv build

Publishing to PyPI

1. Create the repository on GitHub and push.
2. On PyPI, configure Trusted Publishing pointing to the publish.yml workflow.
3. Create a vX.Y.Z release/tag — GitHub Actions publishes automatically.

License

MIT