Glossaries

Overview#

Glossaries enforce consistent translation of domain-specific terms. When a source term appears in the input text and matches a glossary entry, Translate uses the defined target term instead of relying on the AI model's general knowledge. This is critical for legal terminology, government titles, technical standards, and institutional names that must be translated identically every time.

Glossary Structure#

Glossaries are collections of term entries, each scoped to a source language, target language, and domain. A single glossary might contain all legal terms for Arabic-to-English translation, while another holds technical terminology for the same language pair.

Create a Glossary#

curl -X POST http://localhost:8012/api/v1/glossaries \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "GCC Legal Terms",
    "description": "Standard legal terminology for government contracts",
    "source_lang": "ar",
    "target_lang": "en",
    "domain": "legal"
  }'

Add Entries to a Glossary#

curl -X POST http://localhost:8012/api/v1/glossaries/{glossary_id}/entries \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "source_term": "عقد حكومي",
    "target_term": "Government Contract"
  }'

List Glossary Entries#

curl "http://localhost:8012/api/v1/glossaries/{glossary_id}/entries?page=1&page_size=50" \
  -H "Authorization: Bearer $TOKEN"

Managing Glossaries#

List All Glossaries#

Filter by domain, source language, or target language:

curl "http://localhost:8012/api/v1/glossaries?domain=legal&source_lang=ar" \
  -H "Authorization: Bearer $TOKEN"

Get Glossary Details#

curl http://localhost:8012/api/v1/glossaries/{glossary_id} \
  -H "Authorization: Bearer $TOKEN"

Returns the glossary metadata along with all its entries.

Update a Glossary#

curl -X PUT http://localhost:8012/api/v1/glossaries/{glossary_id} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "GCC Legal Terms v2",
    "description": "Updated legal terminology with 2024 regulatory terms"
  }'

Delete a Glossary#

Deleting a glossary removes it and all its entries (requires admin role):

curl -X DELETE http://localhost:8012/api/v1/glossaries/{glossary_id} \
  -H "Authorization: Bearer $TOKEN"

Entry Management#

Individual glossary entries can be updated or deleted:

Update an Entry#

curl -X PUT http://localhost:8012/api/v1/glossaries/{glossary_id}/entries/{entry_id} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "target_term": "Governmental Contract"
  }'

Delete an Entry#

curl -X DELETE http://localhost:8012/api/v1/glossaries/{glossary_id}/entries/{entry_id} \
  -H "Authorization: Bearer $TOKEN"

Domain Scoping#

Glossary terms are scoped to a domain. A term like "act" translates differently in legal context (law/statute) versus general context (action). By scoping glossaries to domains, Translate applies the correct term based on the translation request's domain parameter.

Supported domains: