Metadata-Version: 2.4
Name: linguin-api
Version: 0.1.0
Summary: Official Python client for the Linguin API: multilingual dictionary lookups, reverse dictionary, translation and UI localization.
Project-URL: Homepage, https://linguin.xyz/@api
Project-URL: Documentation, https://linguin.xyz/@api/docs
Project-URL: Repository, https://github.com/theastroscout/linguin-api-py
Author-email: Linguin <i@surfy.one>
License-Expression: MIT
License-File: LICENSE
Keywords: api,definitions,dictionary,i18n,language,linguin,localization,multilingual,reverse-dictionary,translation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# Linguin API for Python

Official Python client for the [Linguin API](https://linguin.xyz/@api): a multilingual dictionary and translation API. Look up any word or phrase in any language, run a reverse dictionary search, translate text and localize UI strings.

No dependencies, Python 3.8+.

- Full API reference: [linguin.xyz/@api/docs](https://linguin.xyz/@api/docs)
- Get an API key: [linguin.xyz/@api/access](https://linguin.xyz/@api/access)
- JavaScript client: [linguin-api-js](https://github.com/theastroscout/linguin-api-js)

## Install

```
pip install linguin-api
```

## Quickstart

```python
from linguin_api import Linguin

linguin = Linguin("YOUR_API_KEY")

entry = linguin.lookup("bonjour", lang="fr")
print(entry["items"][0]["definition"])
# The standard French daytime greeting, equivalent to 'hello' or 'good day'.
```

Every method returns the API response as a dict and raises `LinguinError` on failure.

## Dictionary

`lookup` returns the dictionary entry for a term. Mode `fast` (default) carries the definition, `deep` the complete entry with pronunciation, meanings, examples, synonyms, etymology and categories. Omit `lang` to autodetect the word's language.

```python
entry = linguin.lookup("Serendipität", lang="de", locale="en", mode="deep")
for meaning in entry["items"][0]["meanings"]:
	print(meaning["name"], "-", meaning["definition"])
```

`reverse` is a reverse dictionary: describe a meaning and get the words that fit. Mode `terms` (default) returns bare words, `fast` adds definitions, `deep` the complete entries.

```python
result = linguin.reverse("a doctor for animals", lang="en", mode="fast", limit=2)
for match in result["matches"]:
	print(match["term"], "-", match["definition"])
# veterinarian - A doctor who treats animals.
# vet - An informal short form of veterinarian, a doctor who treats animals.
```

## Translate

Mode `fast` is a quick pass, `deep` weighs context, idiom, register and tone. `live=True` cross-checks the wording against current web usage, `humanizer=True` rewrites the output so it reads like a person wrote it.

```python
result = linguin.translate("Hola, ¿cómo estás?", from_lang="es", to="en")
print(result["translation"])
# Hello, how are you?
```

## Localize

Bulk UI localization: a list of strings in, the list translated into one target language out, same length, same order, so it maps straight back onto your keys. Up to 1000 strings per call.

```python
result = linguin.localize(["Save", "Cancel", "Your changes were saved."], to="de")
print(result["strings"])
# ['Speichern', 'Abbrechen', 'Deine Änderungen wurden gespeichert.']
```

## Async delivery

Every generating method takes an optional `webhook`. With one, the call returns at once with a `req_id` and the result is POSTed to your URL when ready. A missed callback is recoverable: `get(req_id)` returns any result by its id, free.

```python
ticket = linguin.translate(long_text, to="ja", mode="deep", webhook="https://example.com/hook")
# {'req_id': '9f1c7b3e-...', 'status': 'queued'}

result = linguin.get(ticket["req_id"])
```

## Account

Billing is prepaid and per word or per call, with the exact charge attached to every response as `billed`. All account methods are free to call.

```python
linguin.balance()                     # {'balance': 24.9955}
linguin.report(since="2026-07-01")    # calls and cost per method, plus a total
linguin.topup(50)                     # Stripe payment link for a wallet top-up
linguin.refund()                      # unused paid balance back to your cards

new = linguin.key()                   # mint an additional key
linguin.revoke(prefix=new["prefix"])  # revoke one by full value or prefix
```

## Errors

A non-2xx response raises `LinguinError` with a stable `code` you can switch on, the HTTP `status` and a human `message`. Codes are listed in the [API reference](https://linguin.xyz/@api/docs).

```python
from linguin_api import Linguin, LinguinError

try:
	linguin.lookup("qwzrtplk")
except LinguinError as e:
	if e.code == "not_found":
		print("no such word")
	elif e.code == "rate_limited":
		...  # back off and retry
```

## License

MIT
