Glossaries#
A glossary gives the localization engine exact control over specific terms — either enforcing a precise translation or preventing translation entirely. Glossary rules take precedence over the model's own judgment, so the engine applies them consistently across every request.
How it works#
Each glossary item belongs to a localization engine and matches on a source locale and target locale pair (or * for any locale). When the engine processes a translation request, it retrieves relevant glossary items using semantic search — matching the meaning of the input text against stored terms, not just exact string matches.
| 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") |
Glossary types#
Custom translations#
Force a specific translation for a term. The engine will always use 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.
| 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 items are matched by meaning, not exact string comparison. When the engine receives a translation request, it generates embeddings for the input text and finds glossary items with semantically similar source terms.
This means a glossary entry for "Deploy" will also match "Deploying", "deployment", and "deploy your application" — without needing separate entries for each variation.
Hint field
Use the hint field to disambiguate terms with multiple meanings. For example, a glossary entry 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 glossary item 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 items and locale-specific items combine — they don't override each other.
Glossary vs. instructions vs. brand voices#
Each serves a distinct purpose in the engine's configuration:
| Glossary | Instruction | Brand Voice | |
|---|---|---|---|
| Controls | Individual terms | Linguistic rules | Overall tone and style |
| Granularity | Per-term | Per-rule | Per-locale |
| Matching | Semantic (by meaning) | All included for locale | All included for locale |
| 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" |
Rule precedence
Glossary terms take the highest precedence in the engine's rule hierarchy. If a glossary item conflicts with an instruction, the glossary wins. Design instructions to complement the glossary, not duplicate it.
Using glossaries with the API#
Glossary items are applied automatically when you call the localize endpoint. The engine retrieves semantically relevant items for the source and target locale pair and includes them in the prompt.
No additional parameters are needed — the engine handles retrieval and injection.
Managing glossaries via MCP#
If you use the Lingo.dev MCP server, your AI coding assistant can manage glossary items directly:
"Add a glossary entry: translate 'workspace' to 'espace de travail'
for English to French.""Mark 'GraphQL' as non-translatable for all locales."