Metadata-Version: 2.4
Name: tarjamli
Version: 0.1.1
Summary: Python client for Tarjamli translation through Sawalni API
Author-email: Omar Kamali <omar@omneitylabs.com>
License-Expression: MIT
Project-URL: Homepage, https://api.sawalni.com
Project-URL: Issues, https://github.com/omneity-labs/starter-translation/issues
Project-URL: Examples, https://github.com/omneity-labs/starter-translation
Keywords: translation,darija,amazigh,tarjamli,sawalni
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# tarjamli

A small Python client for Tarjamli translation through the [Sawalni API](https://api.sawalni.com). Translate text, convert Darija between Arabic and Latin scripts, and give the translation context about tone, gender or address forms.

Python 3.10+. No runtime dependencies.

## Install

```sh
pip install tarjamli
```

Set your Sawalni API key:

```sh
export SAWALNI_API_KEY="your-key"
```

## Translate

```python
from tarjamli import Tarjamli

client = Tarjamli()
result = client.translate(
    "واش تقدر تصيفط ليا الدوسي؟",
    source="ary_Arab",
    target="fra_Latn",
    instructions="Address one person formally using vous.",
)
print(result.text)
```

Pass your own text. Remove `instructions` for ordinary translation, or change it to supply context. The API field is `instructions`; tone and gender are not separate parameters.

## Convert Darija scripts

```python
result = client.translate(
    "سلام، كيف داير؟",
    source="ary_Arab",
    target="ary_Latn",
)
print(result.text)
```

Reverse the source and target for Latin → Arabic. Use `client.languages()` to list supported language and script codes, including `shi_Latn` for Tachelhit and `zgh_Tfng` for Tamazight in Tifinagh.

## CLI

```sh
tarjamli translate --text 'واش تقدر تصيفط ليا الدوسي؟' --source ary_Arab --target fra_Latn --instructions 'Address one person formally using vous.'
tarjamli languages
```

Use `--text -` to read standard input. Add `--json` for the full API response.

## Configuration and results

`Tarjamli(api_key=None, timeout=180)` reads `SAWALNI_API_KEY` when no key is passed. Keep keys in server-side code or your terminal environment. The package does not load `.env` files.

`translate(text, *, source, target, instructions="", model="tarjamli-mini-v4")` returns a `Translation` with `text`, `source`, `target`, `model`, and `raw` (the full response, including usage when supplied). This release supports the checked Mini model only.

Each call sends one request to `POST https://api.sawalni.com/v1/language/translate`. Live requests use your API balance. There are no automatic retries.

## Errors

```python
from tarjamli import AuthenticationError, RateLimitError, TranslationError

try:
    result = client.translate("Hello", source="eng_Latn", target="ary_Arab")
except AuthenticationError:
    # Check your key and model access.
    raise
except RateLimitError:
    # Decide when to retry in your application.
    raise
except TranslationError:
    # Includes incomplete responses, connection errors and unexpected identities.
    raise
```

Invalid local input raises `ValueError`. Incomplete output raises `IncompleteTranslationError`, a subclass of `TranslationError`. The client checks the returned model and language codes before returning a result.

[More examples](https://github.com/omneity-labs/starter-translation) · [API documentation](https://api.sawalni.com/docs) · [MIT license](LICENSE).
