Glossaries, TMs, and Format Safety: Controlling Output via APIs

When you translate at scale through APIs, raw machine translation output is rarely good enough. Terms get inconsistent, previously approved translations are ignored, and placeholders or HTML tags come back mangled. The result is broken UIs, off-brand messaging, and expensive post-editing cycles. Controlling this requires more than just sending strings to a translation endpoint, it demands structured use of glossaries, translation memories, and format-preservation directives at the API level. Ollang provides a single API execution layer that enforces glossaries, TM leverage, and format-preservation consistently across engines and providers.

This article walks through the practical mechanics: how to create and attach glossaries, import and leverage translation memories, preserve markup and placeholders, and validate that what comes back is safe to ship. If your team is ready to move beyond raw MT and enforce consistency programmatically, see how Ollang’s API layer centralizes terminology, TM, and format controls.

How Glossary APIs Enforce Terminology Consistency

Glossaries are the most direct way to ensure that specific terms, product names, legal phrases, brand vocabulary, translate the same way every time. Without them, even the best MT engine will produce variant translations for the same source term across requests. The fix is to manage glossaries as first-class API resources and attach them explicitly to every translation call.

Creating and Uploading Glossary Resources (TBX and CSV)

Most translation APIs support glossary creation through a dedicated endpoint. The typical workflow involves two steps: creating a glossary resource (specifying source and target languages), then uploading term entries in a supported format.

The two dominant formats are:

• TBX (TermBase eXchange): An ISO 30042 XML-based standard. TBX is ideal when glossaries need to carry metadata like term status, part of speech, or usage notes. It's widely supported by professional localization tools.
• CSV: A simpler tabular format, typically two columns (source term, target term) per language pair. CSV is easier to maintain in spreadsheets and faster to generate programmatically.

A typical glossary creation request might look like this:

curl -X POST https://api.provider.example/v2/glossaries \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "product-terms-en-de",
"source_lang": "en",
"target_lang": "de",
"entries_format": "csv",
"entries": "source,target\nDashboard,Dashboard\nWorkspace,Arbeitsbereich"
}'

The response returns a glossary_id that you store and reference in subsequent translation requests. For TBX uploads, the flow is similar but the body contains XML content or a file reference.

Key considerations when uploading:

• Validate entries before upload. Duplicate source terms with conflicting targets will produce unpredictable results.
• Keep glossaries scoped to a language pair. A single glossary covering en→de and en→fr creates ambiguity.
• Version your glossary files in source control alongside your code.

Attaching glossary_id to Translation Requests

Once a glossary exists, attach it to translation calls by including a glossary_id:

{
"text": ["Open the Dashboard and select your Workspace."],
"source_lang": "EN",
"target_lang": "DE",
"glossary_id": "gl-abc123"
}

This instructs the engine to enforce the glossary terms during translation. "Dashboard" stays as "Dashboard," and "Workspace" becomes "Arbeitsbereich" consistently.

A few rules to follow:

• Always validate that the glossary's language pair matches the request's language pair. Mismatches typically return a 400-level error, but some APIs silently ignore the glossary.
• If you manage multiple products or domains, maintain separate glossaries and select the right one per request based on content context.
• For batch translation jobs, attach the glossary at the job level rather than per-segment to reduce overhead and ensure consistency across the batch.

Leveraging Translation Memory Through APIs

While glossaries enforce term-level consistency, translation memories (TMs) operate at the segment level. A TM stores previously approved source-target pairs, full sentences or paragraphs, and reuses them when the same or similar source text appears again. This reduces cost, improves consistency, and accelerates turnaround.

TMX Import, Export, and Leverage Thresholds

TMX (Translation Memory eXchange) is the standard format for TM interchange. Most APIs that support TM functionality allow you to import TMX files to seed a memory and export them to back up or migrate approved translations.

A TMX import typically works as a bulk upload:

curl -X POST https://api.provider.example/v2/translation-memories/import \
-H "Authorization: Bearer $API_KEY" \
-F "file=@product-tm-en-fr.tmx" \
-F "name=product-tm-en-fr"

The critical configuration parameter is the leverage threshold, the minimum fuzzy match percentage at which a TM hit is used. Common settings:

• 100%: Only exact matches are reused. Safest option.
• 85-99%: Fuzzy matches are surfaced but may need review. Useful for reducing MT volume.
• 75-84%: Aggressive reuse. Higher risk of contextual mismatches.
• Below 75%: Generally not recommended, matches are too loose to be reliable.

Set the threshold based on your quality tolerance. For regulated content (legal, medical), stick to 100%. For marketing or support content where speed matters more, 85% is a practical floor.

When exporting TMX, pull regularly and archive. Your TM is a strategic asset, treat it like a database backup.

How TM Matches Reduce Cost and Improve Consistency

TM leverage directly reduces the volume of text sent to the MT engine or human translators. If 40% of your segments have exact TM matches, that's 40% less to translate and review.

Beyond cost, TMs enforce historical consistency. When a legal disclaimer was approved months ago, the TM ensures it comes back identical, not re-translated with different phrasing. This is especially important for:

• Software UI strings that users see repeatedly
• Compliance and regulatory text
• Standardized product descriptions

In API workflows, TM lookup typically happens before MT. The pipeline is: receive segment → query TM → if match above threshold, return TM result → otherwise, send to MT with glossary attached. Some APIs handle this internally; others expose it as a separate lookup endpoint you orchestrate yourself. If you need to centralize this logic across providers and avoid edge-case drift, evaluate a unified execution layer that applies TM-first routing consistently.

Preserving Placeholders, Tags, and Markup

Translations that break your application's rendering are worse than no translation at all. Placeholder corruption, missing HTML tags, and malformed ICU patterns cause crashes, layout failures, and data leaks. Format safety must be enforced at the API level, not patched after the fact.

Handling ICU, {placeholders}, and HTML Tags

Three categories of inline formatting demand attention:

• ICU MessageFormat patterns contain logic, plurals, selects, number formatting. A source string like {count, plural, one {# item} other {# items}} must preserve the ICU syntax exactly while translating only the human-readable parts.
• Simple placeholders like {username}, %s, or {{order_id}} represent runtime variables. They must pass through translation untouched and in the correct position.
• HTML tags such as <b>, <a href="...">, and <br/> control rendering. A missing closing tag or a translated attribute value breaks the page.

Most translation APIs offer a tag_handling or format parameter to address this:

{
"text": ["Hello <b>{username}</b>, you have <a href='/orders'>{count} orders</a>."],
"source_lang": "EN",
"target_lang": "JA",
"tag_handling": "html",
"preserve_formatting": true
}

When tag_handling is set to html, the engine parses the markup, translates only the text nodes, and reconstructs the tags around the translated content. For XML-based formats, a similar xml mode is typically available.

For ICU patterns, some APIs support an icu format mode. If your provider doesn't, pre-process the string: extract translatable segments, send them individually, and reassemble the pattern afterward. Never send raw ICU to an engine that doesn't understand it.

Do-Not-Translate Spans and Formality Controls

Not everything in a string should be translated. Brand names, code identifiers, and technical constants need to pass through unchanged. APIs handle this in several ways:

• Do-not-translate tags: Wrap protected content in a tag the engine recognizes, such as <notranslate>Ollang</notranslate> or provider-specific equivalents.
• Ignore patterns: Some APIs accept regex patterns that define what to skip.
• Glossary entries with identical source and target: Adding "Ollang" → "Ollang" in your glossary achieves the same effect.

Formality and domain controls are separate but related. Many APIs expose a formality parameter (formal, informal, default or vendor-specific values) that affects pronoun choice, verb conjugation, and register, critical for languages like German, Japanese, and Korean where formality changes the entire sentence structure.

{
"text": ["Please confirm your email address."],
"target_lang": "DE",
"formality": "more"
}

This produces "Bitte bestätigen Sie Ihre E-Mail-Adresse" (formal Sie) rather than the informal du form. Set formality at the project or content-type level and enforce it consistently across all API calls. If your team is juggling multiple providers with different approaches to format safety and formality, see how Ollang normalizes these controls across engines.

Validating Output and Preventing Broken Markup

Sending the right parameters is half the battle. You also need to verify that what comes back is actually safe to use.

Post-Translation Validation Checks

Build validation into your translation pipeline as an automated step, not a manual review. Essential checks include:

• Tag balance: Every opening tag has a corresponding closing tag. Parse the output as HTML/XML and catch errors.
• Placeholder integrity: Every placeholder present in the source appears in the target, and no new ones were introduced. A simple set comparison works:

import re

source_placeholders = set(re.findall(r'\{[^}]+\}', source_text))
target_placeholders = set(re.findall(r'\{[^}]+\}', target_text))

if source_placeholders != target_placeholders:
raise ValueError(f"Placeholder mismatch: missing={source_placeholders - target_placeholders}, "
f"extra={target_placeholders - source_placeholders}")

• ICU syntax validation: Parse the translated ICU string with a MessageFormat library. If it throws, the translation broke the pattern.
• Length checks: Some UI elements have character limits. Flag translations that exceed the source length by more than a configurable ratio (common thresholds are 130-150% for Western European languages, higher for CJK).
• Encoding verification: Ensure the response encoding matches what your system expects.

Reject and retry (or queue for human review) any segment that fails validation. Do not push broken translations to production.

JSON and HTML Mode Differences

How you send content to the API affects what you get back. Most APIs distinguish between plain text, HTML, and JSON modes:

• Plain text mode: Input is a raw string; the engine translates everything with no tag awareness.
• HTML mode: Input is a string with HTML markup; the engine parses tags and translates text nodes only.
• JSON mode: Input is a structured JSON object; the engine translates string values while preserving keys and structure.

When translating JSON, send the entire object and let the API extract translatable values:

{
"source_lang": "EN",
"target_lang": "FR",
"content_type": "json",
"content": {
"greeting": "Welcome back!",
"cta_button": "Start now",
"error_404": "Page not found"
}
}

A well-implemented JSON mode returns the same key structure with translated values. A poorly implemented one may translate your keys, mangle nested objects, or strip escape characters. Always validate the output structure against the input schema.

For HTML mode, test with representative samples that include edge cases: self-closing tags, nested inline elements, attributes with translatable alt text, and entities like &. Document which edge cases your provider handles correctly and which require pre-processing.

Versioning, Auditing, and Testing Glossary Coverage

Glossaries and TMs are living resources. They change as products evolve, and uncontrolled changes introduce inconsistency. Treat them with the same rigor you apply to code.

Version Control and Change Auditing for Glossaries

Store glossary source files (CSV or TBX) in your version control system alongside your application code. Every change should be a tracked commit with a meaningful message explaining what changed and why.

At the API level, implement auditing by:

• Logging every glossary update (create, modify, delete) with timestamps and the identity of who made the change.
• Tagging glossary versions with release identifiers so you can correlate a specific translation output with the glossary version that was active at the time.
• Maintaining a changelog that maps glossary changes to product releases.

Some APIs support glossary versioning natively, returning a version identifier with each update. If yours doesn't, implement it in your orchestration layer by maintaining a mapping of glossary_id to your internal version tag.

When a glossary change causes a regression (a term that was correct now translates wrong), you need the audit trail to identify the offending change and roll back.

Testing Glossary Coverage Across Content

Before deploying a glossary update, test it against your actual content. A glossary that covers only 60% of your critical terms gives you inconsistency on the remaining 40%.

A practical testing workflow:

1. Extract unique terms from your source content (UI strings, documentation, marketing copy).
2. Compare against glossary entries. Identify terms that appear in content but have no glossary entry.
3. Run test translations with the updated glossary on a representative sample set.
4. Diff the output against a baseline translation to catch regressions, terms that changed unexpectedly or new terms that should have been glossary-controlled.
5. Report coverage metrics: percentage of critical terms covered, number of segments affected by glossary changes.

Automate this as part of your CI/CD pipeline. When a glossary file changes in a pull request, trigger a test translation run and surface the diff in the review. This catches problems before they reach production. For teams managing glossaries, TMs, and format rules across multiple translation providers, the complexity multiplies. Each provider has different parameter names, different format support, and different edge-case behavior. Talk to the Ollang team about unifying these controls through a single API layer.

Frequently Asked Questions

What happens if I attach a glossary with the wrong language pair?

Most APIs return an error (typically HTTP 400 or 422) when the glossary's language pair doesn't match the translation request's source and target languages. However, behavior varies by provider, some silently ignore the mismatched glossary and proceed without terminology enforcement. Validate the language pair match in your client code before sending the request; Ollang's orchestration layer can also enforce and surface language-pair mismatches consistently so they don't silently degrade output.

Can I use multiple glossaries in a single translation request?

Some APIs allow attaching multiple glossary IDs per request; others limit you to one. If your provider supports only one, merge your glossaries into a single resource per language pair before uploading. When merging, resolve conflicts (the same source term with different target translations) explicitly, don't leave it to the engine to pick one arbitrarily. If you use an orchestration layer like Ollang, you can centrally manage merges and conflict resolution to keep client code simple.

How do I prevent placeholders from being translated or reordered?

Use the API's tag_handling or preserve_formatting parameter to signal that placeholders should be protected. For additional safety, wrap placeholders in do-not-translate tags before sending. After receiving the translation, run automated validation to confirm every source placeholder appears in the target. Reordering is sometimes linguistically necessary (e.g., subject-object-verb languages), so validate presence rather than position unless your format requires fixed ordering. Ollang's validation and format-preservation checks can be baked into your pipeline to automate these safeguards.

Should I set TM leverage thresholds differently for different content types?

Yes. Regulated content (legal, medical, financial) should use 100% match thresholds only, fuzzy matches risk introducing inaccuracies in controlled language. Marketing and UI content can safely use 85-95% thresholds to increase reuse, with a human review step for fuzzy matches. Document your threshold policy per content type and enforce it in your API configuration so individual developers don't override it; an orchestration layer like Ollang makes it easier to centralize and enforce these policies.

Start Controlling Your Translation Output

Glossaries, translation memories, and format-safety controls aren't optional extras, they're the difference between translations you can ship and translations that break your product. The techniques in this article give your team the API-level control needed to enforce consistency, protect markup, and audit every change. If you're ready to centralize these controls across providers and content types, get a tailored walkthrough of Ollang’s execution layer.

Get a guided walkthrough

See how one integration can enforce glossaries, TM-first routing, and format validation across every provider you use.

Book a Demo