Glossaries

A glossary is a list of term pairs that the engine must honour. Use it for product names, legal terms, UI labels and anything where "close enough" is wrong.

Create a glossary

POST https://api.vizvuz.com/v1/glossaries

curl -X POST https://api.vizvuz.com/v1/glossaries \
  -H "Authorization: Bearer vz_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Billing terms",
        "source_lang": "DE",
        "target_lang": "EN",
        "entries": "Rechnung\tinvoice\nKunde\tclient\n"
      }'

{
  "glossary_id": "01J8ZC4M9XK3P7QW2NRT5V6YAB",
  "name": "Billing terms",
  "ready": true,
  "source_lang": "DE",
  "target_lang": "EN",
  "creation_time": "2026-09-01T10:00:00Z",
  "entry_count": 2
}

entries accepts two shapes. Tab-separated text, one pair per line:

Rechnung	invoice
Kunde	client

Or a JSON object, which is easier to build in code:

{ "entries": { "Rechnung": "invoice", "Kunde": "client" } }

ready is always true — glossaries are usable the moment the call returns. There is no build step to poll for.

Use it in a translation

curl -X POST https://api.vizvuz.com/v1/translate \
  -H "Authorization: Bearer vz_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
        "text": ["Die Rechnung liegt bei."],
        "source_lang": "DE",
        "target_lang": "EN-GB",
        "glossary_id": "01J8ZC4M9XK3P7QW2NRT5V6YAB"
      }'

source_lang is required whenever you pass glossary_id — without it there is nothing to match the glossary's language pair against, and the request answers 400 with validation_error.

The glossary's language pair must match the request. A glossary is stored against base languages, so a DE → EN glossary works for EN-GB and EN-US alike. A mismatch also answers 400 with validation_error.

List, inspect and export

curl https://api.vizvuz.com/v1/glossaries \
  -H "Authorization: Bearer vz_live_xxxxxxxx"

{ "glossaries": [ { "glossary_id": "01J8Z…", "name": "Billing terms", "ready": true,
                    "source_lang": "DE", "target_lang": "EN",
                    "creation_time": "2026-09-01T10:00:00Z", "entry_count": 2 } ] }

A single glossary: GET /v1/glossaries/{id}.

Its entries as tab-separated text: GET /v1/glossaries/{id}/entries. The response is text/tab-separated-values, so you can pipe it straight into a file.

Delete

curl -X DELETE https://api.vizvuz.com/v1/glossaries/01J8ZC4M9XK3P7QW2NRT5V6YAB \
  -H "Authorization: Bearer vz_live_xxxxxxxx"

Answers 204 with no body. Deletion is immediate and permanent. Translation requests that still reference the id answer 404 with glossary_not_found.

Supported pairs

curl https://api.vizvuz.com/v1/glossary-language-pairs \
  -H "Authorization: Bearer vz_live_xxxxxxxx"

{ "supported_languages": [ { "source_lang": "DE", "target_lang": "EN" } ] }

Every combination of two different base languages is supported — all 36 × 35 of them.

Limits and rules

Reaching the plan limit answers 403 with glossary_limit_reached.

How it affects caching

The glossary id and its version are part of the cache key. Editing a glossary raises its version, so the next translation is computed fresh rather than served from a stale cache. You never have to flush anything by hand.

Practical advice

• Keep glossaries small and specific. A glossary with 4,000 general words fights

the engine and makes the output worse, not better.

• One glossary per language pair per domain — "Billing DE→EN", "UI DE→EN" — beats

one giant list.

• Terms are matched as written. If your source text capitalises differently from

your glossary entry, add both spellings.

Last updated Sep 1, 2026, 12:00 AM