Integrating Your CI/CD Pipeline With Your Translation Pipeline

Most software companies start with product localization, which at a high level, involves integrating your translation management system with your code repository and deployment pipeline. This article is not intended as a vendor specific implementation guide but instead discusses the tasks you’ll typically need to address. Most TMS platforms work in similar ways, which makes this a useful reference regardless of which you choose.

In general, a good CI/CD integration will do the following:

Use linters to check for common sources of localization and internationalization issues during a build (this is super important)
Upload screenshots associated with pull requests, to provide visual context to AI and human translators
Upload source language message catalogs and other translatable assets to the TMS.
In addition a cron job will periodically poll the TMS to retrieve update translations and merge those into the code repository

Linters (Build Time Checks)

This is an important QA step that if properly implemented will catch a lot of common issues before translation is even started.

Missing Or Unclear Context

One of the number one causes of translation errors is missing or insufficient context. A simple test is to measure the length of the context message associated with a string. If it is missing or shorter than N characters, the build fails with a “missing context” error message.

A more sophisticated approach would be to submit new messages to an AI coding assistant along with a prompt that asks it if the message and context instructions are clear. If not, you probably don’t want to fail the build, but you can flag this in a build report.

ICU Message Defects

Another source of translation problems are improperly formatted ICU messages. This is a form of markup that is used in localizable strings to insert interpolated values, deal with pluralization and other situations.

It is probably not necessary to develop a test that understands all of the edge cases in this spec, but rather look for common sources of problems like unclosed parentheses, etc. Subtler issues like gender and pluralization are harder to spot via automation.

Pro tip : use AI to assess how well formed new ICU messages are with a prompt like “This following is an ICU MessageFormat. Does it comply with this standard, or is it incorrectly formatted? Reply with ‘correct’, ‘possible error’ or ‘severe error’, followed by an explanation of the defect.

Due to the risk of false positives, you don’t want to fail a build, but these results can be piped into a report on possible source issues in localization.

Screenshots

Good TMS platforms allow you to upload screenshots to provide translators with visual context. This is super helpful in app localization because UI messages are often composed of single words or sentence fragments. Because English words are gender neutral and can often be a noun or a verb, it is often unclear what the intended meaning is.

What the TMS will do is run the screenshot through OCR (optical character recognition) to map UI texts to strings that have been submitted to the TMS. Then when a translator is working on that message, they will see the screenshot in an adjacent window, and can reference that. This can also be used in AI translation workflows as context that is given to the AI service in a prompt. There are a couple of ways to do this.

One is to use screenshots associated with pull requests as a source. So whenever a PR is created that has screenshot attached, this triggers an action that results in the screenshots being extracted and uploaded to the TMS API. If you require screenshots with PRs this is a good way to go.

Another way to go is to extract screenshots from automated QA test cycles and bulk upload those to the TMS on a regular cadence. This may work better if you do not systematically require screenshots in PRs since the QA coverage is automated and probably more extensive. You can also set up a basic QA test suite and covers the most frequently used paths through your service.

On this topic automated QA testing platforms like Playwright, Selenium and similar tools can be confugured to capture screenshots which can then be automatically piped into the TMS platforms on a regular schedule.

Uploading Source Language Catalogs

This automation should be triggered whenever a PR is merged into your main branch. If you are using static message catalogs, all this script does is upload your source language message catalogs to the TMS API. If you are using a wrapper function to display messages, the automation will generate message catalogs at build time by extracting the input values and writing them out to whichever file format you want (JSON, strings.xml, etc).

Most TMS platforms including CrowdIn, Lokalise, Phrase, Smartling and Transifex provide command line (CLI) tools or Github actions. Consult vendor documentation before building custom scripts. Most common implementations are often already covered.

Downloading Translations

This is an area where it is best to keep things simple. Translations come back at unpredictable intervals, often with a few that take a long time due to discussion about terminology and whatnot. At most of the places I worked, we had a cron job that ran a few times a day to download translated catalogs and force merge them into the main branch. This is generally good enough. Using event based triggers and webhooks doesn’t really buy you anything, but rather is an example of sending something to the Department of Over-optimization Department.

AI and machine translations come back very quickly, so you will almost always have okay placeholder translations. As human reviewers have a chance to review and post-edit, those updates will flow in over a few days depending on your SLA with language service providers. Most companies don’t push updates directly to production except for urgent bug fixes, so by the time real users see anything, it has likely been reviewed and approved.

A note about merge conflicts. It is best if you treat the translated message catalogs as auto-generated assets and exclude them from normal merge conflict resolution. If the source message catalogs are manually created and maintained, you probably want to include them so that conflicts are detected there.

Discussion : When To Queue Content For Translation

One decision to make is whether to pick up source material for translation from feature branches or from a pre-release branch (typically main or master).

My opinion is that trying to track dozens of variants of message catalogs is a nightmare, and it also leads to unnecessary translation work because the user facing text is a moving target at this stage. The “earlier is better” logic is compelling, but you’ll typically have a 2-3 day baseline SLA with vendors which is pretty fast.

One thing you can do to upstream translation work is to build out a mockup of the feature and associated messages, and check that into the main branch, so that content gets picked up and translated.

Conclusions

Integrating your CI/CD pipeline with your TMS is simpler than you might expect. A few scripts and a cron job get you 90% of the way there. TMS platforms have integrations that work with major repos like Github and Bitbucket out of the box so you might not even to write custom scripts.

The most important thing is good linter coverage, to prevent common sources of errors from getting into the translation pipeline in the first place.