Glossary Support

Glossaries let you enforce consistent terminology in your translations. You can pass glossary terms inline with each request, or store them server-side and reference them by ID.

Use Cases

• Brand names: "Acme Portal" should always stay "Acme Portal" (or translate to a specific localized name)
• Product terms: "Dashboard" → "Overzichtspagina" (instead of generic "Dashboard")
• Industry jargon: "Sprint" → "Sprint" (keep Agile terminology untranslated)
• Legal terms: Ensure consistent legal terminology across documents

Request Format

Add a glossary array to your translation request body:

{
  "q": "Navigate to the Dashboard and check your Sprint progress.",
  "target": "nl",
  "glossary": [
    { "source": "Dashboard", "target": "Overzichtspagina" },
    { "source": "Sprint", "target": "Sprint" }
  ]
}

Response

{
  "data": {
    "translations": [
      {
        "translatedText": "Navigeer naar de Overzichtspagina en bekijk je Sprint-voortgang."
      }
    ]
  }
}

Without the glossary, "Dashboard" might be translated as "Dashboard" (kept as-is) or "Controlepaneel", and the result would be inconsistent.

Glossary Entry Format

Each entry in the glossary array must have:

Field	Type	Required	Description
source	string	Yes	The term in the source language
target	string	Yes	The required translation for this term

Examples

Python SDK

from langbly import Langbly

client = Langbly(api_key="your-key")

result = client.translate(
    q="Check your Dashboard for Sprint updates.",
    target="nl",
    glossary=[
        {"source": "Dashboard", "target": "Overzichtspagina"},
        {"source": "Sprint", "target": "Sprint"},
    ]
)

Node.js SDK

import { Langbly } from 'langbly';

const client = new Langbly({ apiKey: 'your-key' });

const result = await client.translate({
  q: 'Check your Dashboard for Sprint updates.',
  target: 'nl',
  glossary: [
    { source: 'Dashboard', target: 'Overzichtspagina' },
    { source: 'Sprint', target: 'Sprint' },
  ],
});

cURL

curl -X POST https://api.langbly.com/language/translate/v2 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "Check your Dashboard for Sprint updates.",
    "target": "nl",
    "glossary": [
      {"source": "Dashboard", "target": "Overzichtspagina"},
      {"source": "Sprint", "target": "Sprint"}
    ]
  }'

Stored Glossaries

Instead of passing glossary entries with every request, you can create a stored glossary and reference it by ID. This is useful when you have a large set of terms that you reuse across many translation requests.

Create a Glossary

curl -X POST https://api.langbly.com/v2/glossaries \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product terms",
    "sourceLang": "en",
    "targetLang": "nl",
    "entries": [
      {"source": "Dashboard", "target": "Overzichtspagina"},
      {"source": "Sprint", "target": "Sprint"},
      {"source": "Backlog", "target": "Achterstand"}
    ]
  }'

Use a Stored Glossary

Reference the glossary by ID in text translation:

{
  "q": "Check the Dashboard for Sprint updates.",
  "target": "nl",
  "glossaryId": "your-glossary-id"
}

Or in document translation:

curl -X POST https://api.langbly.com/v2/document/translate \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@report.docx" \
  -F "target=nl" \
  -F "glossaryId=your-glossary-id"

If you pass both an inline glossary and a glossaryId, the inline glossary takes precedence.

Manage Glossaries

Method	Endpoint	Description
GET	/v2/glossaries	List your glossaries
GET	/v2/glossaries/:id	Get a specific glossary
POST	/v2/glossaries	Create a new glossary
PUT	/v2/glossaries/:id	Update a glossary
DELETE	/v2/glossaries/:id	Delete a glossary

Limits

Inline glossary (per request): maximum 200 entries.

Stored glossaries depend on your plan:

	Free	Paid API
Glossaries	1	100
Entries per glossary	10	5,000

• Empty source or target values are silently ignored

Caching

Glossary affects the cache key. Two requests with the same text but different glossaries will produce separate cache entries. Requests without a glossary still use the regular cache.

Tips

• Case sensitivity: Glossary matching is case-sensitive. Include both "dashboard" and "Dashboard" if you need both matched.
• Phrases: You can use multi-word phrases, not just single terms.
• Keep it short: The glossary is injected into the translation prompt. Excessive entries may slightly increase latency.
• Brand names: Use glossary to ensure brand names are never translated or always translated consistently.

Difference from Google Translate Glossary

Google Translate requires you to create and manage glossary resources via a separate API. Langbly's glossary is per-request, so no resource management is needed. Just pass the terms with each request.

Feature	Google Translate	Langbly
Setup	Create glossary resource first	Per-request, no setup
Management	Separate API for CRUD	None needed
Max entries	10,000 per resource	200 inline, up to 5,000 stored
Storage	Server-side	Inline (stateless) or server-side stored
Cost	Extra API calls	Included