Arkian logo
Start free
Menu
← All articles

Localization in CI/CD: A Practical Setup for Small Teams

Localization in CI/CD: A Practical Setup for Small Teams

Developer validating generated localization files

Localization belongs in CI/CD when translated files are treated like any other build artifact: generated from an approved source, validated automatically, and merged through a normal review. For a small team, the useful version is not a heavy platform wired into every commit. It is a short, repeatable path: source strings in, checked language files out, with secrets protected and nothing shipping unreviewed.

This guide covers what to automate, what to gate, how to handle credentials and content security, and how to keep the whole thing light enough that two or three people can run it.

Arkian
arkian.ai
Simplify Localization for Small Teams
Arkian automates multilingual scripts, voice outputs, validation, and packaged language files without requiring repository access or a complex TMS.
Visit Arkian

TL;DR

  • Separate strings from code, use stable keys, and keep plural rules and placeholders intact. Automation fails on messy source first.
  • Put validation (placeholders, plurals, file syntax) in CI as a failing check. Put translation generation on release events, not every commit.
  • Store any translation service credentials as encrypted CI secrets, scope them narrowly, and never print them in logs.
  • Small teams can skip repository access for outside services and skip a full TMS by exchanging reviewable packages instead of live syncs.
  • Arkian produces validated, packaged language files (JSON, iOS strings, Android XML, YAML) and voice output without repository access.

Table of Contents

What localization in a pipeline actually means

Many developers assume localization is translation with a different name. It is wider. Mozilla’s internationalization guide describes the split: internationalization is the engineering work of separating text from code and formatting data by locale, while translation is converting the words. Dates, numbers, currency, plural forms and cultural fit all sit on the localization side.

In a CI/CD context, that gives you three jobs the pipeline can own:

  1. Extraction: pulling source strings from the code or a source file into a translatable format.
  2. Production: generating the target-language files, and any voice or metadata assets that go with them.
  3. Verification: proving the output is structurally safe to ship before anyone merges it.

The first and third are deterministic and cheap to automate. The second is where teams make choices about speed, cost and human review. If you want the planning view for a team with few people, our practical localization plan for small teams covers the scoping decisions.

Fix the source before you automate anything

A pipeline amplifies whatever you feed it. If your source strings are inconsistent, you will produce inconsistent output in every language, faster.

Stable, structured keys

Use a naming convention that carries context, such as namespace.component.action. Without it, managing thousands of strings across languages gets unmaintainable, and translators (human or automated) lose the context they need. A key like checkout.button.pay tells everyone where the text lives. A key like string_417 tells no one anything.

Never concatenate

Building a sentence from fragments breaks in languages with different word order. Pass the whole sentence as one string with named placeholders. For lists, use locale-aware formatting rather than joining with commas by hand: JavaScript’s Intl.ListFormat has been available across browsers since April 2021.

Plurals are not “one or many”

English has two plural forms. Other languages do not. Unicode CLDR defines up to six plural categories (zero, one, two, few, many, other), and which ones apply depends on the language. A pipeline that outputs only “one” and “other” for every locale will quietly ship grammar errors. Our guide to CI-ready batch translation that keeps plurals and placeholders shows how to keep those intact in bulk runs.

Numbers and dates

Hardcoded formats are the most common localization bug that no translator can fix. Format at render time from the user’s locale. Our developer’s field guide to number and date localization goes through the traps.

A pipeline shape that works for small teams

The popular advice is to trigger localization on every commit, pull request and release. That suits larger teams with a localization manager and a TMS. With a handful of people, constant syncing creates noise: partial strings get translated, reviewers see churn, and costs climb for text that will change tomorrow.

A calmer arrangement has four stages.

Stage Trigger What runs Blocks merge?
Lint source Every pull request Key naming, placeholder syntax, duplicate keys, empty values Yes
Freeze source Release branch cut or tag Approved source file is the single input No
Produce languages Manual or release event Translation, voice, metadata generated and packaged No
Validate and review Pull request with the new language files Placeholder parity, plural completeness, file syntax, diff review Yes

The important design choice is the freeze. Translating from an approved source, rather than from whatever is on main at 3 p.m., means every language ships from the same text. It also means the reviewer looks at one diff instead of fifty.

Skip what did not change

Only send changed or new strings for production. Re-translating unchanged text wastes money and can overwrite reviewed wording. Our piece on packaging translations for release without re-uploading unchanged files explains the approach, and translation memory helps keep approved phrasing stable between releases.

Changed strings routed while approved strings remain

Validation gates worth failing a build for

The pipeline’s best contribution is not translation. It is refusing to ship broken files. These checks are cheap and catch most production incidents:

  • Placeholder parity: every {name}, %s or %1$d in the source must appear in the translation, with matching types.
  • Plural completeness: each locale has every category CLDR requires for it.
  • Syntax validity: JSON parses, YAML loads, Android XML is well formed and escaped, iOS .strings entries end with semicolons.
  • Key parity: no missing or orphaned keys against the source file.
  • Length sanity: flag translations that are many times longer than the source, which often signals a runaway output or a UI overflow.
  • Emoji and special characters: confirm they survive round trips. See our notes on handling emojis in translations.

For iOS teams using exchange files, the XLIFF workflow guide covers stage-by-stage checks and common Xcode fixes. A reusable localization project template can hold these checks as a standing QA checklist.

Secure translation delivery and localization data security

Once a pipeline calls an outside service, it handles two sensitive things: credentials and your unreleased content. Treat both deliberately.

Credentials

The standard pattern is to store any translation service API key as an encrypted secret in your CI settings, not in code. GitHub’s documentation on encrypted secrets notes that this lets workflows call services without exposing credentials in the repository. Practical rules that follow:

  • Scope secrets to the narrowest level possible: an environment or a single repository rather than the whole organization.
  • Use fine-grained permissions wherever the platform offers them.
  • GitHub redacts secrets printed to workflow logs, but you should still never print them on purpose, and never echo values derived from them. The same guide notes that a repository can hold up to 100 secrets, which is plenty if you keep one per service.
  • A workflow can only read a secret you explicitly pass to it as an input or environment variable. Review any third-party action before handing it one. GitHub’s current guide to using secrets in Actions walks through creating repository secrets through the web interface and the command line.
  • Rotate keys when someone leaves the team.

Content

Unreleased strings can reveal roadmaps, pricing and feature names. Before sending anything out, decide:

  1. What leaves your boundary. Send only the strings file, not source code. A service that needs repository access to work is asking for far more than translation requires.
  2. Who can see it. Know which people and systems handle the text, and whether a human reviewer is part of the loop.
  3. How it comes back. Prefer a package you can inspect and diff before it touches your branches over a service that pushes commits directly.

That last point is the core of a lean, secure setup: the exchange happens through files you control, and merging stays a human decision. Do your own due diligence on any vendor’s retention and handling terms, and confirm them in writing if your content is confidential.

Do you need a TMS?

A translation management system earns its place when you have many contributors, many reviewers, large glossaries and a localization manager to run it. For a two-to-five person team shipping an app in three to ten languages, it often adds accounts, syncs and settings that nobody has time to maintain.

What you actually need can be listed in a few lines:

  • A frozen, approved source file
  • A way to produce target-language files in the formats your platforms use
  • Automated validation
  • A reviewable package and a clean diff
  • A glossary so product terms stay consistent. Our five-step glossary guide shows how to build one without special tooling.

If your team outgrows that, a TMS is a reasonable next step. Until then, the lighter path is easier to secure, because fewer systems touch your content.

Our perspective

We built Arkian for small teams because the usual advice assumes resources they do not have. Continuous localization guidance tends to describe a system that syncs with your repository, tracks every string in a TMS and routes work to a bench of linguists. Teams of a few people do not need all of it. They need the end product: correct files in the right formats, validated, ready to review.

So we start from an approved source and produce the outputs: translated strings, voice, metadata and the packaging around them. We do that without asking for repository access, because we think the safest credential is the one you never had to hand over. Your pipeline stays yours. You decide when a package enters it.

We also think the most valuable automation is the boring kind. Checking that a plural category is present, that a placeholder survived, that a file parses: none of this is glamorous, yet this is what stops a bad release in Portuguese or Polish when nobody on the team reads those languages. Our work with the Quiet Harbour app, described in the Quiet Harbour case study, was about exactly that: a coherent product experience across languages, not a pile of disconnected files.

— Arkian

Beyond strings: voice, metadata and SEO files

Pipelines that handle only UI strings leave work behind. If your product has audio prompts, onboarding narration or store listings, those assets need the same discipline: one approved source, consistent terminology, reviewable output.

Web teams have a parallel concern. Language alternates for search engines go out of date as pages change, and one approach is automating hreflang in CI/CD so the tags regenerate whenever content does. The principle is the same as for strings: generate from a single source and let the build verify it.

For app stores, see our guide to app store localization without manual file work.

Where Arkian fits

Arkian produces the localization assets and packages them so your pipeline only has to review and merge. That includes localization strings, multilingual voice production, metadata and structured packaging into JSON, iOS strings, Android XML, YAML and MP3/WAV, with no repository access and no TMS to run.

Where Arkian fits — overview diagram

Pricing is published on the pricing page: a membership at 19.00 CAD per month, or one-off credit packs at 29.00 CAD (Starter), 79.00 CAD (Pro) and 249.00 CAD (Studio). If you are sizing a first release, the smaller packs are a low-commitment way to run a single production job and inspect the package before changing anything in your pipeline.

A starter checklist

  1. Adopt a key convention and refactor hardcoded strings.
  2. Replace concatenation with whole-sentence strings and named placeholders.
  3. Add a lint job for keys and placeholders on every pull request.
  4. Define your freeze point: the tag or branch where source is approved.
  5. Produce language files from the frozen source only.
  6. Run validation (placeholders, plurals, syntax) as a required check.
  7. Review the diff, merge, and archive the package with the release.
  8. Store any service credentials as scoped encrypted secrets, and rotate them on staff changes.

Start with one language. Once the path works end to end, adding the next is a configuration change rather than a project.

FAQ

What is localization in CI/CD?

It is the practice of making translation and locale adaptation part of your automated build and release process. Source strings are extracted, language files are produced, and checks run before the files merge. The goal is that new languages and updated text ship with the same reliability as code.

Should localization run on every commit?

Not necessarily. Linting source strings on every pull request is cheap and useful. Producing translations is better tied to a frozen source at release time, especially for small teams, so you avoid translating text that is still changing and keep review diffs readable.

How do I keep translation API keys secure in a pipeline?

Store them as encrypted secrets in your CI platform, scope them to the narrowest level, and pass them only to the steps that need them. Do not print them in logs, and rotate them when team members leave. GitHub’s encrypted secrets documentation describes the mechanism.

Do I need repository access to use an outside localization service?

It depends on the service. Many integrations ask for it so they can sync files directly, but translation only needs the strings. Exchanging reviewable packages instead keeps your code private and leaves merging in your hands.

What breaks most often in automated localization?

Placeholders and plurals. A dropped variable crashes or garbles a message, and a missing plural category produces wrong grammar in languages that need more than two forms. Both are easy to catch with automated validation.

Sources