Repo-Connected Localization: CI/CD Integration with TMS APIs

Most localization pipelines break at the handoff. Developers push new strings to a repository, then someone manually uploads files to a translation management system, waits for translations, downloads them, and opens a pull request. Every manual step introduces delay, drift, and the risk of shipping untranslated UI. Repo-connected localization eliminates that gap by wiring your CI/CD pipeline directly to TMS APIs so that every commit containing changed strings automatically triggers extraction, translation, and asset delivery, without anyone alt-tabbing to a dashboard. This article walks through the architecture, API patterns, file formats, webhook strategies, and failure modes you need to build a reliable, automated pipeline from commit to localized artifact using platforms like Ollang, Phrase, Smartling, Lokalise, Transifex, and Crowdin.

If your team is evaluating how to automate localization end-to-end across text, software, and content types, explore how Ollang's execution layer fits into your CI/CD workflow.

Why Repo-Driven Localization Matters

The Cost of Manual Handoffs Between Dev and L10n

Manual localization handoffs create a compounding tax on every release. A developer adds three new strings, but the localization manager doesn't notice until the next weekly sync. By then, the feature has shipped in English only, and the translated assets arrive two sprints later, if they arrive at all. According to the Globalization and Localization Association (GALA), translation delays are among the top reasons companies ship incomplete locale coverage.

The costs are concrete:

• Context loss. When strings are extracted days after they're written, developers have moved on and can't answer translator questions about meaning or placeholders.
• Merge friction. Manually committed translation files collide with ongoing development, producing merge conflicts in resource bundles that nobody wants to resolve.
• Incomplete coverage. Without automated diffing, new or changed strings slip through. Users in non-primary locales encounter raw keys or stale copy.
• Velocity drag. Teams that localize manually report spending significant engineering hours per release cycle on file wrangling rather than product work.

What "Shift-Left" Means for Localization

"Shift-left" is borrowed from testing culture: catch problems earlier in the pipeline, where they're cheaper to fix. Applied to localization, it means treating translated strings as build artifacts that are produced, validated, and merged as part of the same CI/CD pipeline that runs your linter and test suite.

In a shift-left model:

• String extraction happens at commit time, not release time.
• Translation requests are triggered by webhooks or pipeline stages, not calendar reminders.
• Translated assets are pulled back into the repo and validated before merge, not after deploy.
• Missing locales block the build the same way a failing test would.

This isn't aspirational, it's how mature engineering organizations handle localization at scale. The architecture relies on TMS APIs that support push, pull, async job management, and webhook notifications.

Architecture Overview: Git → CI → TMS API → Artifact

The core loop of a repo-connected localization pipeline has four stages:

1. Commit. A developer pushes code containing new or changed strings to a feature branch.
2. Extract and push. The CI pipeline detects changed resource files, diffs them against the previous state, and pushes new or modified strings to the TMS via API.
3. Translate and review. The TMS routes strings through machine translation, human review, or both. When translation is complete, a webhook fires back to the CI system.
4. Pull and merge. The pipeline pulls translated files from the TMS, validates placeholder integrity and file format correctness, and commits them back to the branch or opens a pull request.

┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ Git │────▶│ CI/CD │────▶│ TMS API │────▶│ Review │
│ Commit │ │ Pipeline│ │ (Push) │ │ + MT │
└──────────┘ └──────────┘ └──────────┘ └──────────┘
▲ │
│ Webhook fires │
└─────────────────────────────────┘
Pull translated assets

This architecture works with any CI system, GitHub Actions, GitLab CI, Jenkins, CircleCI, Bitbucket Pipelines, and any TMS that exposes push/pull endpoints and webhook registration.

String Extraction and Diff Strategies

Detecting Changed Keys Across Commits

Pushing your entire resource file to the TMS on every commit is wasteful and can re-trigger translations for strings that haven't changed. Instead, diff only the strings that were added, modified, or removed.

A straightforward approach uses git diff to identify changed resource files, then a lightweight script to compare keys:

# Identify changed resource files in this commit
CHANGED_FILES=$(git diff --name-only HEAD~1 HEAD -- 'src/locales/en/*.json')

for FILE in $CHANGED_FILES; do
# Extract only new or modified keys
python3 scripts/diff_keys.py \
--previous <(git show HEAD~1:"$FILE") \
--current "$FILE" \
--output /tmp/changed_keys.json
done

The diff_keys.py script compares the previous and current versions of the JSON file key by key, emitting only entries where the value changed or the key is new. Deleted keys can be flagged separately for cleanup in the TMS.

Handling JSON, YAML, XLIFF, and Other Formats

Different frameworks use different resource file formats. Your extraction and diffing logic needs to handle the formats your codebase uses:

When diffing, parse each format into a normalized key-value structure before comparison. Libraries like i18next-parser for JSON or Python's polib for PO files handle format-specific parsing so your diff logic stays format-agnostic.

Placeholder Safety and Validation

Placeholders, {username}, {{count}}, %d, %@, are the most fragile part of any translated string. A translator or MT engine that drops, reorders, or corrupts a placeholder will cause runtime crashes or garbled output.

Build placeholder validation into your pipeline:

1. Extract placeholders from the source string using a regex pattern appropriate to your format (e.g., \{[^}]+\} for ICU-style).
2. After translation, verify that every placeholder present in the source also appears in the target, in a syntactically valid form.
3. Fail the pipeline if a placeholder is missing or malformed, and flag the specific string and locale for review.

import re

def validate_placeholders(source: str, target: str) -> list[str]:
pattern = r'\{[^}]+\}'
source_ph = set(re.findall(pattern, source))
target_ph = set(re.findall(pattern, target))
missing = source_ph - target_ph
return [f"Missing placeholder: {p}" for p in missing]

This check should run as a gate before translated files are committed back to the repo.

Push/Pull Patterns via TMS APIs

Uploading Source Strings on Commit

Most TMS platforms expose a file upload or key-value push endpoint. The general pattern is:

1. Authenticate with an API key or OAuth token.
2. Identify the project and branch (some platforms support branch-aware projects natively).
3. Upload the changed source file or post individual key-value pairs.

Here's a generic curl example for uploading a JSON resource file:

curl -X POST "https://api.example-tms.com/v2/projects/${PROJECT_ID}/upload" \
-H "Authorization: Bearer ${TMS_API_TOKEN}" \
-F "file=@src/locales/en/messages.json" \
-F "file_format=json" \
-F "update_translations=false" \
-F "tags=release-4.2"

Key parameters to control:

• update_translations: Set to false if you only want to push source strings without overwriting existing translations.
• tags or branch: Tag uploaded strings so you can pull translations for a specific release or feature branch.
• cleanup_mode: Some APIs let you mark keys not present in the upload as deprecated, which helps keep the TMS in sync with the repo.

Pulling Translated Files After Completion

Once translations are ready, signaled by a webhook or polled via a status endpoint, pull the translated files back:

curl -X GET "https://api.example-tms.com/v2/projects/${PROJECT_ID}/download" \
-H "Authorization: Bearer ${TMS_API_TOKEN}" \
-G -d "locale=fr" -d "file_format=json" \
-o src/locales/fr/messages.json

For projects with many locales, batch the downloads:

LOCALES="fr de ja ko pt-BR zh-Hans"
for LOCALE in $LOCALES; do
curl -s -X GET "https://api.example-tms.com/v2/projects/${PROJECT_ID}/download" \
-H "Authorization: Bearer ${TMS_API_TOKEN}" \
-G -d "locale=${LOCALE}" -d "file_format=json" \
-o "src/locales/${LOCALE}/messages.json"
done

Sync vs. Async: When to Poll, When to Wait

Some TMS APIs process uploads synchronously, the response includes the result immediately. Others return a job ID for asynchronous processing.

• Synchronous endpoints are simpler but can time out for large files. Use them when you're pushing small diffs (under a few hundred keys).
• Asynchronous endpoints return immediately with a job ID. You then either:
• Poll the job status endpoint at intervals until completion.
• Register a webhook that the TMS calls when the job finishes.

Polling example:

# Submit async job
JOB_ID=$(curl -s -X POST ".../upload" ... | jq -r '.data.job_id')

# Poll until complete
while true; do
STATUS=$(curl -s -H "Authorization: Bearer ${TMS_API_TOKEN}" \
"https://api.example-tms.com/v2/jobs/${JOB_ID}" | jq -r '.data.status')
if [ "$STATUS" = "completed" ]; then break; fi
if [ "$STATUS" = "failed" ]; then echo "Job failed"; exit 1; fi
sleep 10
done

Webhooks are preferred for production pipelines because they eliminate wasted poll cycles and reduce API call volume against rate limits.

Branch-Based Workflows and Merge Strategies

Feature-Branch Isolation for In-Progress Translations

Branch-based localization prevents half-finished translations from leaking into your main branch. The pattern:

1. Developer creates feature/onboarding-v2 and adds new strings.
2. CI pushes those strings to the TMS, tagged with the branch name.
3. Translations proceed in the TMS against that branch's string set.
4. When translations are complete, CI pulls them into the same feature branch.
5. The PR now includes both the code changes and the corresponding translations.

This keeps main clean, only fully translated features get merged. Some TMS platforms (Phrase, Crowdin) have native branch support. Others require you to simulate branches with tags or separate project keys. Ollang supports branch-aware workflows via branch metadata and tags exposed through its API.

Resolving Merge Conflicts in Resource Files

Resource file merge conflicts are the most common failure mode in repo-connected localization. Two branches modify the same locale file, and Git can't auto-merge.

Mitigation strategies:

• Sort keys deterministically. If your JSON or YAML keys are always alphabetically sorted, Git's merge algorithm handles concurrent additions cleanly in most cases.
• Use one-key-per-line formatting. Compact JSON with multiple keys on one line maximizes conflict surface. Pretty-printed, sorted JSON minimizes it.
• Automate conflict resolution. A post-merge script can parse both sides of a conflict, merge the key-value maps programmatically, and write a clean file. Since resource files are structured data, this is safer than text-level merge.
• Adopt a single source of truth. If the TMS is authoritative for translations, always overwrite local translations with the TMS version on pull. Conflicts only arise in the source language file, which the developer controls.

Webhook-Driven Translation Triggers

Firing MT + Review on Every Commit

Webhooks are the nervous system of a repo-connected pipeline. Configure two directions:

• Git → CI → TMS (outbound): Your CI platform fires on push events. The pipeline extracts changed strings and pushes them to the TMS API. This is typically handled by the CI YAML configuration, not a webhook per se, it's event-driven via the CI trigger.
• TMS → CI (inbound): Register a webhook in your TMS that fires when a translation job completes, a review is approved, or a specific status changes. The webhook payload hits an endpoint you control (a serverless function, a CI webhook trigger, or a dedicated microservice) that kicks off the pull-and-merge stage.

Example webhook payload from a TMS:

{
"event": "translation.completed",
"project_id": "abc123",
"locale": "de",
"branch": "feature/onboarding-v2",
"completed_keys": 47,
"timestamp": "2025-01-15T14:32:00Z"
}

Your handler parses this, triggers a CI pipeline run for the specified branch, and the pipeline pulls the German translations and commits them.

Configuring Webhook Endpoints Securely

Webhook endpoints are attack surface. Protect them:

• Validate signatures. Most TMS platforms sign webhook payloads with an HMAC secret. Verify the signature before processing.
• Use HTTPS only. Never expose a webhook receiver over plain HTTP.
• Scope permissions. The webhook handler should have the minimum permissions needed, typically read from the TMS and write to the repo.
• Idempotency. Webhooks can fire multiple times for the same event. Design your handler to be idempotent, pulling translations that are already up to date should be a no-op, not a duplicate commit.

Sample CI YAML: End-to-End Pipeline

Below is a GitHub Actions workflow that demonstrates the full loop: detect changed strings, push to a TMS API, wait for translations, pull them back, validate placeholders, and commit.

name: Localization Pipeline

on:
push:
paths:
- 'src/locales/en/**'

jobs:
push-strings:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 2

- name: Detect changed locale files
id: diff
run: |
FILES=$(git diff --name-only HEAD~1 HEAD -- 'src/locales/en/')
echo "changed_files=$FILES" >> $GITHUB_OUTPUT

- name: Extract changed keys
if: steps.diff.outputs.changed_files != ''
run: |
python3 scripts/diff_keys.py \
--previous <(git show HEAD~1:src/locales/en/messages.json) \
--current src/locales/en/messages.json \
--output /tmp/changed_keys.json

- name: Push to TMS
if: steps.diff.outputs.changed_files != ''
env:
TMS_API_TOKEN: ${{ secrets.TMS_API_TOKEN }}
TMS_PROJECT_ID: ${{ secrets.TMS_PROJECT_ID }}
run: |
curl -X POST "https://api.example-tms.com/v2/projects/${TMS_PROJECT_ID}/upload" \
-H "Authorization: Bearer ${TMS_API_TOKEN}" \
-F "file=@/tmp/changed_keys.json" \
-F "file_format=json" \
-F "branch=${GITHUB_REF_NAME}" \
-F "update_translations=false"

pull-translations:
runs-on: ubuntu-latest
# Triggered by repository_dispatch from webhook handler
if: github.event_name == 'repository_dispatch'
steps:
- uses: actions/checkout@v4

- name: Pull translations for all locales
env:
TMS_API_TOKEN: ${{ secrets.TMS_API_TOKEN }}
TMS_PROJECT_ID: ${{ secrets.TMS_PROJECT_ID }}
run: |
for LOCALE in fr de ja ko pt-BR zh-Hans; do
curl -s -X GET \
"https://api.example-tms.com/v2/projects/${TMS_PROJECT_ID}/download" \
-H "Authorization: Bearer ${TMS_API_TOKEN}" \
-G -d "locale=${LOCALE}" -d "file_format=json" \
-o "src/locales/${LOCALE}/messages.json"
done

- name: Validate placeholders
run: python3 scripts/validate_placeholders.py src/locales/

- name: Commit and push translations
run: |
git config user.name "localization-bot"
git config user.email "l10n-bot@example.com"
git add src/locales/
git diff --cached --quiet || \
(git commit -m "chore(l10n): pull translations [skip ci]" && git push)

Key details in this workflow:

• fetch-depth: 2 ensures the previous commit is available for diffing.
• [skip ci] in the commit message prevents an infinite loop where the translation commit triggers another pipeline run.
• repository_dispatch is used as the trigger for the pull job, fired by a lightweight webhook handler (e.g., an AWS Lambda or Cloudflare Worker) that receives the TMS webhook and dispatches to GitHub.
• Secrets are stored in GitHub's encrypted secrets store, never hardcoded.

Secrets Management and Permission Scopes

Storing API Tokens Safely

TMS API tokens grant access to your translation projects, treat them like database credentials.

• Use your CI platform's secrets manager. GitHub Actions has encrypted secrets, GitLab CI has CI/CD variables with masking, and Jenkins has the Credentials plugin. Never commit tokens to the repo.
• Rotate tokens regularly. Set a calendar reminder or use short-lived tokens if the TMS supports OAuth with refresh flows.
• Separate read and write tokens where possible. The push job needs write access; a monitoring job only needs read.

Scoping Permissions to Minimum Necessary

Apply the principle of least privilege:

• The CI bot's Git token should have write access only to the locales directory, not the entire repo. GitHub's fine-grained personal access tokens or deploy keys can enforce this.
• The TMS API token should be scoped to the specific project, not the entire organization.
• Webhook secrets should be unique per endpoint. If one is compromised, you revoke and rotate only that secret.

Comparing TMS API Capabilities

Not all TMS APIs are created equal. The table below compares key API features across major platforms relevant to repo-connected pipelines.

Ollang stands apart as an AI execution layer rather than a point TMS tool. Where platforms like Phrase or Crowdin focus on translation project management, Ollang covers the full localization spectrum, text, video, audio, software, websites, and legal documents, with built-in translation quality review and API integration designed for enterprise CI/CD pipelines. That API-first execution-layer design enables direct repo-connected localization across multiple content types from a single integration.

Glossary and Translation Memory Endpoints

Glossary and translation memory (TM) endpoints are critical for consistency. A glossary enforces that "dashboard" is always translated as "Tableau de bord" in French, while TM leverages previously translated segments to reduce cost and turnaround.

In your CI pipeline, you can:

• Pre-load glossary terms before pushing strings, ensuring MT engines respect your terminology.
• Query TM to identify strings with high-confidence existing translations, skipping them from the MT queue.
• Update TM after human review, feeding approved translations back for future leverage.

Platforms vary in how they expose these. Phrase and Crowdin offer dedicated glossary CRUD endpoints. Smartling integrates glossary enforcement into its translation workflow automatically. Ollang provides programmatic control over terminology and TM leverage across all supported content types through its API.

Async Jobs, Rate Limits, and Throughput

Rate limits determine how aggressively your pipeline can push and pull. Exceeding them results in 429 Too Many Requests responses and failed pipeline runs.

Best practices:

• Batch uploads. Instead of one API call per key, upload the entire changed file in a single request.
• Respect Retry-After headers. When you hit a rate limit, back off for the duration specified.
• Use async jobs for large uploads. Synchronous uploads that process thousands of keys will time out. Async endpoints return immediately and process in the background.
• Cache download responses. If translations haven't changed since the last pull (check via ETags or last-modified timestamps), skip the download.

If your pipeline runs across dozens of repos or microservices, consider a centralized localization orchestrator that queues TMS API calls and respects rate limits globally, rather than each repo's pipeline competing for the same quota.

Failure Modes and Remediation

Merge Conflicts in Locale Files

As discussed earlier, merge conflicts are the most frequent failure. When they occur:

1. Detect automatically. Your CI script should catch a non-zero exit code from git merge or git rebase.
2. Attempt programmatic resolution. Parse both sides of the conflict as structured data (JSON, YAML), merge the key maps, and write a clean file.
3. Fall back to human review. If programmatic resolution fails (e.g., the same key has different source strings on each branch), open a PR with conflict markers and assign it to the localization team.

Missing Locales and Incomplete Translations

A build that ships with missing locale files is worse than a build that fails. Guard against this:

• Define a locale manifest. A simple config file listing required locales (e.g., ["en", "fr", "de", "ja"]). The pipeline checks that every locale has a corresponding file after pulling translations.
• Set a completion threshold. Some teams require 100% translation before merge. Others accept 95% and ship with fallback to the source language. Make this configurable.
• Alert on missing locales. If a pull returns an empty file or a 404 for a locale, the pipeline should fail loudly and notify the localization team via Slack, email, or your incident channel.

REQUIRED_LOCALES="fr de ja ko"
for LOCALE in $REQUIRED_LOCALES; do
FILE="src/locales/${LOCALE}/messages.json"
if [ ! -s "$FILE" ]; then
echo "ERROR: Missing or empty locale file for ${LOCALE}"
exit 1
fi
done

Webhook Delivery Failures

Webhooks are not guaranteed delivery. TMS platforms typically retry a few times, but if your endpoint is down during all retries, you'll miss the event.

Mitigations:

• Implement a polling fallback. Run a scheduled pipeline (e.g., every 30 minutes) that checks for completed translations, independent of webhooks.
• Log all webhook receipts. If a translation seems stuck, check whether the webhook was received and processed.
• Use a dead-letter queue. Route failed webhook deliveries to a queue for manual or automated retry.

API Errors, Timeouts, and Retries

Network failures and API errors are inevitable. Build retry logic into your pipeline:

• Retry with exponential backoff for transient errors (5xx, timeouts, connection resets).
• Fail fast on client errors (4xx) except 429, which should trigger a backoff-and-retry.
• Set a maximum retry count. Three retries with exponential backoff (2s, 4s, 8s) is a reasonable default.
• Log the full error response. TMS APIs often include error codes and messages in the response body that help diagnose issues quickly.

Scaling the Pipeline Across Repositories

For organizations with dozens or hundreds of microservices, each with its own locale files, a per-repo pipeline can become unwieldy. Consider:

• A shared localization GitHub Action or GitLab CI template that each repo includes. Update the template once, and all repos pick up the change.
• A centralized localization service that receives push events from all repos, batches TMS API calls, and distributes translations back. This is especially useful for staying within rate limits.
• Monorepo-aware diffing that scans only the packages or services that changed, rather than re-processing the entire tree.

Ollang supports centralized orchestration across text, software, and media to reduce vendor sprawl and simplify enterprise-scale pipelines. See Ollang's enterprise API in action.

Frequently Asked Questions

How do I prevent CI loops when committing translated files back to the repo?

Include a skip directive in your commit message, such as [skip ci] for GitHub Actions and GitLab CI, or [ci skip] for some other platforms. Alternatively, configure your pipeline trigger to ignore commits made by the localization bot's user account. Both approaches prevent the translated file commit from triggering another pipeline run.

Can I use repo-connected localization with a monorepo?

Yes. The key is scoping your pipeline trigger to specific paths (e.g., on.push.paths: 'packages/*/locales/en/**') so that only changes to source locale files trigger the localization pipeline. Your extraction script should then identify which package changed and push only those strings to the TMS, tagged with the package name for clean separation.

What happens if the TMS API is down during a pipeline run?

Your pipeline should implement retry logic with exponential backoff for transient errors. As a safety net, run a scheduled "catch-up" pipeline that polls the TMS for any completed translations that may have been missed due to webhook or push failures. This ensures translations are never permanently lost due to a temporary outage.

How do I handle pluralization rules that differ across locales?

Use a format that supports plural categories natively, such as ICU MessageFormat, .stringsdict for iOS, or ARB for Flutter. Your diffing and validation scripts need to be plural-aware, a string with {count, plural, one {# item} other {# items}} in English may have six plural forms in Arabic. Validate that the translated string includes all plural categories required by the CLDR plural rules for the target locale.

Get Started with Automated Localization

A well-wired repo-connected pipeline turns localization from a bottleneck into a background process. Strings flow from commit to translation to merged artifact without manual intervention, and your build fails clearly when something goes wrong rather than silently shipping broken locales.

Whether you're connecting a single app or orchestrating localization across an enterprise portfolio of services, content types, and media formats, Ollang provides the API execution layer to make it work reliably.

Ready to connect your repo?

Book a Demo