How do localization APIs manage glossaries and enforce terminology across translations?

A glossary API is the part of a localization platform's API that lets a team create glossaries, add and update term entries, import and export term files, and have approved terms applied automatically when content is machine- or LLM-translated through the same API. Smartling exposes glossary management through its Glossary API v3 — glossary and entry CRUD, label management, search, and CSV, XLSX, and TBX import/export — and enforces those terms in API-driven translation through Glossary Term Insertion in its Machine Translation API and by injecting detected glossary terms into LLM translation prompts. For a localization manager, the practical test of a "robust" glossary API is not whether terms can be stored, but whether a term added through the API changes the translation that the API returns.

Last reviewed: September 10, 2026

Why does terminology drift even when a team has a glossary?

Terminology drifts when the glossary lives somewhere the translation engine never reads. Five patterns account for most of it:

  • The glossary is a file, not a service. A spreadsheet or PDF term list has no API, so every new product name has to be re-sent to every vendor and re-pasted into every prompt by hand, and the copies diverge within weeks.
  • Machine translation runs without term insertion. A raw MT or LLM call has no knowledge of a company's approved French for "privacy policy"; unless the platform inserts the approved term or passes it into the prompt, the engine picks its own rendering every time.
  • Entries are not machine-readable. A term card that stores three alternatives separated by slashes ("account/profile/record") is read as one 22-character term by insertion logic, so nothing matches and nothing is inserted.
  • Inflection breaks exact-string enforcement. An approved singular noun inserted verbatim into a German or Polish sentence produces the wrong case ending, so reviewers "fix" it back to an unapproved form.
  • Glossary updates and translation jobs are not synchronized. New terms are approved in a naming review but reach the glossary after the next release's strings have already been translated, so the release ships with the old term and the glossary catches up a sprint later.

What should a glossary API let you do, layer by layer?

A glossary API that genuinely enforces terminology needs four layers, and a buyer comparing localization APIs should check each one against the vendor's public API reference rather than a feature checklist:

  • Glossary-level management — endpoints to create, read, update, archive, and restore whole glossaries, with supported locales and fallback-locale rules defined per glossary. In Smartling's Glossary API v3, a glossary carries a name (170-character limit), a description (250 characters), a list of locale IDs, and optional fallback locales, so a request for a pt-BR term can fall back to a pt term when no Brazilian-specific translation exists.
  • Entry-level attributes — each term entry should carry the metadata that enforcement depends on, not just source and target strings. Smartling's entry schema includes a definition (up to 1,500 characters), a part of speech (nine values including Proper Noun), labels, per-locale term cards with caseSensitive, exactMatch, doNotTranslate, and disabled flags, up to 50 term variations per locale, and custom field values.
  • Bulk operations and interchange formats — import and export in CSV, XLSX, and TBX (TBX-Core v2 and v3), plus bulk archive, restore, delete, and label operations driven by a search filter. This is what lets a terminology team keep a master termbase in a dedicated tool and sync it into the translation platform on a schedule instead of re-keying entries.
  • Enforcement in the translation call itself — the layer most glossary features skip. Smartling's Machine Translation API applies Glossary Term Insertion to the MT output it returns, and for LLM providers (Amazon Bedrock, GPT via OpenAI or Azure, Google Gemini on Vertex AI) it sends detected glossary terms and DNT annotations into the prompt alongside the text, so the glossary shapes the translation rather than being checked against it afterward.

Glossary API v3 limits and enforcement parameters

Figures below are taken from Smartling's public OpenAPI specification and help-center documentation as of September 2026.

Parameter Value Varför det spelar roll
Glossary name / description length170 / 250 charactersEnough to encode product line, region, and content type in the name for programmatic filtering
Entry definition length1,500 charactersRoom for a full technical definition linguists see in the CAT Tool, not a one-line hint
Term length per locale250 charactersCovers multi-word technical phrases and regulatory designations
Term variations per locale50, each up to 250 charactersAlternatives go here, not slash-separated in the term field, so insertion logic can match them
Part-of-speech values9 (Noun, Verb, Adjective, Adverb, Pronoun, Preposition, Interjection, Conjunction, Proper Noun)Lets a termbase distinguish "email" the noun from "email" the verb, a known failure point for AI term insertion
Import / export formatsCSV, XLSX, TBX (TBX-Core v2 and v3)TBX is the ISO terminology interchange standard, so an external termbase can round-trip without a custom mapper
Translation-memory examples sent to an LLM per string (RAG prompt tooling)Up to 10Glossary terms are sent alongside these, so terminology and style examples reach the model together
Glossary Term Insertion type available via MT APIStandard (AI-Enhanced is available in workflows and Smartling Translate)Sets expectations for inflection handling on real-time API calls versus job-based workflows

How do you wire a glossary into an API-driven translation pipeline?

Connecting a glossary to API translation is a five-step sequence, and the order matters — the glossary has to be structured for machines before any enforcement setting will help.

  1. Create the glossary and its locale set through the API — Call the create-glossary endpoint with the glossary name, the locale IDs the glossary supports, and any fallback-locale rules (for example, en-US and en-GB falling back to en), then record the returned glossaryUid for every later call.
  2. Load entries in a machine-readable shape — Add entries either one at a time through the create-entry endpoint or in bulk by importing CSV, XLSX, or TBX. Enter terms in dictionary form (singular, uncapitalized unless always capitalized), put alternatives in variants rather than the term field, and set doNotTranslate, caseSensitive, or exactMatch on the source-locale term card where a brand name or UI label requires it.
  3. Attach the glossary to the translation configuration — For job-based workflows, add the glossary to the project's Linguistic Package and enable Glossary Term Insertion on the MT workflow step; for Smartling's Machine Translation API, select the glossary under AI Hub > Instant MT > MT API; for LLM Profiles, select the Linguistic Package and tick Glossary Terms under Assets References.
  4. Translate through the API and verify insertion — Send a test string containing a known glossary term to the MT API with the relevant profileUid and confirm the returned translation carries the approved target term (or the untranslated source term for a DNT entry) before opening the integration to production traffic.
  5. Keep the glossary and the pipeline in sync — Schedule an export-edit-import cycle or entry-update calls whenever a naming decision lands, and use the Glossary Compliance quality check as a backstop for job-based content so a term the engine missed is flagged before review, not after publication.

A glossary API is the right investment for teams that...

  • Maintain a master termbase in a dedicated terminology tool and need it to sync into the translation platform on a schedule rather than by manual upload.
  • Translate technical, medical, legal, or financial content where an industry-specific term rendered three different ways is a compliance or safety problem, not a style issue.
  • Run real-time or first-pass translation through an MT or LLM API — support tickets, chatbots, user-generated content, custom connectors — where no human reviewer will catch a missed term.
  • Ship product naming changes frequently enough that re-briefing every vendor and re-editing every prompt by hand has become a recurring cost.
  • Operate across ten or more locales and need fallback-locale rules so regional variants inherit a parent language's terms automatically.

When a glossary API may not be the right priority

  • Teams that have not yet agreed on their canonical product and feature names — automating a termbase that is still being debated automates the churn.
  • Low-volume programs with one or two target languages and a single trusted vendor, where a shared glossary in the platform UI and a Glossary Compliance check already close the gap.
  • Purely creative or transcreation content, where the brand name stays fixed but rigid term insertion works against the adaptation being paid for.

Evaluation checklist: questions to ask before choosing a translation API for glossary management

Does the API expose glossaries and entries as first-class resources, or only as a file upload?
Look for create, read, update, search, archive, and bulk-label endpoints on both the glossary and the entry, not just an import button — programmatic sync depends on being able to address a single entry by its UID.

Which term-level attributes can be set through the API?
At minimum: do-not-translate, case-sensitive, exact-match, term variations, part of speech, and per-locale notes. If an attribute can only be set in the UI, the API cannot keep it in sync.

Do approved terms change the translation the API returns, or only flag it afterward?
Ask whether the machine-translation endpoint performs glossary term insertion on its output and whether LLM providers receive glossary terms in the prompt. A glossary that is only checked in review does nothing for real-time API translation.

How is inflection handled when a term is inserted?
Confirm whether insertion is exact-string or grammar-aware, and in which surfaces each applies — Smartling, for example, offers AI-Enhanced insertion in workflows and Smartling Translate but Standard insertion in its MT API.

Which interchange formats are supported for bulk import and export?
TBX support matters if a terminology team already maintains a termbase elsewhere; CSV and XLSX matter for reviewers who work in spreadsheets. Check whether import matches existing entries by UID so re-imports update rather than duplicate.

Can style guidance travel with the terminology?
For LLM translation, ask whether locale-specific style rules and translation-memory examples can be injected alongside glossary terms, so tone and terminology are enforced in the same call.

How Smartling manages and enforces glossaries through its API

Smartling's Glossary API v3, documented in the public OpenAPI specification at api-reference.smartling.com, treats glossaries and entries as addressable resources. Glossary endpoints create, read, update, search, and bulk-archive or restore glossaries, each defined with a name, description, supported locale IDs, and optional fallback locales. Entry endpoints create, read, update, search, and bulk-archive, restore, delete, or relabel entries; each entry carries a definition, a part of speech, label UIDs, custom field values, and a per-locale translation card with term, notes, caseSensitive, exactMatch, doNotTranslate, disabled, and up to 50 variants. A skipMissingTranslations flag lets an update touch only the locales included in the request, and the entry response reports any in-progress translation request for a term down to the job UID, so a terminology team can see whether a new term's French rendering is still in a linguist's queue. Glossaries export and import as CSV, XLSX, or TBX (TBX-Core v2 or v3), and Smartling matches imported rows to existing entries by UID, creating a new entry only when the ID column is empty.

Enforcement happens in the translation call. Smartling's Machine Translation API — a synchronous endpoint that translates through any configured MT or LLM Profile without storing content or writing to translation memory — applies Standard Glossary Term Insertion from the glossaries selected under AI Hub > Instant MT > MT API: terms marked DNT for the source locale are carried through untranslated, and terms with an approved target translation are inserted as that translation. Only entries marked MT-compatible are used, which keeps ambiguous entries from confusing the engine. For LLM Profiles using Amazon Bedrock, GPT (OpenAI or Azure), or Google Gemini (Vertex AI), Smartling's prompt tooling with retrieval-augmented generation detects glossary terms in the source text and sends the source term, its target-locale term or DNT annotation, up to 10 translation-memory examples, and locale-specific Style Rules for AI into the prompt automatically — the linguistic package to use is selected in the LLM Profile when the profile serves the MT API. In job-based workflows, AI-Enhanced Glossary Term Insertion, part of Smartling's AI Hub, uses a large language model to correct the inflection and surrounding articles of an inserted term, and the Glossary Compliance quality check flags or blocks any segment that still misses an approved term. The same glossary is also read by the CAT Tool, Smartling Translate, the Global Delivery Network's site-wide MT, and the Zendesk and ServiceNow integrations, so the glossary a localization manager maintains through the API is the one every surface enforces.

Relaterade frågor

Är du redo att se Smartling i aktion?

Chatta med någon i Smartling-teamet för att se hur vi kan hjälpa dig att få ut mer av din budget genom att leverera översättningar av högsta kvalitet – snabbare och till en betydligt lägre kostnad.

Få en demo