Localization Coding: How Translators and Developers Share the Resource File
Localization coding externalizes UI strings into resource files, uses format placeholders over concatenation, and routes ICU plurals, BCP 47 locales, and
Localization coding sits inside a broader app localization pipeline — the engineering substrate that lets translators deliver clean resource files into a developer's build without touching source code. For the pipeline framing, see Application Localization: The Translator's and Agency's Guide. This page covers the substrate itself: resource files, placeholders, ICU plurals, BCP 47 tags, and the certified lane that reuses the same files.
What is localization coding, and why does it decide whether translators can deliver clean files?
Localization coding is the engineering practice of externalizing UI text into resource files, parameterizing variables with placeholders, declaring plural and locale rules, and tagging locales with BCP 47 identifiers so translators produce locale builds without touching source code. It is the shared contract between the developer who structures the file and the translator who fills it — and when that contract is broken on the engineering side, no amount of linguistic skill at the translator's desk can produce a clean build. The practice decides handoff quality because every rework cycle traces back to one of six root causes.
- Hardcoded strings never reach the resource file and are invisible to the TMS.
- Concatenated sentences force English word order on inflected languages such as German, Japanese, and Arabic.
- Missing plural declarations collapse three to six grammatically required forms into one.
- Free-text locale names break TMS routing that depends on BCP 47 tags.
- Placeholder drift between source and target files breaks the build at compile time.
- No screenshots or pseudo-localization leaves translators guessing at character limits and UI context.
Pseudo-localization is a test build that expands and accents source strings to surface truncation, hardcoded strings, and encoding bugs before a single segment reaches a human translator. Running it early is the single highest-leverage quality gate in the pipeline, because defects caught there cost a fraction of what they cost when they surface at the LQA stage. The LQA gate prices at $40–$90 per 1,000 words translated and runs an MQM-style scorecard aligned to ISO 17100. Catching a hardcoded string at that stage costs roughly ten times what catching it at pseudo-loc costs — making localization coding decisions directly responsible for program economics, not just technical correctness.
How does localization coding differ from internationalization (i18n), and where does each stop?
Internationalization is the upfront engineering that makes a codebase locale-ready — externalized strings, Unicode encoding, locale-aware formatting APIs, and bidirectional layout support — while localization coding is the per-locale execution that fills those resource files with translated strings, plural rules, and BCP 47 tags. Internationalization is the critical engineering practice of preparing a software application so that it can be adapted to various languages and regions without requiring code changes at the time of each new locale launch. The i18n layer ships once. The l10n layer ships every time a new locale lands, and it operates entirely within the structure the i18n layer created.
| Dimension | Internationalization (i18n) | Localization (l10n) |
|---|---|---|
| Scope | Upfront engineering | Per-locale execution |
| Owner | Developer | Translator + localization engineer |
| Artifacts | Externalized strings, Unicode encoding, locale-aware APIs, bidirectional support | Translated strings, plural rules, date/number formats, locale-specific legal copy |
| Shipped | Once | Every new locale |
| Failure mode | Hardcoded strings, broken encoding, layout that clips RTL text | Wrong plural form, mis-routed BCP 47 tag, placeholder mismatch |
Key i18n practices include externalizing all user-facing strings from the codebase, using a library that supports pluralization and locale-specific formatting for dates and numbers, and designing user interfaces that can accommodate text expansion and right-to-left languages. Each of those practices creates a specific hook that the l10n layer depends on: the externalized string file is where translators work, the pluralization library is what reads their plural-branch entries, and the RTL-capable UI is what renders their Arabic or Hebrew output without clipping.
For the program-planning view that sits above both layers, see Localisation Strategy: How Agencies Plan, Price, and Deliver Multi-Locale Programs.
What does the handoff from i18n to l10n look like in a real repository?
The developer externalizes every user-facing string into resource files — en.json, strings.xml, Messages.resx — wires ICU MessageFormat or gettext for plurals, and commits a locale-neutral build. A Translation Memory stores all previously translated source-and-target language pairs, so segments that reappear across locale cycles return at full leverage rather than being re-translated from scratch. The translator then receives the resource files via TMS or Git and returns locale-stamped copies keyed to the correct BCP 47 tag.
- Developer extracts strings into the source resource file.
- CI pipeline pushes the file to the TMS, keyed by BCP 47 locale tag.
- Translator opens segments in the CAT tool, with TM and term base pre-loaded.
- Reviewer passes at $0.04–$0.08 per source word, checking every segment pre-LQA.
- LQA scorecard runs at $40–$90 per 1,000 words against an MQM-style framework.
- Signed-off file commits back to the repository as es-MX.json or de-DE.json.
What are the common technical approaches to localization coding across modern stacks?
The three common approaches are resource-file externalization with key-value lookups, inline ICU MessageFormat for complex plural and gender rules, and gettext-style .po files with msgid/msgstr pairs — each paired with a BCP 47 locale tag and loaded at runtime by the i18n library. The approach is set by the stack, not by preference.
Which string resource file format fits which stack?
Translators receive .po on PHP and Python projects, .resx on .NET, strings.xml on Android, .strings on iOS, .json on JavaScript and React, and XLIFF as the interchange format CAT tools consume. Each format carries different placeholder syntax and plural handling.
| Format | Stack | Placeholder syntax | Plural handling | CAT support |
|---|---|---|---|---|
| .po (gettext) | PHP, Python, GNU | %(name)s, %s, %d | nplurals + Plural-Forms header | Native in most CAT tools |
| .resx | .NET | {0}, {1} | External library (e.g., Humanizer) | Via XLIFF export |
| strings.xml | Android | %1$s, %2$d | <plurals> element, CLDR categories | Native in most CAT tools |
| .strings / .stringsdict | iOS | %1$@, %2$d | .stringsdict with NSStringLocalizedFormatKey | Native in most CAT tools |
| .json | JavaScript, React, Node | {name}, {count} | ICU MessageFormat | Via plugins or XLIFF conversion |
| XLIFF (1.2 / 2.0) | Interchange | Preserves source placeholders | Carries ICU or native | Native — the lingua franca |
For JSON stacks specifically, see JS Localization: How Translators Fit Into a JavaScript i18n Pipeline and React i18n: How Translators Fit Into a React Localization Pipeline. React Native programs follow Expo Localization: What Translators and Agencies Need to Know About expo-localization. Static-site stacks using JSON namespaces track with How to Add i18n to an Astro Site.
Why do format placeholders beat string concatenation in every target language?
Format placeholders like %1$s, {name}, or {0} let translators reorder arguments inside a single resource entry, while concatenation forces English word order on languages like German, Japanese, Arabic, and Russian — producing ungrammatical output no reviewer can rescue. Concatenation is the single most common cause of broken grammar in Slavic, Semitic, and East Asian locales.
Consider "You have {count} messages from {name}". A translator working in German needs the verb at the end. A translator working in Japanese reorders subject, object, and verb entirely. A translator working in Arabic flips reading direction and inflects {name} for case. All three fit inside one placeholder-based entry. None of them survive concatenation like "You have " + count + " messages from " + name, because the fragments cannot be reassembled.
- Android/Java:
%1$s,%2$d(positional, so translators reorder). - ICU / react-intl:
{name},{count}(named, so translators reorder by name). - .NET:
{0},{1}(positional index). - Python gettext:
%(name)s(named, dictionary-style).
How do ICU MessageFormat and gettext handle plural rules translators actually see?
ICU MessageFormat exposes CLDR plural categories (zero, one, two, few, many, other) inside a single message; gettext uses nplurals and a Plural-Forms header per .po file — Russian declares 3 forms, Arabic 6, Welsh 6, Japanese 1, and the translator fills each category key.
| Language | Plural forms | CLDR categories used | gettext nplurals |
|---|---|---|---|
| English | 2 | one, other | 2 |
| Russian | 3 | one, few, many | 3 |
| Arabic | 6 | zero, one, two, few, many, other | 6 |
| Welsh | 6 | zero, one, two, few, many, other | 6 |
| Polish | 3 | one, few, many | 3 |
| Japanese | 1 | other | 1 |
| Chinese | 1 | other | 1 |
| French | 2 | one, other | 2 |
CJK languages carrying one plural form are a frequent source of over-engineered keys. For CJK specifics on top of the plural rule, see Chinese Localization: What Makes It Harder Than Most Projects.
How should dynamic strings with variables be structured so translators can keep grammar intact?
Dynamic strings must keep the full sentence in one resource entry with named or positional placeholders — never split across multiple keys — because word order, gender agreement, and clitic placement differ by locale and cannot be reassembled correctly from fragments at runtime. String concatenation is an anti-pattern: it breaks word order in German, Japanese, Arabic, and Russian, and it is structurally impossible to fix at translation time without changing the code. One sentence equals one key — that rule is the foundation of every platform's resource-file convention.
What does a correctly structured ICU message look like for a count-plus-name sentence?
Placeholder syntax varies by platform and must be preserved exactly as received. Android and Java use positional specifiers such as %1$s and %2$d. ICU MessageFormat and React-intl use named tokens such as {name} and {count}. .NET resource files use indexed tokens such as {0} and {1}. Python gettext uses named mapping syntax such as %(name)s. Translators must carry every placeholder through to the target segment without altering its syntax, because the runtime substitution engine matches the token literally.
A single ICU entry such as {count, plural, one {# message from {name}} other {# messages from {name}}} lets translators choose the correct plural form and reposition {name} according to target-language grammar. The equivalent concatenation — count + ' messages from ' + name — breaks the moment the target language inflects the noun or moves the verb. ICU plural categories are drawn from CLDR: the available categories are zero, one, two, few, many, and other. Russian requires three active categories. Arabic requires all six. Welsh also requires six. Japanese requires only one — other — because the language has no grammatical plural distinction. French requires two. Each branch keeps {name} and the # count token intact and reorders them per locale grammar.
How do gender and case agreement get represented in the resource file?
ICU select clauses — {gender, select, female {her message} male {his message} other {their message}} — represent gender agreement inside a single string entry, keeping the logic in the resource file rather than in conditional code. Case agreement in Slavic and Finnic languages requires either declined variants per form or a developer comment on the key specifying the grammatical context so the translator supplies the correctly inflected form.
- Gender: ICU
selectwith female / male / other branches; translator fills each branch independently. - Case: pass the inflected noun as a separate variable, or add a developer comment specifying nominative, genitive, or accusative context.
- Formality: ICU
selectwith formal / informal branches for German Sie/du, French vous/tu, and Japanese keigo registers. - Positional placeholders: keep platform syntax intact —
%1$s,{name},{0}, or%(name)s— and never reorder without confirming the runtime supports reordering.
What we offer
What locale and language codes should the resource files carry?
Resource files are tagged with BCP 47 identifiers that combine an ISO 639-1 two-letter language code with an optional ISO 3166-1 alpha-2 country code — es-MX for Mexican Spanish, fr-FR for metropolitan French, pt-BR for Brazilian Portuguese — and the TMS stores every translated segment against the BCP 47 tag, not a free-text locale name. Storing segments against a structured tag rather than a display name is what allows the TMS to route content correctly, apply the right term base, and surface TM leverage across locale variants that share a root language. A client adding es-AR to an existing es-ES program inherits the shared term base through the BCP 47 language-subtag structure, reducing net-new word volume from the first segment.
Can AI tools like ChatGPT and Copilot write or audit localization code reliably?
AI tools reliably scaffold ICU MessageFormat skeletons, generate boilerplate key structures, and audit placeholder parity between source and target files, but AI-generated translations still require human review before the LQA gate at $40–$90 per 1,000 words. The scaffolding use is sound. The finished-translation use is not.
What should an agency let AI do, and what stays with a human reviewer?
AI handles key-naming conventions, placeholder-parity checks, pseudo-translation stubs, and plural-category skeletons. A human reviewer owns terminology, locale convention, tone, and the certificate-of-accuracy wording on certified lanes — because those decisions are legally or contractually operative.
| Task | AI (ChatGPT, Copilot) | Human reviewer |
|---|---|---|
| ICU MessageFormat skeleton | Yes | Sign-off |
| Key naming conventions | Yes | Sign-off |
| Placeholder parity audit (source vs target) | Yes | Spot-check |
| Pseudo-translation stubs | Yes | Spot-check |
| Plural-category skeleton (CLDR branches) | Yes | Fill content |
| Finished translation | Draft only | Owns |
| Terminology, tone, locale convention | No | Owns |
| Certificate of accuracy wording | No | Owns |
Who runs this inside the agency is the localization engineer. For scope, pay, and reporting line, see Localization Engineer Job: What the Role Does, Pays, and Requires. Senior engineers at major tech firms earn total compensation of $150,000–$200,000.
Pricing
How does the certified translation lane fit the same localization coding substrate?
Certified translation runs as a regulated lane on the same resource-file substrate: locked boilerplate for the certificate of accuracy and named-translator attestation fields sit in domain logic rather than the presentation layer, and USCIS filings price at $0.10–$0.25 per source word or
Certified translation runs as a seventh regulated lane on the same resource-file substrate: locked boilerplate for the certificate of accuracy and named-translator attestation sit in domain logic rather than presentation, and USCIS filings price at $0.10–$0.25 per source word or $25–$150 per standard page with optional notarization at $10–$50. The lane shares term base and style guide with the other six delivery lanes — product app, website, marketing, support KB, legal/compliance, in-product video.
For the full lane framing inside multi-locale programs, see Localization Management: How Translators and Agencies Run Multi-Locale Programs. For how it scopes against enterprise programs, see How Enterprise Localization Programs Are Structured and Run.
Where should localization data live — presentation layer or domain logic?
Display strings and format masks live in the presentation layer. Currency math, tax rules, legal clauses, and certified-document attestation fields live in domain logic — because those values change the result of the computation, not just how it renders, and a mis-rendered attestation can invalidate the certification.
- Presentation layer: UI labels, button text, date format masks, currency symbol, number separators.
- Domain logic: VAT rate, tax jurisdiction rules, currency conversion math, legal clause bodies, certificate of accuracy boilerplate, per-page attestation field.
A currency symbol belongs in presentation. A VAT rate belongs in domain logic. A certified-document attestation field belongs in domain logic, because its wording is legally operative. For the same rule applied to corporate programs, see Business Localization: How Agencies Deliver Multi-Locale Programs for Corporate Clients.
5–
Get a quotePricing
What are the common pitfalls when building a localization system from scratch?
The repeating pitfalls are hardcoded strings, concatenated sentences, missing plural declarations, free-text locale names instead of BCP 47 tags, placeholder drift between source and target files, and no screenshots or pseudo-loc for translator context — each one causes rework the LQA pass surfaces too late. Rework cost compounds. For how to present rework savings to a client, see How to Measure and Present the ROI of Localization Work.
What should the translator receive before any strings are translated?
The pre-handoff bundle contains externalized resource files tagged with BCP 47, an ICU or gettext plural declaration per locale, screenshots or a pseudo-loc build for context, a term base and style guide, and placeholder documentation listing every {variable} and %s token.
- Externalized resource files — no hardcoded strings in source.
- BCP 47 tag on each file (en.json, es-MX.json, fr-FR.json).
- ICU MessageFormat or gettext Plural-Forms declaration per locale.
- Screenshots or a pseudo-loc build — see Pseudo Localization: What Translators Need to Know About i18n Test Builds.
- Term base and style guide shared across all seven delivery lanes.
- Placeholder documentation: every
{variable},%s,%1$s, and{0}listed with its runtime value type. - Developer comments on gender, case, and formality context for ambiguous keys.
Short answers to the questions translators and agency PMs ask when they first open a developer's resource file.
Frequently asked questions
What is localisation in software?
In software, localisation (l10n) is the process of adapting a product's interface, content, and behaviour for a specific locale — covering language, date formats, currency, pluralisation rules, and more. It goes beyond swapping text strings: developers store translatable content in resource files (JSON, XLIFF, .strings, .resx, etc.) that translators fill in for each target language. A well-structured resource file separates code from content, letting translators work without touching the codebase and enabling the app to load the correct strings at runtime.
What is the difference between translation and localization?
Translation converts text from one language to another, while localization adapts the entire user experience for a target market. Translation is one component inside localization: a localized product also adjusts number formats, currency symbols, date order, images, right-to-left layout, pluralisation logic, and cultural references. For translators working with resource files, this distinction matters because some strings carry placeholders, gender agreements, or plural forms that require locale-specific handling beyond word-for-word rendering.
What's the difference between translation and localization?
Translation converts text from one language to another, while localization adapts the entire user experience for a target market. Translation is one component inside localization: a localized product also adjusts number formats, currency symbols, date order, images, right-to-left layout, pluralisation logic, and cultural references. For translators working with resource files, this distinction matters because some strings carry placeholders, gender agreements, or plural forms that require locale-specific handling beyond word-for-word rendering.
Is it localization or localisation?
Both spellings are correct — "localization" follows American English conventions and "localisation" follows British English. The industry uses both interchangeably, and you'll see each in major style guides, tool documentation, and standards bodies such as LISA and W3C. The shorthand "l10n" (the letter L, ten characters, then N) is the universally accepted abbreviation in technical contexts and avoids the spelling debate entirely.
What is an example of localization?
A classic example is an app that displays dates as MM/DD/YYYY in the United States but switches to DD/MM/YYYY for the United Kingdom and YYYY-MM-DD for ISO-standard markets. At the string-resource level, this means the developer stores a date-format pattern as a translatable key, and the translator (or locale configuration) supplies the correct pattern for each region. Other examples include adapting currency symbols, swapping metric and imperial units, adjusting plural forms in Slavic languages, and mirroring UI layout for Arabic or Hebrew.
How do I handle sentence building across different languages in a string resource file?
Use named placeholders and keep full sentences as single string keys rather than concatenating fragments. Splitting a sentence into pieces (e.g., "You have" + count + "messages") forces a fixed word order that breaks in languages where the verb or noun comes first. Instead, store the whole sentence as one key — "You have {count} messages" — and let the ICU MessageFormat or similar standard handle pluralisation and gender agreement per locale. This gives translators full sentence context and the freedom to reorder elements naturally.
What's the best way to structure localization strings to avoid broken grammar in other languages?
Store complete sentences as single resource keys and use a message-formatting standard such as ICU MessageFormat or GNU gettext for plurals, gender, and select cases. Never split sentences across multiple keys or hard-code conjunctions in code — what reads naturally in English often produces ungrammatical output in German, Japanese, or Arabic when reassembled. Add context comments (developer notes) to every key so translators know the UI location, the gender of any referenced noun, and the possible values of each placeholder. Consistent key naming and a glossary of product terms reduce inconsistency across large files.
How do I deal with word order differences when localizing dynamic strings?
Use named, reorderable placeholders rather than positional ones so translators can place variables wherever grammar demands. For example, "{user} sent {count} files" allows a German translator to write "{count} Dateien wurden von {user} gesendet" without touching the code. Positional placeholders like %1$s and %2$s exist in some frameworks for the same reason — they let translators swap order freely. Avoid constructing sentences by concatenating separate strings in code, as this locks word order to the source language structure.
What are common pitfalls when building a localization system from scratch?
The most common pitfalls are string concatenation (forcing source-language word order), missing plural forms, hard-coded punctuation and spacing in code, and neglecting context metadata for translators. Developers often underestimate string expansion: translated text can be 30–100% longer than English, breaking fixed-width UI elements. Other frequent issues include not supporting right-to-left scripts, ignoring locale-specific number and date formats, and treating the source-language file as a living document without a change-tracking workflow — which causes translators to miss updates and ship stale strings.
What does "localization" mean?
Localization means adapting a product, document, or piece of content so it feels native to a specific locale — not just translated, but culturally and technically appropriate. In software, this covers UI strings, date and number formats, currency, images, and legally required terminology. In document translation (including certified translation), localization means ensuring the target text conforms to the conventions, register, and regulatory language of the destination country, not merely rendering words from one language into another.
What is another term for localization?
The most common alternative term is "l10n," the numeronym used in technical documentation. In a broader sense, "adaptation" or "transcreation" are used when cultural rewriting goes beyond linguistic conversion, while "internationalisation" (i18n) refers to the engineering work that makes a product ready for localization. In the certified translation industry, terms like "target-market adaptation" or simply "adaptation" appear when translators must align a document with local legal or regulatory conventions.
What is sl and tl in translation?
SL stands for source language — the language the original document is written in — and TL stands for target language — the language it is being translated into. These abbreviations are standard shorthand across translation studies, CAT tools, and resource file workflows. In a bilingual resource file or XLIFF segment, you will typically see a source element (SL string) paired with a target element (TL string) for each translatable unit, which is exactly the structure translators and developers share when collaborating on localization.
Related
- Localization Engineer Job: What the Role Does, Pays, and Requires
- Localization Files: What Translators Receive, Parse, and Return
- Localization Management: How Translators and Agencies Run Multi-Locale Programs
- Localization QA: How Translators and Agencies Run LQA Before Release
- Localization SEO: How Translators Make Localized Pages Rank
- Localization SaaS: How Translators and Agencies Run Continuous Localization for Software Clients