Connecting CMS, Repos, and TMS: A Translation API Playbook

Most localization bottlenecks are not translation problems, they are integration problems. Content lives in a CMS, strings live in a code repository, design copy lives in Figma, and translation memory lives in a TMS. Without tight API connections between these systems, teams resort to manual file handoffs, stale translations ship to production, and engineers burn cycles on work that should be automated. This playbook provides reference architectures, payload patterns, and CI/CD gates so your engineering team can build a resilient, observable, and secure translation pipeline. Whether you manage a handful of locales or hundreds, the patterns here scale. If you need an AI-powered execution layer that already handles these integrations, explore how Ollang can accelerate your pipeline.

Why API-First Localization Beats Manual Handoffs

The Cost of Copy-Paste Workflows

Manual localization workflows, exporting spreadsheets, emailing files, re-importing translations, introduce delay at every step. A single content update can take days to reach translators, and the return trip is just as slow. Worse, each handoff is an opportunity for human error: mismatched keys, overwritten translations, formatting corruption. Teams that rely on copy-paste workflows frequently discover that production content is out of sync with the source of truth, leading to inconsistent user experiences and costly hotfixes.

The operational cost compounds as you add locales. What works passably for two languages collapses at ten. Engineers get pulled into file management instead of building product features, and translators lose context because they receive strings stripped of surrounding UI.

Velocity, Quality, and Observability Gains

An API-first approach eliminates these handoffs entirely. Source content changes trigger automated extraction, translation, review, and deployment, often within minutes. The gains fall into three categories:

• Velocity: Delta detection means only changed strings are sent for translation, reducing turnaround from days to hours or minutes.
• Quality: Translators work in context with stable reference IDs, and automated quality checks catch errors before deployment.
• Observability: Every API call is logged, every webhook delivery is tracked, and dashboards surface bottlenecks in real time.

Organizations that adopt continuous localization report significantly faster time-to-market for multilingual releases, according to research from CSA Research. The shift from batch-based to event-driven translation is the single highest-leverage change a localization team can make.

Reference Architecture Overview

An orchestration layer (for example, Ollang) centralizes connectors, delta detection, and job routing so teams do not have to build point integrations for each system. The following connector patterns are the building blocks for that orchestration.

CMS Connectors: Adobe Experience Manager and Contentful

Content management systems are the primary source of truth for marketing pages, help articles, and editorial content. The integration pattern differs by CMS architecture.

Adobe Experience Manager (AEM) exposes content via its Assets HTTP API and Content Fragment API. A typical integration registers a workflow launcher that fires when a content author publishes or updates a page. The launcher calls your translation orchestration layer, which extracts translatable nodes from the JCR content tree, preserving structure and metadata. Translated content is written back to language-copy pages via the same API.

Contentful follows a webhook-driven model. You configure a webhook on the Entry.publish event, which posts the entry payload, including locale fields, to your translation service endpoint. Contentful's Content Management API supports locale-aware field updates, so translations can be written directly back to the appropriate locale variant of each entry. The key architectural decision is whether to use Contentful's built-in locale model or manage locale entries as separate content objects; the former is simpler, the latter offers more granular publishing control.

In both cases, the connector must handle:

• Extracting only translatable fields (skipping system metadata, asset references, and boolean flags)
• Preserving rich-text formatting (HTML or Contentful's rich-text JSON)
• Mapping CMS content IDs to stable translation keys

Repository Connectors: GitHub and GitLab

For product UI strings, the repository is the source of truth. The integration pattern centers on monitoring locale resource files, typically JSON, YAML, ARB, or .strings files, within the repo.

GitHub and GitLab both support webhooks on push and pull-request events. When a developer pushes changes to the source locale file (e.g., en.json), a webhook triggers your translation pipeline. The pipeline diffs the changed file against the previous commit to identify new, modified, and deleted keys, this is delta detection, and it is critical for avoiding redundant translation work.

A robust connector uses the repository's API (GitHub's REST or GraphQL API, GitLab's Repository Files API) to:

1. Fetch the changed source file at the specific commit SHA
2. Compute the delta against the last-processed commit
3. Send only changed segments to the TMS or AI engine
4. Write translated files back to a feature branch
5. Open a pull/merge request for review

This PR-based workflow gives engineers visibility into what changed and lets CI checks validate the translations before merge.

Design Tool Connectors: Figma

Figma has become a primary source of UI copy, especially in design-led organizations. The Figma REST API exposes text nodes within frames, making it possible to extract copy, send it for translation, and write translations back into design files or directly into code-ready resource files.

The practical challenge with Figma is that designers rarely think in terms of string keys. A connector must assign stable identifiers to text nodes (Figma's internal node IDs work well) and maintain a mapping table between design nodes and code-level translation keys. This mapping enables a closed loop: copy changes in Figma flow to the TMS, translations flow back to both Figma (for design review) and the repository (for development).

Product Analytics and Feature Flags

Connecting product analytics to your translation pipeline enables prioritization. If analytics data shows that a particular feature is used by a high percentage of users in a target locale, those strings can be prioritized in the translation queue. Similarly, feature-flag systems (LaunchDarkly, Unleash, or homegrown solutions) allow you to gate localized features, releasing translations only when they pass quality checks.

The integration is lightweight: your translation orchestration layer queries the analytics or feature-flag API to annotate translation jobs with priority metadata and to control deployment timing.

String Extraction, Stable IDs, and Format Handling

Designing Stable Translation Keys

Unstable keys are one of the most common causes of translation loss. If a key changes from homepage.hero.title to home.hero_title between releases, the TMS treats it as a new string and the existing translation is orphaned. Stable key design follows a few principles:

• Use a hierarchical, dot-separated namespace that reflects logical structure, not file paths or component names that refactor frequently.
• Never auto-generate keys from source text (e.g., hashing "Welcome back" to a3f9b2c). Source text changes; the key should not.
• Document key naming conventions in a style guide and enforce them with a linter.

A stable key looks like onboarding.welcome.heading, it describes where and what, not how the string reads.

ICU MessageFormat and Plural Handling

Pluralization and variable interpolation are where naive string handling breaks down. The ICU MessageFormat standard provides a syntax that handles plurals, gender, and select expressions across languages with different grammatical rules.

A source string like:

{count, plural, one {# item in your cart} other {# items in your cart}}

allows translators to provide the correct plural forms for each target language, critical for languages like Arabic (six plural forms) or Polish (three). Your extraction pipeline must:

• Detect ICU syntax and pass the full message pattern to the TMS, not just the inner text fragments
• Validate that translated strings contain the same placeholders and plural categories as the source
• Reject translations that break ICU syntax before they reach production

Delta Detection and Deduplication

Sending your entire string catalog for translation on every change is wasteful and slow. Delta detection compares the current source file against the last-processed version and extracts only new or modified key-value pairs.

The algorithm is straightforward:

1. Load the previous source snapshot (stored in your orchestration layer's database or fetched from the repo at the last-processed commit)
2. Diff keys: identify added, removed, and modified entries
3. For modified entries, compare source values, if only whitespace or comments changed, skip
4. Deduplicate across files: if the same source string appears in multiple locations, translate once and fan out

Delta detection reduces translation volume dramatically in mature products where most strings are stable between releases.

API Mechanics: Auth, Rate Limits, Batching, and Reliability

Authentication and Secrets Management

Every integration involves API credentials, OAuth tokens, API keys, service account certificates. These secrets must never be hardcoded in source files or CI configurations.

Best practices:

For webhook endpoints that receive payloads from external systems, validate signatures. GitHub signs webhook payloads with HMAC-SHA256; Contentful provides a signing secret. Always verify before processing.

Rate Limiting and Backoff Strategies

Every API you integrate with enforces rate limits. Contentful's CMA allows 10 requests per second for content management operations. GitHub's REST API permits 5,000 requests per hour for authenticated users. TMS APIs vary widely.

Your connector must implement:

• Exponential backoff with jitter: On a 429 (rate-limited) response, wait an increasing interval plus a random offset to avoid thundering-herd problems.
• Request batching: Group multiple string updates into a single API call where the endpoint supports bulk operations.
• Queue-based throttling: Use a message queue (SQS, RabbitMQ, or a Redis-backed queue) to buffer outgoing requests and drain at a rate below the limit.

Batching, Retries, and Idempotency Keys

Network calls fail. Your pipeline must handle transient errors gracefully.

Batching reduces the number of API calls and improves throughput. Instead of sending one string per request, batch strings into payloads of 50-200 segments (tuned to the TMS API's limits and your average segment size).

Retries should follow a policy: retry on 5xx errors and timeouts up to three times with exponential backoff; do not retry on 4xx client errors (except 429).

Idempotency keys prevent duplicate processing. Attach a unique key (e.g., a UUID or a hash of the job parameters) to each translation request. If a retry sends the same payload, the TMS can recognize it as a duplicate and return the existing result instead of creating a new job. This is essential for avoiding double charges and conflicting translation versions.

PII Handling and VPC Options

Translation payloads often contain user-generated content or data that includes personally identifiable information. Compliance with GDPR, CCPA, and other privacy regulations requires:

• PII detection and redaction: Scan outgoing payloads for patterns (email addresses, phone numbers, names) and replace them with placeholders before sending to external translation services. Restore original values after translation.
• Data residency: Some regulations require data to remain within specific geographic boundaries. Choose TMS providers and cloud regions that support your residency requirements.
• VPC peering and private endpoints: For maximum security, connect to your TMS or AI engine over a private network rather than the public internet. Major cloud providers support VPC peering and AWS PrivateLink / GCP Private Service Connect for this purpose.

If your organization requires enterprise-grade security for translation data, talk to the Ollang team about VPC and data-residency options.

CI/CD Gates for Translation Quality

i18n Linting and Pseudo-Localization

Catching internationalization issues before translation begins saves time and money. Two automated gates belong in every CI pipeline:

i18n linting checks source strings for common problems:

• Hardcoded strings in code that bypass the localization framework
• Concatenated strings that prevent proper translation (e.g., "Welcome, " + userName + "!" instead of a parameterized message)
• Missing keys in the source locale file
• Duplicate keys
• Broken ICU syntax

Tools like i18next-parser, eslint-plugin-i18n-json, or custom scripts can run as a CI step and block merges that introduce violations.

Pseudo-localization replaces source text with accented or expanded characters (e.g., "Ŝéttîñĝš" for "Settings") to simulate translation without waiting for real translations. This reveals:

• UI elements that truncate or overflow with longer text
• Hardcoded strings that were missed by the linter
• Layout issues with right-to-left or bidirectional text

Pseudo-loc should run automatically on every build and be visually inspectable in preview environments.

Screenshot Capture and In-Context Preview

Automated screenshot capture gives translators and reviewers visual context. After pseudo-loc or real translations are applied, a headless browser (Playwright, Puppeteer) navigates key screens and captures screenshots for each locale. These images are attached to the translation job in the TMS, enabling translators to see exactly where their text appears.

In-context preview goes further: it renders the actual application with translated strings in a staging environment that translators can browse. This is the single most effective way to catch context-dependent errors, a word that is correct in isolation but wrong in a specific UI location.

LQA Checks Before Deploy

Linguistic Quality Assurance (LQA) is the final gate before translated content reaches users. Automated LQA checks include:

• Placeholder integrity: Verify that all variables ({name}, %d, {{count}}) present in the source also appear in the translation
• Terminology consistency: Flag translations that use unapproved terms according to your glossary
• Length constraints: Reject translations that exceed character limits defined per key (critical for mobile UI elements and push notifications)
• Formatting validation: Ensure date, number, and currency formats match the target locale's conventions
• Spell-check and grammar: Run locale-specific checks against the translated text

These checks run as a CI step on the pull request that introduces new translations. Failures block the merge and generate actionable error reports linked to specific keys. If you want to review or automate your CI/CD quality controls and LQA workflow, Review CI/CD quality controls with Ollang.

Platform-Specific Patterns

Mobile: Over-the-Air Translation Updates

Mobile apps have a unique constraint: App Store and Play Store review cycles can take days. Over-the-air (OTA) update systems allow you to push new translations without a full app release.

The pattern:

1. At app launch (or on a configurable interval), the app calls your translation CDN endpoint with its current locale and a version hash.
2. The server compares the hash against the latest published translation bundle. If newer translations exist, it returns a delta payload.
3. The app merges the delta into its local string store and applies the updated translations immediately or on next screen load.

Key considerations:

• Fallback chain: If the OTA fetch fails, the app uses the bundled translations shipped with the binary. Never leave the user with missing strings.
• Signing: Sign translation bundles to prevent tampering. Verify the signature on the client before applying.
• Size optimization: Send only the delta, compressed. For most apps, a translation update is a few kilobytes.

Web: SSR, Edge Caching, and Locale Routing

Server-side rendered (SSR) applications and static sites have different caching considerations for localized content.

SSR applications (Next.js, Nuxt, SvelteKit) typically load translations at request time based on the user's locale. The locale is determined by URL path prefix (/fr/about), subdomain (fr.example.com), or Accept-Language header. Translations should be loaded from a fast, in-memory store or a CDN-backed API, never from the TMS directly at request time.

Edge caching requires locale-aware cache keys. A CDN must vary its cache by locale to avoid serving French content to English users. Most CDN providers (Cloudflare, Fastly, Akamai) support Vary headers or custom cache keys that incorporate the locale identifier.

Static site generation (SSG) pre-renders pages for each locale at build time. This is the simplest model for caching but requires a rebuild when translations change. A webhook from your TMS can trigger a rebuild automatically when new translations are published.

Feature-Flagged Multilingual Releases

Feature flags decouple code deployment from feature release, and the same principle applies to translations. A common pattern:

1. New feature code and its source strings are merged to the main branch behind a feature flag (disabled by default).
2. The translation pipeline detects the new strings and sends them for translation.
3. Translations are completed, reviewed, and pass LQA checks.
4. The feature flag is enabled for the target locales where translations are ready.
5. Locales without completed translations continue to see the existing experience (or a fallback).

This prevents the common problem of shipping a feature with untranslated strings in some locales. The feature flag acts as a quality gate that is locale-aware.

Sample Payload Schemas

Webhook Event Payload

A well-structured webhook payload from your CMS or repository connector to the translation orchestration layer:

{
"event": "content.updated",
"source": "contentful",
"timestamp": "2025-01-15T09:32:00Z",
"idempotency_key": "ctfl-6rqM3x-2025-01-15T09:32:00Z",
"content": {
"entry_id": "6rqM3xKpLmNoPqRs",
"content_type": "blogPost",
"source_locale": "en-US",
"target_locales": ["fr-FR", "de-DE", "ja-JP"],
"fields": [
{
"key": "title",
"value": "Getting Started with Continuous Localization",
"max_length": 80,
"context": "Blog post title, displayed in H1 and browser tab"
},
{
"key": "body",
"value": "<p>Continuous localization automates...</p>",
"format": "html",
"context": "Main body content"
}
]
},
"callback_url": "https://api.internal.example.com/translations/callback",
"priority": "high"
}

Key design decisions in this schema:

• The idempotency_key prevents duplicate jobs if the webhook fires twice
• Each field includes context for translators and optional max_length for automated LQA
• The callback_url tells the TMS where to POST completed translations
• format indicates whether the value contains markup that must be preserved

Translation Response Payload

The TMS or AI engine returns completed translations:

{
"job_id": "trn-20250115-0932-fr",
"idempotency_key": "ctfl-6rqM3x-2025-01-15T09:32:00Z",
"source_locale": "en-US",
"target_locale": "fr-FR",
"status": "completed",
"segments": [
{
"key": "title",
"source": "Getting Started with Continuous Localization",
"translation": "Premiers pas avec la localisation continue",
"confidence": 0.96,
"origin": "translation_memory"
},
{
"key": "body",
"source": "<p>Continuous localization automates...</p>",
"translation": "<p>La localisation continue automatise...</p>",
"confidence": 0.89,
"origin": "ai_engine",
"review_required": true
}
],
"lqa_results": {
"passed": true,
"warnings": ["body: sentence length exceeds source by 22%"]
}
}

The origin field (translation memory, AI engine, human translator) enables downstream quality decisions. Segments flagged review_required can be routed to human reviewers automatically.

Rollout Checklist

Use this checklist to validate your translation pipeline before going live:

Frequently Asked Questions

How do I handle translation for content that changes multiple times a day?

Use delta detection with debouncing (buffer changes 5-15 minutes) and send only the net changes; an orchestration layer like Ollang can handle buffering and net-delta computation for you.

What happens if the TMS API is down during a deployment?

Design the pipeline to degrade gracefully: deploy the last-known-good translation bundle, cache translations at the CDN or client, and log/alert for retry, Ollang supports cached bundles and alerts as part of the orchestration.

Should I use a single TMS for all content types, or multiple specialized tools?

It depends on content risk and volume; many teams use an orchestration layer that routes content to different engines (machine for high-volume, human for legal) while exposing a single normalized API, Ollang provides that orchestration model.

How do I ensure translated strings do not break my application at runtime?

Combine CI checks (ICU and placeholder validation), pseudo-localization, typed interpolation, and runtime fallbacks; Ollang's pipeline can integrate those checks into pre-merge gates to prevent runtime failures.

Build Your Translation Pipeline with Confidence

A well-architected translation pipeline turns localization from a bottleneck into a competitive advantage. The patterns in this playbook, stable keys, delta detection, idempotent API calls, CI/CD quality gates, and platform-specific deployment strategies, give your engineering team the blueprint to ship multilingual products quickly and reliably.

Ollang provides the AI execution layer that connects your CMS, repositories, design tools, and deployment infrastructure into a single, automated localization workflow. If you are ready to eliminate manual handoffs and ship translations at the speed of your code, an orchestration layer like Ollang lets you move from ad hoc scripts to a governed, observable system.

See the Orchestration in Action

• Need secure VPC connectivity and data residency? Talk to our team.
• Want help wiring CMS and repo triggers into CI? Get a technical walkthrough.

Next Step

Book a Demo