A glossary gives the localization engine exact control over specific terms - either enforcing a precise translation or preventing translation entirely. Glossary terms take precedence over the model's own judgment, so the engine applies them consistently across every request.
A glossary is organization-owned: a named container holding terms, applied to a localization engine by attachment. One glossary can govern every engine that needs it, and an engine can apply several.
How it works#
| Object | Fields |
|---|---|
| Glossary | Name, description, the source locales it covers. Holds any number of terms. |
| Term | Source locale, target locale, source text, target text, type, hint. |
When the engine processes a translation request, it retrieves relevant terms from every attached glossary using semantic search - matching the meaning of the input text against stored source terms, not exact strings.
| Field | Description |
|---|---|
| Source locale | The locale of the source text, or * for any source |
| Target locale | The locale of the target text, or * for any target |
| Source text | The term in the source language |
| Target text | The required translation (or the same term, for non-translatables) |
| Type | custom_translation or non_translatable |
| Hint | Optional context to disambiguate the term (e.g., "noun, the product feature") |
Glossaries are organization-owned#
| Action | Effect |
|---|---|
| Create a glossary | It exists at organization level and applies to nothing until attached |
| Attach it to an engine | Every term in it is retrievable for that engine's translations |
| Attach it to several engines | The same terms govern all of them - edit once, every engine follows |
| Attach several glossaries to one engine | Their terms combine into one retrieval pool |
| Detach it from an engine | The engine stops applying it. The glossary and its terms are kept. |
| Delete a glossary | Refused while any engine still applies it - detach first. Deleting takes its terms with it. |
| Delete an engine | Glossaries and terms survive. They belong to the organization, not the engine. |
Attachment order carries no meaning. When two attached glossaries define the same source text for the same locale pair, either may win - keep one term in one place.
Manage glossaries under Glossaries in the organization sidebar. An engine's Glossary tab lists the terms it currently applies and attaches or detaches glossaries.
Source locales#
A glossary declares which source locales it covers. A custom_translation whose source locale is not one of them is refused on write - on every path, including the dashboard, the API, an applied engine suggestion, and provisioning. The check uses the same permissive locale match as read time, so a glossary covering en accepts an en-US term.
Leave the source locales empty and the glossary accepts any source locale.
Non-translatables are exempt: there is no source-language translation to bind. They are also stored once against a wildcard target locale, whatever target you send - the term is protected in every language, so per-locale copies would be duplicates.
Glossary types#
Custom translations#
Force a specific translation for a term. The engine always uses your translation instead of the model's.
| Source text | Target text | Source locale | Target locale |
|---|---|---|---|
| Deploy | Bereitstellen | en | de |
| 911 | 112 | en | de |
| workspace | espace de travail | en | fr |
Use custom translations for:
- Product terminology with established translations
- Cultural adaptations (emergency numbers, measurement units)
- Terms where the model consistently picks the wrong synonym
Non-translatables#
Prevent a term from being translated. The engine keeps the source text as-is, in every target locale.
| Source text | Target text | Type |
|---|---|---|
| Lingo.dev | Lingo.dev | non_translatable |
| OAuth | OAuth | non_translatable |
| GraphQL | GraphQL | non_translatable |
Use non-translatables for:
- Brand names and product names
- Technical protocols and standards
- Proper nouns that should remain in the source language
Semantic matching#
Glossary terms are matched by meaning, not exact string comparison. When the engine receives a translation request, it generates embeddings for the input text and finds terms with semantically similar source text.
This means a term for "Deploy" also matches "Deploying", "deployment", and "deploy your application" - without separate entries for each variation.
Hint field
Use the hint field to disambiguate terms with multiple meanings. For example, a term for "bank" with hint "financial institution" won't match "river bank" in the input text.
Wildcard locales#
Set source or target locale to * to apply a term across all locale pairs.
Common patterns:
| Source text | Source locale | Target locale | Use case |
|---|---|---|---|
| Lingo.dev | * | * | Never translate the brand name in any language |
| API | en | * | Keep "API" untranslated across all target locales |
| Deploy | en | de | Use specific German translation for this English term |
Wildcard terms and locale-specific terms combine - they don't override each other.
Locale matching#
Glossary terms match across regional variants, not just exact locale codes. A de term applies to de-DE; a de-DE term applies to a bare de request. Siblings like de-DE and de-AT never share terms. When several match, the CLDR default region wins. The same rules drive brand voices, rules, and model configs. See Locale Resolution for the full behavior, including the script-safety rule for custom translations.
Glossary vs. rules vs. brand voices#
Each serves a distinct purpose in the engine's configuration:
| Glossary | Rule | Brand Voice | |
|---|---|---|---|
| Controls | Individual terms | Linguistic conventions | Overall tone and style |
| Granularity | Per-term | Per-rule | Per-locale text |
| Matching | Semantic (by meaning) | All matching rules included | The single best-matching text |
| Precedence | Highest - overrides model judgment | Medium - guides the model | Lowest - sets context |
| Example | "Deploy" → "Bereitstellen" | "Abbreviate Straße to Str." | "Use informal du, technical tone" |
All three are organization-owned containers an engine applies by attachment: glossaries hold terms, rulesets hold rules, and a brand voice holds one text per locale.
Rule precedence
Glossary terms take the highest precedence in the engine's hierarchy. If a glossary term conflicts with a rule, the glossary wins. Design rules to complement the glossary, not duplicate it.
Using glossaries with the API#
Glossary terms are applied automatically when you call the localize endpoint. The engine retrieves semantically relevant terms for the source and target locale pair from the glossaries it applies and includes them in the prompt. No additional parameters are needed.
| Call | Purpose |
|---|---|
POST /glossaries | Create a glossary for the organization |
GET /organizations/:id/glossaries | List the organization's glossaries with term and engine counts |
GET /glossaries/:id/glossary-items | List a glossary's terms, grouped by source text |
POST /glossary-items with glossaryId | Add a term to a glossary |
PUT /engines/:id/glossaries | Replace the set of glossaries an engine applies |
DELETE /engines/:id/glossaries/:glossaryId | Stop applying one glossary to an engine |
GET /engines/:id/glossary-items | List every term an engine currently applies |
ownerEngineId on POST /glossary-items still works - it writes into the engine's default glossary. Prefer glossaryId.
Access#
org:glossary:read and org:glossary:edit govern glossaries and the terms inside them; attaching one to an engine also needs engine:edit on that engine. A per-glossary grant gives someone read and edit on a single glossary instead of every glossary in the organization. See Roles & Permissions.
Managing glossaries via MCP#
If you use the Lingo.dev MCP server, your AI coding assistant can manage glossaries and their terms directly:
"Create a glossary called Product terms covering English, and
apply it to the web engine.""Add a term: translate 'workspace' to 'espace de travail'
for English to French.""Mark 'GraphQL' as non-translatable for all locales."