Localization Files: What Translators Receive, Parse, and Return
Localization files are externalized resource files — JSON, XLIFF, PO, strings.xml, .resx — that carry source segments, keys, placeholders, and plural rules
Localization files are the production artifact that moves between the developer's repo and the translator's CAT tool — the signed contract that decides whether a locale cycle ends in a clean merge or a round of engineering tickets. This page frames the file from the translator's acceptance desk: the six fields to inspect, the formats on the delivery queue, the placeholder families to preserve byte-for-byte, and the five ways a dirty file breaks the build. The localization file is the deliverable of an How App Localization Works and What Clients Are Buying engagement — and the resource contract behind every Localization Coding: How Translators and Developers Share the Resource File workflow.
What is a localization file, and what does it contain?
A localization file is an externalized resource file that carries source strings, unique keys, placeholders, plural categories, and BCP 47 locale metadata, which translators edit in a CAT tool and return as a locale-stamped copy the developer merges back into the repo. It is a key-value structure, not a document. The key is stable across locales; the value is the translatable segment. Placeholders and inline tags travel inside the value and must survive the round-trip untouched.
Each localization file carries the following, at minimum:
- Keys — stable identifiers the developer references in code.
- Source segments — the translatable text in the source locale.
- Target slots — empty or pre-populated fields for the target locale.
- Placeholders — ICU, double-curly, or printf-style tokens that inject runtime values.
- Plural categories — CLDR-aligned variants (zero, one, two, few, many, other).
- BCP 47 locale tag — the ISO 639-1 language plus optional ISO 3166-1 country code (es-MX, pt-BR, fr-CA).
- Context fields — comments, notes, or screenshots that disambiguate the segment.
Which six fields does every localization file carry?
Every localization file carries six fields a translator inspects before accepting the job: the key, the source segment, the target segment slot, the placeholder family, the plural category set, and the BCP 47 locale tag — plus an optional comment field that supplies context. Each field maps to one acceptance check. A failure on any field is an engineering ticket back to the developer, not a translation workaround.
| Field | What the translator verifies | Failure signal |
|---|---|---|
| Key | Unique, stable, matches across source and target files | Duplicate or renamed keys |
| Source segment | Final copy, no hard-coded fragments | Draft placeholders in source |
| Target slot | Empty or seeded with TM match | Pre-filled with machine output and no post-edit flag |
| Placeholder family | ICU, double-curly, or printf — one family per file | Mixed families inside one file |
| Plural categories | CLDR categories declared for the target locale | Only "one" and "other" when target needs "few" and "many" |
| BCP 47 locale tag | Filename or metadata matches target (es-MX, not es) | Generic tag where regional variant is required |
How does a localization file differ from a translation memory or term base?
A localization file is the live production artifact for one locale cycle, a translation memory is the cumulative segment store that leverages across cycles, and a term base is the controlled glossary enforced inside both. Three different objects, three different lifecycles. The file is per-release; the TM grows forever; the term base is curated and audited.
- Localization file — per-release deliverable, one per locale, merged into the build.
- Translation memory — cumulative segment store, leverages full and fuzzy matches across every past cycle.
- Term base — controlled glossary, enforces approved target terms during CAT editing.
What are the common localization file formats translators actually receive?
The common localization file formats translators receive are JSON (flat, nested, ICU), XLIFF 1.2 and 2.1, gettext PO, Android strings.xml, iOS .strings and .stringsdict, .NET .resx, YAML, and ARB — each mapped to a stack and each forcing different placeholder and plural conventions. Major TMS platforms list 50+ supported formats, but these nine carry the volume. Custom or nested JSON is the most common filter-failure point in practice.
Which format maps to which stack, and what does the translator preserve?
Each format maps to a predictable stack and locks a specific preservation contract: JSON for React/Vue/Next.js preserves ICU braces, XLIFF 2.1 for TMS bilinguals preserves inline tag IDs, gettext PO for WordPress and Django preserves msgid_plural counts, strings.xml for Android preserves apostrophe escapes, and .resx for .NET preserves name/value XML parity.
| Format | Primary stack | Preservation contract |
|---|---|---|
| JSON (flat / nested / ICU) | React, Vue, Next.js, i18next | ICU braces, nested key paths, escaped quotes |
| XLIFF 1.2 / 2.1 | TMS interchange across any CAT tool | Inline tag IDs, trans-unit id attributes, segment state |
| gettext PO | WordPress, Drupal, Django, GNU toolchain | msgid / msgstr pairs, msgid_plural count, Plural-Forms header |
| Android strings.xml | Android native | <plurals> / <item quantity> tags, apostrophe escape (\') |
| iOS .strings / .stringsdict | iOS, macOS native | UTF-16 encoding, .stringsdict plist plural structure |
| .resx | .NET, WinForms, ASP.NET | name/value XML parity, UTF-8 encoding, comment attributes |
| YAML | Rails, Jekyll, static sites | Indentation, anchor references |
| ARB | Flutter | ICU MessageFormat, @metadata keys |
Why is XLIFF the dominant interchange format on multi-tool projects?
XLIFF (XML Localization Interchange File Format) is dominant on multi-tool projects because it is an OASIS standard XML-based format designed specifically to round-trip source and target segments plus metadata between any CAT tool and any TMS without data loss. One translator can open an XLIFF 2.1 bilingual in Trados Studio, another in memoQ, a third in Phrase — the segment IDs, inline tags, and state attributes survive every hop. Native formats like JSON or PO force vendor-specific filter rules; XLIFF normalizes the interchange.
What does a JSON localization file look like in practice?
A JSON localization file in practice is a key-value tree where keys are stable identifiers and values are source strings with ICU or double-curly placeholders — flat for simple apps, nested or i18next-shaped for React, and ICU MessageFormat-wrapped when plurals and selects are needed. React-shaped nested JSON and i18next conventions are detailed on React i18n: How Translators Fit Into a React Localization Pipeline.
A minimal pair:
- en.json —
{"welcome": "Hello, {name}", "cart": {"items": "{count, plural, one {# item} other {# items}}"}} - es-MX.json —
{"welcome": "Hola, {name}", "cart": {"items": "{count, plural, one {# artículo} other {# artículos}}"}}
The key path cart.items is identical across both files. The ICU block structure is identical. Only the human-readable text is translated.
How does a translator inspect a localization file before accepting the job?
A translator inspects a localization file against a six-field acceptance checklist before accepting the job: key integrity, placeholder family, plural categories, inline-tag parity, UTF-8 encoding, and BCP 47 tag match — any failure triggers an engineering ticket back to the developer, not a translation workaround. The inspection runs before quoting, because defects at these six boundaries determine review and LQA cost, not word count.
- Key integrity — open source and target files side by side, confirm identical key sets, no renames mid-cycle.
- Placeholder family — scan every value for ICU, double-curly, or printf tokens, confirm one family per file.
- Plural categories — verify CLDR category coverage matches the target locale (Arabic needs six, English needs two).
- Inline-tag parity — in XLIFF, confirm every source tag ID appears in the target slot or is correctly empty.
- Encoding — verify UTF-8 for JSON, PO, YAML, strings.xml, .resx; UTF-16 for iOS .strings; check BOM presence rules.
- BCP 47 locale tag — confirm filename and metadata carry the full tag (pt-BR, not pt) when regional variant is required.
What signals that a localization file passed a pseudo-localization gate?
A localization file that passed a pseudo-localization gate arrives with strings already inflated 30–50% to expose truncation, ASCII characters swapped for accented equivalents, hard-coded text surfaced in the UI, and encoding verified as UTF-8 — covered in depth on Pseudo Localization: What Translators Need to Know About i18n Test Builds. A build that skipped this gate pushes hard-coded strings, truncation bugs, and encoding regressions into the translator's queue, where none of them are translation defects.
The three placeholder families a translator preserves byte-for-byte are single-curly ICU like {name} and {count, plural, one {#} other {#}}, double-curly Handlebars/Mustache like {{name}}, and printf-style like %s or %{name} — each one breaks the build if altered, reordered, or translated. The enumeration appears in full on JS Localization: How Translators Fit Into a JavaScript i18n Pipeline.
| Family | Syntax example | Common stacks |
|---|---|---|
| ICU single-curly | {name}, {count, plural, one {#} other {#}} | JSON, XLIFF, ARB, Flutter |
| Handlebars / Mustache double-curly | {{name}}, {{count}} | i18next, Vue, Ember templates |
| printf-style | %s, %d, %1$s, %{name} | gettext PO, strings.xml, iOS .strings, Ruby |
What does the plural-rule contract look like across formats?
The plural-rule contract follows CLDR categories — zero, one, two, few, many, other — expressed as ICU MessageFormat blocks in JSON and XLIFF, msgid_plural with Plural-Forms headers in PO, and <plurals>/<item quantity> tags in Android strings.xml and iOS .stringsdict. English needs two categories, Arabic needs six, Russian needs four. The translator fills every category the target locale requires.
- ICU MessageFormat (JSON, XLIFF, ARB) —
{count, plural, one {# item} other {# items}} - gettext PO — msgid / msgid_plural / msgstr[0] / msgstr[1] with the file's Plural-Forms header defining n-rules.
- Android strings.xml —
<plurals name="items"><item quantity="one">...</item><item quantity="other">...</item></plurals> - iOS .stringsdict — plist dictionary with NSStringLocalizedFormatKey and per-category strings.
How does a dirty localization file break the round-trip to the developer's build?
A dirty localization file breaks the round-trip in five specific ways: escaped-quote corruption in JSON, inline tag ID drift in XLIFF, msgid_plural count mismatch in PO, apostrophe escaping in Android strings.xml, and encoding regression (UTF-8 to Windows-1252) in .resx — each one surfaces at merge, not at translation. The translator's output passes CAT QA. The developer's build fails on parse or render. Understanding why these defects slip through requires knowing how each format is parsed and what the build toolchain expects at ingestion time.
String extraction is the first point of structural risk. In most programming environments, the developer marks displayable strings by hand before they ever reach the translator — meaning the externalized file inherits whatever inconsistencies existed in the original markup. XLIFF compounds this because it is a format defined by an ISO standard and carries not just source and target text but also per-segment annotations such as Do Not Translate markers; when a CAT tool strips or renumbers inline tag IDs during export, those annotations break silently and the TMS merge rejects the segment as structurally corrupt. The defect is invisible to the translator and lethal to the build.
| Format | Round-trip failure | Where it surfaces |
|---|---|---|
| JSON | Unescaped or double-escaped quotes inside values | JSON parser throws at build |
| XLIFF | Inline tag IDs renumbered or dropped in target | TMS merge rejects segments as corrupt |
| gettext PO | msgid_plural count does not match Plural-Forms header | msgfmt compile fails |
| Android strings.xml | Apostrophes not escaped as \' or wrapped in quotes | Resource compile fails or renders truncated |
| .resx | Encoding saved as Windows-1252 instead of UTF-8 | Accented characters render as mojibake at runtime |
Each failure mode is deterministic: the same structural violation produces the same build error every time. That predictability is what makes pre-delivery QA automation valuable — a script that validates JSON syntax, checks XLIFF inline tag parity, counts PO plural forms against the Plural-Forms header, and asserts UTF-8 encoding on .resx files catches all five defect classes before the file leaves the translator's desk. Without that gate, defects travel downstream and are discovered at the most expensive point in the pipeline.
What do these defects cost at the review and LQA gates?
File-level defects compound at the two quality gates: review at $0.04–$0.08 per source word checks every segment and absorbs placeholder fixes, and LQA at $40–$90 per 1,000 words samples output against an MQM-style scorecard aligned to ISO 17100 — defects clustered at placeholder and plural boundaries drag both scores. A dirty file inflates review hours because defects cluster where structure meets text, not in the prose itself. Structural errors — a broken placeholder, a mismatched plural category, a corrupt inline tag — register as accuracy failures on an MQM scorecard even though they are engineering defects rather than linguistic ones, which means they penalize the translation quality score and trigger rework cycles that consume both review and LQA budget simultaneously.
- Review gate — $0.04–$0.08 per source word, segment-by-segment, catches placeholder breaks before merge.
- LQA gate — $40–$90 per 1,000 words, samples against an MQM-style scorecard, flags accuracy and formatting error categories.
- Economic linkage — a file that fails pseudo-loc or arrives without a placeholder-family declaration pushes defect density up where both gates charge most.
Pseudo-localization is the upstream gate that prevents the majority of structural defects from ever reaching the translator. It inflates source strings by 30–50% and substitutes ASCII characters with accented equivalents, exposing UI truncation and placeholder parsing failures in the developer's build before translation begins. A localization file that passes pseudo-loc in a staging environment is structurally sound; one that skips this gate carries latent defects that the translator cannot see and the CAT tool will not catch.
Which CAT tools open each format cleanly, and where do filters fail?
CAT tools open the core localization formats through format-specific filters, and each filter carries its own failure boundary. XLIFF is the interchange format most tools handle reliably because it is a standardized, well-specified XML schema — the same standardization that makes XLIFF the safest choice for TMS round-trips. Custom-nested JSON is the top filter failure point across the ecosystem: when a developer's key structure differs from the parser's assumptions — arrays inside objects, keys at irregular nesting depths, mixed placeholder families in a single file — the filter either silently drops segments or exposes raw syntax to the translator as translatable text. Both outcomes corrupt the target file. Platform-specific customizations inside XLIFF variants add a second layer of filter risk, because tools that handle the base schema correctly may still misparse extensions added by a particular framework or TMS export.
| CAT tool | Strong on | Common filter failure |
|---|---|---|
| Trados Studio | XLIFF 1.2/2.1, nested JSON, .resx | Deeply nested JSON with array values |
| memoQ | XLIFF, JSON, YAML, ARB | Custom key paths requiring regex filters |
| Phrase | JSON, XLIFF, strings.xml, .stringsdict | Mixed placeholder families in one file |
| Poedit | PO / POT (native) | Non-standard Plural-Forms headers |
| OmegaT | YAML, Markdown, HTML | XLIFF 2.1 inline tag rendering |
| Smartcat | JSON, XLIFF, ARB | Custom-nested JSON with developer-specific key shapes |
The practical mitigation is a filter configuration checklist agreed upon at project kickoff: the PM specifies the exact JSON key depth, the placeholder syntax family (ICU, printf, or custom), and the target encoding before the translator opens the file. A filter misconfiguration discovered mid-translation requires reprocessing every segment the tool has already handled — a cost that falls entirely on the agency and is entirely avoidable.
How do localization files move between the repo, the TMS, and the translator?
Localization files move repo-to-TMS via a connector that syncs on commit, keyed by BCP 47 locale tag: the developer externalizes strings into the source file, CI pushes it to the TMS, the translator opens segments in the CAT tool, and the locale-stamped copy returns through the same connector for merge. The repo stays source of truth for keys and source strings; the TMS is system of record for translations. This handoff is not a one-time event — it is a continuous loop that repeats with every sprint, release branch, or content update, which means the connector configuration and the file naming convention must be stable across the full product lifecycle.
The localization file itself is the artifact that makes this exchange possible: it is an externalized resource carrying source strings, keys, placeholders, plural categories, and BCP 47 locale metadata in a form that both the developer's build toolchain and the translator's CAT tool can parse without manual transformation. That dual parsability is the design contract the file must satisfy at every point in the pipeline. When the file format is XLIFF, it additionally carries standardized interchange metadata — source and target segment pairs, translation state flags, and per-segment annotations — that allow any conforming CAT tool or TMS to round-trip the content without loss. XLIFF files also exist in platform-specific variants that extend the base schema, so the connector must be configured to handle the exact variant the framework emits.
Translation memory travels alongside the file but is distinct from it. TM data is exchanged between tools in its own interchange format, and the cumulative segment store it represents is built up across every locale cycle the project has run. The TMS applies TM leverage automatically when new source segments arrive, pre-populating matches before the translator sees the file — which means the file the translator opens may already contain confirmed full matches, fuzzy matches, and untranslated new segments, each with a different handling cost. The term base is a second companion artifact: it is a controlled glossary the CAT tool enforces in real time during segment editing, flagging deviations from approved terminology before the translator moves to the next segment.
What does the resource bundle delivered at project kickoff contain?
The resource bundle delivered at project kickoff is the complete set of artifacts the translator needs to work the file correctly without back-and-forth. It lists segment count, placeholder density, character limits per key, and context fields across formats such as XLIFF, JSON, .strings, and strings.xml — and it includes the TM, the term base, the style guide, and access to a pseudo-localized or staging build where the translator can verify that rendered output matches the character-limit constraints in the file. Each artifact in the bundle addresses a different failure mode: the TM prevents redundant translation of repeated strings, the term base prevents terminology drift, the style guide governs register and punctuation conventions, and the staging build surfaces UI truncation before delivery.
Segment count and placeholder density together determine the project's structural complexity. A file with high placeholder density — many ICU MessageFormat expressions, printf tokens, or custom variable patterns — requires more translator attention per segment than a file of equivalent word count with plain prose, because every placeholder is a preservation obligation that CAT QA must verify. Character limits per key are equally load-bearing: a key that allows 40 characters for a button label constrains the translator's lexical choices in every target language, and a resource bundle that omits these limits forces the translator to guess — which produces truncation defects that surface only in the rendered UI.
How do agencies move string files out of the repo at scale?
Agencies move string files out of the repo at scale through a managed TMS connector that treats the repo as source of truth and the TMS as system of record for translations. The connector detects new or changed source segments on commit, pushes them for translation, and writes locale-stamped files back for merge — without requiring the developer to manually export, email, or re-import any file. At scale, this automation is not optional: a program running ten or more locale pairs across monthly release cycles generates hundreds of file transactions per quarter, and manual handoffs at that volume introduce version mismatch, duplicate work, and merge conflicts that compound with every release.
The BCP 47 locale tag is the key that makes automated routing work. Every file in the repo carries a locale tag — a language code combined with an optional country code such as es-MX, pt-BR, or fr-CA — and the connector uses that tag to route each file to the correct target-language workflow in the TMS, apply the correct TM and term base, and write the translated output back to the correct locale directory in the repo. A malformed or inconsistent locale tag breaks routing silently: the file may be processed against the wrong TM, delivered to the wrong translator queue, or written back to the wrong directory, producing a build that compiles but serves the wrong locale to end users.
The questions translators and PMs ask most about localization files cluster around format choice, placeholder handling, plural rules, encoding, and the difference between a localization file and a translation memory — concise answers follow.
Frequently asked questions
What is a localization file?
A localization file is a structured text file that stores translatable strings, labels, and content separately from an application's source code so translators can work on them without touching the codebase. Common formats include JSON, XLIFF, PO/POT, YAML, .strings, and .resx files. Each file pairs a key (a stable identifier like "btn.submit") with a value (the human-readable text to be translated). For translators producing certified translations, localization files are the deliverable — they receive them, translate the values, and return the completed files to the developer or agency.
what are localization files
Localization files are the containers that hold all translatable text for a software product, app, or digital service, organized so translators can work on them efficiently. They come in dozens of formats — XLIFF, JSON, PO, YAML, .strings, .resx, ARB — each with its own syntax but the same core logic: key-value pairs where the key is untouched and the value is translated. For professional translators and agencies, these files are a primary work format, often processed in CAT tools like memoQ, SDL Trados, or Phrase before being returned to the client.
what is localization files
Localization files are structured documents containing the translatable text strings of a software application or digital product, separated from the code so they can be translated independently. Each string is identified by a unique key, allowing developers to swap language versions without rewriting logic. Formats range from XLIFF and PO (widely supported by CAT tools) to proprietary JSON or YAML schemas. Translators receive these files, populate the target-language values, and return them — making localization files the core unit of work in software translation workflows.
What does localization mean?
Localization (often abbreviated L10N) means adapting a product, document, or piece of software so it feels native to a specific target market — covering language, date and number formats, currency, images, and cultural references. It goes beyond translation by addressing locale-specific conventions: for example, converting MM/DD/YYYY to DD/MM/YYYY for European markets, or replacing idioms that don't carry across cultures. In a certified translation context, localization also means ensuring that adapted content still meets the accuracy and completeness standards required for legal or official acceptance.
how does localization work
Localization works by extracting all user-facing text from a product into localization files, sending those files to translators, and then reinserting the translated strings back into the product for each target locale. The process typically follows this sequence: developers export source-language files (e.g., XLIFF or JSON), translators work on them using CAT tools or TMS platforms, translated files are reviewed and returned, then engineers reintegrate them and run QA checks. For certified translation projects, an additional review or notarization step may be required before the translated files are accepted as official.
How do I translate an entire file?
To translate an entire localization file professionally, import it into a CAT tool (such as memoQ, SDL Trados, or Phrase) that can parse the file format and present each string in a translation editor while protecting tags and keys from accidental modification. The tool applies translation memories and terminology databases to pre-populate matches, which translators then review, correct, and confirm. Once all segments are translated, the tool exports the file in its original format. For certified translations, the returned file must also be accompanied by a signed statement of accuracy from a qualified translator.
What are the five types of translation?
The five most commonly recognized types of translation are literary, technical, legal, medical, and localization/software translation. Literary translation handles creative works and prioritizes style and voice; technical translation covers manuals, engineering documents, and specifications; legal translation deals with contracts, statutes, and certified documents; medical translation covers clinical trials, labels, and patient materials under strict regulatory standards; and software/localization translation adapts UI strings, help content, and app copy for specific markets. Certified translation can overlap with legal, medical, and technical categories, each requiring the translator to attest to accuracy.
Related
- 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
- Localization Solution: What Translators and Agencies Assemble to Run Multi-Lane Work
- Localization Workflow: How Translators and Agencies Wire the Production Pipeline