linguin-api 0.1.0

Official Python client for the Linguin API: multilingual dictionary lookups, reverse dictionary, translation and UI localization.

Linguin API for Python

Official Python client for the Linguin 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
• Get an API key: linguin.xyz/@api/access
• JavaScript client: linguin-api-js

Install

pip install linguin-api

Quickstart

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.

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.

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.

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.

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.

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.

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.

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