Getting started with glossaries

What is a glossary

A glossary is a reusable terminology list that can be applied to individual translation requests with glossary_id. Each glossary holds mapping entries (type: "mapping" with source and target) and do-not-translate entries (type: "do_not_translate" with a value), organized into groups that can be enabled or disabled per request. These entries are provided to the translation model and applied to the resulting translation where applicable.

Use glossaries to keep terminology consistent across routes and teams rather than manually inserting entries into each translation request.

Recommended usage

Glossaries are meant for terminology that may be translated inconsistently or incorrectly in a specific context. Avoid adding generic terms or globally enabling too many entries without verifying the results. Large glossaries may force terminology into sentences where it does not belong and may result in worse translations.

Good use cases for glossaries include:

• product names that must stay as written in every locale
• support phrases that agents reuse across tickets
• legal or compliance language where a paraphrase is a liability
• terms that should never be translated, such as version codes or regulatory identifiers

That list is enough to improve output. Wait to add more entries until a real translation has an issue and you can identify a specific term that caused it.

Creating and managing glossaries

Glossaries using the POST /api/v1/translate/glossaries endpoint with a display name, an optional sourceLanguageTag and targetLanguageTag, and a default caseSensitive flag for entry matching. Language tags use the canonical set in the languages reference.

Glossary contents live in groups[]:

• each group has a name and an enabled flag that controls whether it contributes entries by default
• items[] inside a group define the behavior: type: "mapping" items use source and target to set how a term is translated, and type: "do_not_translate" items use value to keep that value as written
• every item has its own enabled flag, so you can disable a single term without removing it

PATCH /api/v1/translate/glossaries/:glossaryId replaces the whole mutable tree. Send the updatedAt value from your last GET or list response as expectedUpdatedAt; if another tab or session saved first, the API returns 409 instead of erasing that newer revision. DELETE removes the resource. Every create, update, and delete writes an immutable version snapshot, and GET /api/v1/translate/glossaries/:glossaryId/versions lists them, so "what changed between last quarter and this one" has an answer you can fetch.

Creating, reading, updating, and deleting glossaries are session-only management. Translation routes that apply glossaries are API key auth. The full field list and endpoints are in the glossaries docs.

Apply one stored glossary per request

A translation request references one stored glossary with glossary_id. The selector fields narrow that one glossary; they do not merge multiple stored glossaries together:

• glossary_group_ids selects the enabled groups you want from the stored glossary
• glossary_item_ids selects specific items, combined with the selected groups as a union

Use the selectors to work with a single glossary across multiple use cases or teams. For example, a support team could pass glossary_group_ids: ["grp_support"] while a marketing team passes glossary_group_ids: ["grp_marketing"] and both read the same stored resource. Avoid per-team glossaries that may be updated out-of-sync and lead to differing translations.

For per-item selections in one request, the batch docs cover per-item glossary_id, glossary_group_ids, and glossary_item_ids overrides, and the shared batch route applies one root-level selection to every item. The selector fields are documented in the glossaries docs and the translate docs. You can test combinations in the playground before implementing in code.

Pin versions on async work

Synchronous and asynchronous translation requests need different glossary behavior. Ignoring that behavior can lead to inconsistencies.

Synchronous requests resolve the live glossary selection at request time. If you re-run a synchronous request soon after an edit, it will include that change. Pass glossary_version_id on a synchronous route when you want a specific snapshot for reproducible behavior.

Asynchronous jobs do the opposite. When you create an asynchronous job, the stored glossary request is pinned to the version active at creation time, and later glossary edits do not change queued work. Pass glossary_version_id to pin the same snapshot across separate jobs. Retries re-run the same configuration, so a partially failed job resumes without switching terminology halfway through. Re-run the job from the start and you get the same output for the same input. That reproducibility is the point.

Document jobs behave the same way as regular asynchronous jobs: request.glossary_id is pinned at job creation. The async docs describe the async pipeline, and the documents docs describe how document jobs maintain the selection.

Protect terms that should not be translated

Do-not-translate solves the same problem as a glossary: preserving names, placeholders, and codes that must survive translation intact. "Beta" and "premium" stay in English. {order_id} stays exactly as written. An HTML snippet stays valid if the markup does not move.

• glossary.entries carries inline request-scoped mappings when you do not want a stored resource
• glossary.do_not_translate carries inline protected terms with that inline glossary
• top-level do_not_translate lists protected terms such as placeholders or brand names for the request
• preserve_placeholders detects placeholder-like values and adds them to protected-term handling without rewriting the source text. strict_placeholder_preservation tightens enforcement when enabled and causes translation requests to return an error if any placeholder is accidentally modified during translation

do_not_translate items live in the same groups[] structure as mapping items, so the same group selection governs them. A type: "do_not_translate" item in the grp_brand group is applied or disabled together with that group.

Roll out mappings, do-not-translate entries, and placeholder preservation as one terminology-control system. They can share the same review process, the same per-team scoping, and the same version system. More details can be found in the translate docs.

Recommended roll out strategy

1. Start with one team and a short list: product names, do-not-translate terms, and placeholder rules.
2. Test some real translations and compare the output against the no-glossary version.
3. Add groups for the next team and narrow the active terms per team. Do not add terms without justification in order to mitigate cases where a glossary entry causes an unrelated text to be translated incorrectly.
4. Compare terminology across locales on a regular schedule so drift gets caught while the list is still small.

Term drift across locales compounds. Catching it in week two is a short meeting. Catching it in month six is a rework project.

What the rollout changes

After a rollout, the glossary is small enough to review in an afternoon. Every team reads the same stored resource, asynchronous jobs reproduce exactly, and protected terms stay as written. The common outcome is terminology applied where it belongs and output that stays stable across retries and re-runs.