Metadata-Version: 2.4
Name: libretranslate-aio
Version: 0.1.3
Summary: Sync and async Python client for the LibreTranslate API (httpx)
Project-URL: Homepage, https://github.com/jbsanf/libretranslate-aio
Project-URL: Documentation, https://github.com/jbsanf/libretranslate-aio#readme
Project-URL: Repository, https://github.com/jbsanf/libretranslate-aio
Project-URL: Issues, https://github.com/jbsanf/libretranslate-aio/issues
Project-URL: Changelog, https://github.com/jbsanf/libretranslate-aio/blob/main/CHANGELOG.md
Author: João B. Santos
License-Expression: MIT
License-File: LICENSE
Keywords: api,async,httpx,libretranslate,translation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Description-Content-Type: text/markdown

# libretranslate-aio

**Synchronous** and **asynchronous** Python client for the [LibreTranslate API](https://libretranslate.com/docs/), built on [httpx](https://www.python-httpx.org/).

## Installation

```bash
pip install libretranslate-aio
```

## Quick start (sync)

```python
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)

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

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

```bash
# 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

```bash
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](https://pypi.org/manage/account/publishing/), configure *Trusted Publishing* pointing to the `publish.yml` workflow.
3. Create a `vX.Y.Z` release/tag — GitHub Actions publishes automatically.

## License

MIT
