Automating the Localization Pipeline: Extraction to TMS to CI

- Designing a resilient end-to-end localization workflow - Automating string extraction and reliable TMS integration - CI/CD localization: keep translations in the delivery loop - Quality gates, metadata, and screenshot-driven reviews - Scaling releases: branching, releases, and safe rollbacks - Practical Application: checklists, scripts, and example CI jobs Localization is not a feature you ship once — it’s a continuous engineering pipeline that must be designed, instrumented, and automated with the same rigor you apply to CI/CD. When you treat translations as a manual, after-the-fact task, releases slow down, context is lost, and UX breaks in languages you thought you covered. Manual copy handoffs create the obvious symptoms: late translations, PR noise, mismatched placeholders, and translators working blind. You likely see long review cycles, translators asking for context, and last-minute reverts when translated copy causes layout breakage. These are not people problems — they’re pipeline problems. Designing a resilient end-to-end localization workflow An engineering-grade localization pipeline treats language assets as first-class artifacts. The minimal architecture I use on large products looks like this: - Source-of-truth: code repo contains only keys + default (base) language (or message descriptors). No hardcoded UI strings in templates or components. Make every user-facing string akey that maps to a translation unit. - Extraction stage: code → canonical resource file(s) (JSON/XLIFF) via extraction tooling. Extraction preserves id ,defaultMessage ,description andsource location metadata. Use the ICU Message Format for complex plural/gender logic so translators can handle language rules predictably. - TMS (authoring) stage: extracted messages are pushed to the TMS (Crowdin / Lokalise). Translators and reviewers work in the TMS with context (screenshots, in‑context editor) and TM/glossary support. Crowdin and Lokalise both surface screenshots and in‑context editing to translators. - Pull and deliver stage: translations are pulled from the TMS, validated, and introduced as commits/PRs (or delivered OTA/CDN) back into the app. PRs provide the usual review, QA and can be gated by automated checks. Crowdin and Lokalise both provide CLI/Actions to automate push/pull workflows and create PRs. - Runtime: dynamic loading (lazy-load per locale or per route) so only required translation bundles are shipped to users, keeping bundle sizes healthy. Design decisions that matter - Keep the base language as canonical text, not code comments. That enables automatic diffing and consistent TM suggestions. - Use description andextract-source-location in your message descriptors; they become context metadata your translators will actually use.formatjs extraction supports this metadata in the output. - Treat translations as deployable artifacts: versioned, testable, and revertible. Important: Treat the TMS as the translator’s workbench, not the engineering system of record. The code repo + tagging/filenames remain the ultimate source for runtime assets; the TMS should sync with it reliably. Automating string extraction and reliable TMS integration The single biggest win is reliable, repeatable extraction that produces the exact file layout your TMS expects. Two practical patterns: - Framework-aligned extraction: use the tool that matches your i18n stack. For React + FormatJS/React‑Intl, use @formatjs/cli to extract messages. It understandsdescription ,defaultMessage , and offers--extract-source-location to record source file + line metadata for each message. Use--format to produce a TMS-friendly JSON or XLIFF shape. - Key-based extraction (i18next/Lingui): use i18next-scanner ori18next-cli to scan and generate resource files; these tools can be extended to detect custom patterns or Trans components. Example: a small package.json script and formatjs invocation { "scripts": { "extract:i18n": "formatjs extract \"src/**/*.{ts,tsx}\" --out-file lang/en.json --extract-source-location --id-interpolation-pattern '[sha512:contenthash:base64:6]'" } } Why you must include descriptions and source locations - description gives translators function-level intent (button label vs. page title).source lets you link to screenshots or code lines in reviews. FormatJS extraction supports both. TMS integration patterns - Push-only: a CI job runs extraction and upload to the TMS via CLI. Crowdin hascrowdin upload sources andcrowdin download translations commands; these are configuration-driven and support--branch for string-based branching. - GitHub App / Actions: let the TMS create PRs for you on translation downloads; Lokalise offers push/pull GitHub Actions that will create PRs and tag branches for you. Use the TMS app when you want less custom scripting and predictable PR behaviour. File formats and interchange - Prefer TMS-native JSON for web stacks, but maintain an XLIFF or TMX export path for offline tooling or vendor handoffs; XLIFF is the standard interchange format maintained by OASIS. Use XLIFF where tool interoperability or CAT-tool workflows are required. CI/CD localization: keep translations in the delivery loop Design your CI so localization jobs run like other checks — triggered by changes to translatable code paths, not by every push. A typical flow - Developer merges UI copy or changes default copy on main /release/* . - CI job extract-and-push runs only whenpaths match your UI sources (src/** ) and executes extraction script +crowdin upload sources (orlokalise-push-action ). This uploads new/changed strings to the TMS. - Translators work in the TMS. Use TM, glossary, QA checks and screenshots. - TMS triggers an export (webhook or scheduled task). On export, a CI job pull-and-open-pr downloads translations and opens a PR with only translation file changes (or the TMS GitHub app creates it for you). Lokalise and Crowdin support creating PRs automatically. - The PR runs localized smoke tests, visual regression or pseudo-localization checks before merge. Sample GitHub Actions pattern (extract & push) name: i18n: extract-and-push on: push: paths: - 'src/**' - 'package.json' jobs: extract-and-upload: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 20 - run: npm ci - run: npm run extract:i18n - name: Upload sources to Crowdin env: CROWDIN_TOKEN: ${{ secrets.CROWDIN_TOKEN }} run: | npx @crowdin/cli upload sources Security notes: store TMS API tokens in secrets and grant minimal repo permissions to any action that creates PRs. Use the TMS-provided GitHub App or documented Actions where possible — they handle edge cases like branch tagging and PR creation. Automation triggers and pull cadence - Use a TMS webhook to trigger a pull-and-commit workflow when translations reach your quality threshold. Alternatively, schedule nightly pulls for low-latency teams. Crowdins’ and Lokalise’s APIs and marketplace apps allow automated distribution or scheduled releases. Quality gates, metadata, and screenshot-driven reviews Automated translation delivery without quality enforcement is useless. Build quality gates at multiple layers: - TMS-level QA checks: configure QA checks in your TMS to catch ICU syntax errors, placeholder mismatches, length problems, and tag/HTML mismatches. Crowdin and Lokalise provide built-in QA checks and allow custom or AI checks for organization-specific rules. Enforce those checks as Errors for critical languages. - Source metadata: include description ,max_length andcontext on each message so translators and QA tools can make correct decisions. FormatJS descriptors includedescription ;--extract-source-location produces a linkable file/line reference. - Screenshots & in-context: upload screenshots or use in-context editors so translators see copy in the UI. Crowdin and Lokalise allow automatic tagging of strings from screenshots and in-context editors that tag strings automatically. - Local/CI compile checks: run a build-time formatjs compile (or equivalent) step to verify ICU strings compile for each target locale before the PR is mergeable. Catch runtime formatting exceptions early. - Pseudo-localization and visual snapshots: run pseudo-localization in CI and a lightweight visual regression pass on critical screens so you detect overflow or LTR/RTL layout issues before shipping. Block merging with automation - Add a CI check that validates translation PRs: run crowdin status or TMS API call to assert translation coverage orprogress >= X% for required locales. Crowdin and Lokalise provide status APIs/CLI to query project progress. Callout: Annotate every extracted message with context metadata and a screenshot link. The upfront developer effort reduces translator queries and rework more than any other single measure. Scaling releases: branching, releases, and safe rollbacks As translation volume grows, you need predictable scoping and rollback capabilities. Branching and scoping - Tag strings with branch or release identifiers in your TMS so translators only see the content for the release they should work on. Lokalise and Crowdin both support branch/tag scoping on uploads and downloads (use --branch or Action parameters). This prevents translators from translating unrelated future work. - Use temporary translation branches: the TMS creates a tms-sync/ branch or PR for translation bundles. Merge only after QA and localized smoke tests complete. Release strategies - Per-release PRs: let the TMS create a single PR containing all translation updates for the release branch. Run the same merge pipeline as code changes. This reduces surprises at release time. - Over-the-Air (OTA) delivery: for web and mobile, consider OTA/CDN-based translation delivery. Crowdin’s Content Delivery (OTA) lets you push translation bundles to a CDN that your app fetches at runtime; that allows instant language fixes without a code deploy. Rollback techniques - Repo-based rollback: since pul