Arkian logo
Start free
Menu
← All articles

Developer Localization Workflow: From Strings to Release

Developer Localization Workflow: From Strings to Release

Developer reviewing localization strings at workstation

A good developer localization workflow does five things in order: it keeps text out of code, hands translators clean source strings with context, validates what comes back, packages it in the formats your platforms expect, and ties every release to the exact files it shipped with. Most teams that struggle with localization are not short of translators. They are short of a repeatable handoff between engineering and everyone else.

This guide walks through that workflow step by step, with a checklist you can paste into your own repo and a plain look at the trade-offs for small teams.

Arkian
arkian.ai
Simplify Your Localization Handoff
Arkian automates multilingual scripts, voice outputs, validation, and packaging for small teams without complex translation management systems.
Explore Arkian

TL;DR

  • Externalize every user-facing string early and review i18n problems in code review, not after launch.
  • Treat the handoff as a contract: stable keys, source text, context notes, placeholders and length limits.
  • Validate returned files automatically (placeholders, plural forms, missing keys) before anything is merged.
  • Package output per platform (JSON, iOS strings, Android XML, YAML, audio) and version it against your build.
  • Small teams can skip a full translation management system if the workflow is automated end to end.

Table of Contents

What a developer localization workflow actually covers

Localization has two halves. Internationalization (i18n) is the engineering work that makes software able to support more than one language. Localization (l10n) is adapting the product to a specific language and region. As one set of open best practices puts it, localization means adapting software, games, multimedia and websites for a new language.

A workflow is the path text takes between those halves. Most guides split it into stages like extraction, translation, review, merging translated files back into the code structure, and release. That order holds whether you ship a mobile app, a web product or a game. What differs is how much of it you do by hand.

Five stages in a developer localization workflow

The seven steps below are the ones we see decide whether a small team ships on time.

Step 1: Internationalize before you translate

The costliest mistake is retrofitting. The same best-practices document recommends starting localization in the earliest stages of development, and adding i18n checks to code review: key naming conventions, missing keys, and whether each string has enough context.

In practice, that means a short list your reviewers apply to every pull request that touches UI:

  • No user-facing text is hardcoded in a view, template or controller.
  • No sentence is built by concatenating fragments. Word order differs between languages, so a sentence has to be one string with placeholders.
  • Dates, numbers and currencies use platform formatters, not manual formatting. Our field guide to number and date localization covers the common failures.
  • Layouts can grow. Android’s own localization checklist lists “design for localization” as its second step, right after choosing target languages.

If you also run a multilingual website, the same early-stage thinking applies to search markup. Teams that care about this often start by automating hreflang in CI/CD so language alternates are regenerated whenever pages change, rather than patched by hand.

Step 2: Choose a string format and stay with it

Pick one source-of-truth format per platform and do not mix conventions inside it. Typical choices:

Platform Common format Notes
iOS / macOS .strings, .stringsdict, XLIFF XLIFF is handy for exchange with translators
Android strings.xml Plurals use <plurals> resources
Web / React Native JSON Often nested; keep key depth shallow
Rails, some backends YAML Watch indentation and quoting
Voice / audio MP3 or WAV One file per string ID keeps mapping simple

The format matters less than the discipline. Keys should be stable, descriptive and never reused for a different meaning. Rename a key and you orphan every translation attached to it. If you work in Apple’s toolchain, our XLIFF workflow breakdown explains the four stages and the Xcode snags that tend to appear.

Step 3: Make the handoff a contract

The query developers often type here is “developer handoff for localization.” The honest answer is that a handoff fails when the translator has to guess. A string called save could be a verb on a button or a noun in a menu. Without context, you get the wrong one in German and a bug report in week two.

Every string you hand over should carry:

  1. A stable key. Never a position or auto-generated hash that changes between builds.
  2. The source text, approved. Do not send copy that product or marketing may still change.
  3. A context note. Where it appears, what it does, who sees it.
  4. Placeholder documentation. What {count} or %1$s holds, and its type.
  5. Length limits. Button labels and notifications have hard constraints.
  6. A glossary. Product names, terms that stay in English, and preferred terms. We walk through building a localization glossary in five steps.
  7. Target locales. Be specific. Spanish for Spain and Spanish for Mexico are different deliverables.

The SAP guidelines for multilingual development make a related point: set up a framework for good-quality texts right at the start of a project, and involve the people who will work with the text while you are still planning.

Step 4: Handle plurals and variables with ICU MessageFormat

English has two plural forms, so developers often write a quick check for “one” versus everything else. Other languages have more categories, and that logic produces broken sentences. GainHQ’s guide recommends ICU MessageFormat for pluralization and variable substitution because it handles grammar that English-only logic misses.

A minimal example of an ICU plural:

{count, plural, one {# file} other {# files}}

Translators then add the categories their language needs (for instance few or many in Slavic languages) without touching your code. We cover three ICU checks to run before shipping in a separate piece, including what to test when a translator changes the structure.

Step 5: Validate everything that comes back

This is the step most small teams skip, and it is where bugs enter. Translated files are code-adjacent: a missing brace or a deleted placeholder can crash a screen. GainHQ notes that returned translations should be validated before merging, with automated checks catching broken placeholders, and failures sent back for fixing.

An open-source example of the pattern is a translations auto-validate GitHub Actions workflow, built so translation-only pull requests from community contributors can merge without waiting on a maintainer release cycle. Whatever tooling you use, the rules worth automating are:

  • Key parity: every locale has exactly the keys the source has, no more and no fewer.
  • Placeholder parity: the same placeholders appear in source and translation.
  • Plural completeness: each locale defines the categories its language needs.
  • Syntax validity: JSON parses, XML is well formed, YAML loads, .strings entries end with semicolons.
  • Length checks: flag strings far longer than the source.
  • Encoding: UTF-8 everywhere, no mangled characters.

The Microsoft internationalization checklist is a useful companion for the broader list of areas to verify, from operating system support to locale-sensitive behavior.

Step 6: Package per platform and version it

Validated strings still need to land where your build expects them. That means correct folder names (values-fr on Android, fr.lproj on iOS), correct file names, and a predictable structure. A messy output folder is how the German file ends up in the Portuguese bundle.

Two habits pay off quickly:

  • Fixed folder layout. Decide it once and generate it every time. See how we think about a multilingual output folder structure.
  • Versioning tied to builds. Record which translation set shipped with which commit. Our post on matching translation files to a Git SHA shows how, and it makes “which version had that typo?” answerable in seconds.

If your app uses resource bundles, preventing locale breaks in resource bundles is the next thing to read.

Step 7: Test, release and loop back

Before release, run the localized build, not only the files. Android’s checklist puts testing the localized app as its own step, and the practical items are consistent across platforms:

  • Switch device language and walk the main flows.
  • Look for truncation, overlap and clipped buttons.
  • Check right-to-left layouts if you support Arabic or Hebrew.
  • Verify formatted dates, numbers and currency per locale.
  • Confirm store listings and metadata exist for each language. Our guide to app store localization without manual file work covers that last mile.

Then close the loop. When a reviewer finds an error, fix it in the source of truth and the glossary, not only in the shipped file, or it returns next release.

A reusable developer localization checklist

Copy this into a pull request template or a release issue.

Before development

  • [ ] Target locales decided, with regional variants named
  • [ ] String format chosen per platform
  • [ ] Glossary started

In code review

  • [ ] No hardcoded user-facing text
  • [ ] No concatenated sentences
  • [ ] Plurals use ICU or the platform’s plural resources
  • [ ] Dates, numbers, currencies use system formatters
  • [ ] New keys have context notes

At handoff

  • [ ] Source copy approved and frozen
  • [ ] Keys stable, placeholders documented, length limits stated
  • [ ] Screenshots or descriptions attached for ambiguous strings

On return

  • [ ] Key and placeholder parity pass
  • [ ] Plural categories complete
  • [ ] Files parse in their target format
  • [ ] Spot review by a native speaker for high-visibility screens

At release

  • [ ] Files in correct folders for each platform
  • [ ] Translation set tagged to the build
  • [ ] Localized build tested on device
  • [ ] Store metadata and any audio assets delivered

Do you need a translation management system?

A full translation management system earns its place on large products with many contributors, long-lived branches and dedicated localization managers. For a team of two to ten, it can add repository integrations, seat management and a learning curve that cost more hours than the localization itself.

The alternative is a lighter, production-style workflow: you supply approved source content, and a service returns validated, packaged files that you review and drop in. You keep control of your repo, and nobody needs access to it. Our localization plan for small teams lays out how to decide, and our cost breakdown for app localization shows where developer hours typically go.

Our perspective: the handoff is the product

We build Arkian for small teams, and the pattern we see is consistent: the translation itself is rarely the slow part. The slow part is everything around it. Exporting strings, formatting them for a translator, fixing broken placeholders on return, renaming folders, converting formats, and producing voice files that match the text.

Our perspective: the handoff is the product — overview diagram

So we designed Arkian around production, not management. You give us approved source content. We produce multilingual strings, scripts, voice output and metadata, validate them, and package them into reviewable, delivery-ready files. There is no repository access to grant and no TMS to configure.

We also believe validation belongs inside the workflow, not after it. A package that has not been checked for placeholders and structure is a draft, not a deliverable. Our work with the Quiet Harbour app is the example we point to: a coherent localized product experience across several languages, built from the same approved source. You can read the details in the Quiet Harbour case study.

— Arkian

Where Arkian fits in this workflow

Arkian covers steps 3 to 6 for teams that would rather not run them by hand. Localization strings handles app text for iOS .strings, Android XML and JSON language files. Multilingual voice production produces matching MP3 or WAV audio, and structured packaging delivers it all in a consistent layout.

Plans are 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).

Common mistakes that break the workflow

  • Sending unfinished copy. Every late wording change multiplies across all languages.
  • Treating translators as the validator. They translate; your pipeline validates.
  • Reusing keys. One key, one meaning, forever.
  • Skipping locale variants. Decide on regional versions before the handoff.
  • Forgetting non-text assets. Voice prompts, store metadata and screenshots need the same discipline as UI strings.
  • No version link. Without a build-to-translation record, regressions are hard to trace.

FAQ

What is the first step in a developer localization workflow?

Externalizing strings and fixing i18n problems in code review. Doing it at the start of development avoids the expensive retrofit of an app with hardcoded text. Choosing target locales comes with it, because that decides formats and layout needs.

What should a developer include in a localization handoff?

Stable keys, approved source text, context notes, placeholder descriptions, length limits, a glossary and the exact target locales. The goal is that a translator never has to guess what a string does or where it appears.

How do I validate translation files automatically?

Run checks in CI or in your packaging step: key parity with the source, matching placeholders, complete plural categories and valid file syntax. Fail the build, or send the file back, when any check fails. Open-source GitHub Actions workflows for translation validation are a good starting point.

Do small teams need a translation management system?

Not necessarily. If your volume is modest and you can supply approved source content, an automated production workflow that returns validated, packaged files is often enough. A TMS makes more sense once many contributors and branches need coordinating.

Sources