Answer
i18n Translation: How Translators Produce Localized Builds from JSON, YAML, and XLIFF
i18n translation is the production step where translators convert externalized source strings into locale resource files — JSON, YAML, PO, XLIFF — ready for
i18n translation is one stage of How App Localization Works and What Clients Are Buying — the production step where a translator receives externalized source strings from an internationalized codebase and ships back locale resource files the build system uses without further engineering.
Key points
- i18n translation is the production step that converts externalized source strings into target-locale resource files — JSON, YAML, PO, or XLIFF — while preserving every placeholder and ICU rule exactly as authored. Internationalization itself means developing software adaptable to different languages and regions without requiring code changes; translation is where that adaptability becomes real output.
- Every handoff bundles four input artifacts together: a resource file, a placeholder spec, an ICU plural and gender table, and screenshot or Storybook context for each ambiguous key. Sending fewer than all four forces the translator to guess at meaning, which introduces errors that survive into production builds.
- Translators must protect five placeholder classes verbatim before committing a translated file:
{{name}},{0},%s,<Trans>inline React components, and ICU{count, plural, …}blocks. Altering any of these syntactically breaks the runtime, regardless of whether the surrounding translation is linguistically perfect. - Every certified-lane job passes an LQA gate priced at $40–$90 per 1,000 words, scored against an MQM-style scorecard aligned to ISO 17100. That gate applies whether the draft was produced by a human translator, a CAT tool, or an AI engine.
- A standalone i18n-editor stops scaling at roughly 5,000 translation keys, four or more target locales, or any weekly-commit continuous-localization cadence — at which point a connected Translation Management System with Git and CI/CD hooks becomes necessary.
- CLDR plural categories differ substantially by locale: English uses one and other; French adds many; Russian and Polish require one, few, many, and other; Arabic demands all six — zero, one, two, few, many, and other. Locale codes also carry additional parameters such as date formats, currency symbols, and measurement units that shape how strings must be composed.
What is i18n translation, and how does it differ from 'using an i18n library'?
i18n translation is the production step where a translator converts externalized source strings from an internationalized codebase into target-locale resource files — JSON, YAML, PO, or XLIFF — preserving placeholders, ICU plural rules, and locale formatting without touching application code. It is not the same job as wiring an i18n library into source. The engineering layer is one-off; the translation step repeats every release.
Four artifacts must arrive together or the job is incomplete:
- A resource file in a supported format (JSON, YAML, PO, or XLIFF).
- A placeholder spec documenting
{{name}},{0}, and%ssyntax. - An ICU plural and gender table listing categories per target locale.
- Screenshot or Storybook context for every ambiguous key.
The engineering layer that produces those strings is covered on i18n: What Internationalization Means for Translators Producing Localized Builds. That page defines the scope — string externalization, Unicode, locale-aware formats, ICU plural and gender, RTL layout, fallback chains, and expansion-tolerant UI — so this page stays on the production step.
Disambiguation: i18n vs i18n translation vs l10n
| Term | What it is | When you need it |
|---|---|---|
| i18n (internationalization) | Engineering layer: strings externalized, Unicode, ICU, RTL, fallbacks, expansion-tolerant UI. | Once per codebase, before any locale ships. |
| i18n translation | Linguistic conversion of i18n resource files into a target locale, placeholder- and ICU-safe. | Every release that adds or edits strings. |
| l10n (localization) | Full per-locale adaptation: translation plus currency, date, legal, imagery, and QA. | Per locale, per market launch. |
| i18n-editor | Standalone desktop or web app that opens JSON, YAML, PO, and XLIFF key-by-key. | Small projects under the TMS threshold. |
| TMS | Server platform with TM, reviewer gates, connectors, and LQA sampling. | Above 5,000 keys, four locales, or weekly commits. |
What does the '18' in i18n stand for in translation briefs?
The 18 in i18n is a numeronym for the 18 letters between the first 'i' and the last 'n' in 'internationalization'. Translators meet the term the moment a client ships a resource file instead of a Word document. The same convention produces l10n for localization and a11y for accessibility.
How does i18n translation sit between i18n and l10n in production?
i18n is the one-off engineering layer, l10n is the per-locale cultural adaptation, and i18n translation is the specific linguistic conversion of i18n resource files into each target locale — the handoff artifact between the two.
flowchart TD A[i18n engineering: strings externalized] --> B[i18n translation: JSON/YAML/PO/XLIFF per locale] B --> C[l10n: currency, date, legal, imagery, QA] C --> D[Localized build ships]
What files arrive at a translator's desk for an i18n translation job?
Four artifact classes arrive: a resource file (JSON, YAML, PO, or XLIFF), a placeholder spec documenting {{name}} and {0} syntax, an ICU plural/gender table, and screenshot or Storybook context for every ambiguous key. A handoff missing any one of them produces either guesswork or a broken build.
Which resource-file formats do i18n translators actually open?
Translators open five formats regularly: flat JSON, namespaced JSON, YAML, PO/POT, and XLIFF 1.2 or 2.0 — each with its own placeholder syntax, comment convention, and preferred editor.
| Format | Typical owner | Common failure mode | Editor translators open it in |
|---|---|---|---|
| Flat JSON | Front-end dev shipping a single-file bundle | Key collisions when strings reused across screens | i18n-editor or TMS |
| Namespaced JSON | React / Next.js team using react-i18next | Translator edits one namespace, misses the fallback in another | i18n-editor or TMS |
| YAML | Rails and static-site generators | Indentation errors break the file silently | i18n-editor with YAML lint |
| PO / POT | WordPress, Django, GNU gettext projects | Fuzzy flags left in, plural forms header missing | Poedit, OmegaT, memoQ |
| XLIFF 1.2 / 2.0 | TMS connector export (Phrase, Lokalise, Crowdin, Transifex, memoQ) | Inline tag drift, trans-unit state not updated | CAT tool: Trados, memoQ, OmegaT |
For deeper detail on the editor class, see i18n-editor: What Translators Use to Edit JSON Translation Files.
What does a React/Next.js i18n handoff look like in practice?
A React handoff is almost always a /public/locales/{lang}/{namespace}.json tree with {{name}} placeholders and <Trans> inline components, delivered through react-i18next or next-i18next and consumed via the useTranslation hook. Next.js App Router projects add a locales array in config and an appWithTranslation wrapper with a server/client component split.
A specimen handoff:
/public/locales/ ├── en/ │ ├── common.json │ └── auth.json ├── fr/ │ ├── common.json │ └── auth.json └── ar/ ├── common.json └── auth.json
Framework-specific pipeline detail is on React i18n: How Translators Fit Into a React Localization Pipeline.
What signals that the i18n layer is 'not ready' and the handoff must be rejected?
Reject the handoff when hardcoded strings remain in source, placeholders use mixed syntaxes, ICU plural categories are missing for languages like Arabic or Russian, or screenshots are absent for keys like 'Submit' that collapse into one key for three UI states. Internationalization is complete only when five conditions hold in the source build:
- Strings externalized — no literals in source files.
- ICU plural and gender rules declared for every count and gendered noun.
- Date, number, currency, phone, and address formats resolve from locale IDs.
- Right-to-left mirroring works end-to-end.
- No copy baked into images or canvas.
A readiness defect list is a single-page audit artifact; see Localisation Strategy: How Agencies Plan, Price, and Deliver Multi-Locale Programs for how agencies hand that back to engineering.
How does i18n translation work step by step for a web development project?
i18n translation runs in six steps: receive the resource bundle, lock placeholder parity, draft target strings in an i18n-editor or TMS, validate ICU plurals, run LQA against an MQM-style scorecard aligned to ISO 17100, and commit the per-locale file back to the repo or TMS connector.
Three real handoff shapes recur in web-dev projects:
- A
public/localesJSON tree pulled from a Git repo. - An XLIFF export produced by a TMS connector (Phrase, Lokalise, Crowdin, Transifex, memoQ).
- PO files from a Git-tracked WordPress, Django, or gettext project.
flowchart LR A[Intake bundle] --> B[Lock placeholder parity] B --> C[Draft in editor/TMS] C --> D[Validate ICU plurals] D --> E[LQA against MQM scorecard] E --> F[Commit per-locale file]
Step 1 — How do you intake a JSON or XLIFF bundle without breaking the keys?
Clone or download the resource bundle read-only, diff it against the previous version to identify changed keys, and open it in an i18n-editor that locks the key column so only values are editable. Preserve the key order the source ships with. Run pseudo-localization on the source before translating so overflow and hardcoded strings surface before words are spent — covered on Pseudo Localization: What Translators Need to Know About i18n Test Builds.
Step 2 — How do you preserve placeholders, ICU plurals, and inline tags?
Preserve five placeholder classes verbatim: {{name}} double-brace, {0} positional, %s printf, <Trans> inline React components, and ICU {count, plural, one {# item} other {# items}} blocks — any drift breaks the production build.
Run a placeholder-parity checklist before saving every JSON handoff:
- Every
{{variable}}in source appears identically in target. - Every
{0},{1}positional index is retained — reorder in text, never in syntax. - Every
%sand%dprintf token is kept in the same order the source uses it. - Every
<Trans>or<0>…</0>inline tag is closed and nested the same way. - Every ICU
selectandpluralblock retains its categories and#placeholder.
Step 3 — How do you handle plural, gender, and select rules per locale?
Declare every CLDR plural category the target language requires — English has one and other, French adds many, Russian uses one/few/many/other, Polish uses one/few/many/other, and Arabic uses zero/one/two/few/many/other.
| Locale | CLDR plural categories |
|---|---|
| English (en) | one, other |
| French (fr) | one, many, other |
| Russian (ru) | one, few, many, other |
| Polish (pl) | one, few, many, other |
| Arabic (ar) | zero, one, two, few, many, other |
A sample ICU block translators receive:
{itemCount, plural,
one {# item in your cart}
other {# items in your cart}
}
For Arabic, the same key expands to six categories; omitting zero or two ships a broken plural at runtime.
Step 4 — How do you commit translations back without triggering a merge conflict?
Commit per-locale files on a branch named locale/{lang}, run the i18n linter the client ships, and open a pull request so the CI pipeline can rebuild the bundle, run pseudo-localization, and surface overflow before merge. Keep the key order the source file uses. Namespaces exist so bundles load on demand — split by feature (common.json, auth.json) and never merge two namespaces into one commit.
A locale fallback chain resolves missing keys at runtime without breaking the UI: fr-CA → fr → en. A translator who leaves a key untranslated as an empty string disables that chain for that key.
Which tools do translators use for i18n translation in 2025?
Translators use three tool classes: standalone i18n-editors for JSON/YAML/PO/XLIFF, TMS platforms like Phrase, Lokalise, Crowdin, Transifex, or memoQ for larger programs, and Git-connected CAT tools when the client prefers pull-request-based delivery.
| Tool class | Best fit | Formats | Delivery model |
|---|---|---|---|
| i18n-editor (standalone) | Under 5,000 keys, 3 or fewer locales, release-based | JSON, YAML, PO, XLIFF | File in / file out |
| TMS (Phrase, Lokalise, Crowdin, Transifex, memoQ) | 5,000+ keys, 4+ locales, weekly cadence | All, via connector | Git / CI/CD connector |
| CAT tool (Trados, memoQ, OmegaT) | XLIFF from TMS export, agency-side reviewer workflow | XLIFF 1.2 / 2.0, TMX | Package in / package out |
When is a standalone i18n-editor enough?
A standalone i18n-editor handles projects under roughly 5,000 translation keys, three or fewer target locales, and release-based delivery — above that threshold translation memory leverage, reviewer gates, and LQA sampling demand a TMS. Full detail on scope, placeholder parity, and ICU validation is on i18n-editor: What Translators Use to Edit JSON Translation Files.
When does the project need a Translation Management System on top?
The project needs a TMS when the key count passes 5,000, four or more locales ship in parallel, or commits land weekly on a continuous-localization cadence. File-based editing loses TM leverage, has no reviewer gate, and cannot run the LQA sampling that certified lanes require. The same thresholds published on our continuous-localization guide apply here — see Continuous Localization: How Translators and Agencies Run the Delivery Model.
How does machine translation fit into i18n translation production?
Machine translation enters as a pre-translate stage on repetitive UI strings, with human post-editing (MTPE) priced per word and a mandatory LQA gate at $40–$90 per 1,000 words against an MQM-style scorecard aligned to ISO 17100 before the locale ships. MT without the LQA gate is not an i18n translation deliverable on a certified lane.
What quality gate does i18n translation have to pass before a build ships?
Every i18n translation job on a certified lane passes an LQA gate at $40–$90 per 1,000 words, scored against an MQM-style scorecard aligned to ISO 17100 covering accuracy, fluency, terminology, locale convention, and style — regardless of whether a translator, CAT tool, or AI produced the draft. The gate is not optional: it is the mechanism that separates a certified deliverable from an unreviewed string dump, and it applies equally to flat JSON files and to complex XLIFF 2.0 bilingual packages.
What does the MQM-style scorecard measure on a JSON locale file?
The scorecard samples strings for five error categories — accuracy, fluency, terminology, locale convention, and style — then weights each by severity to produce a pass/fail against a job-specific threshold. Accuracy errors are the most severe class: a string that conveys the wrong meaning in the target locale is a critical failure even if it is grammatically flawless. Locale convention errors cover the parameters each locale carries beyond raw language — date formats, currency symbols, and measurement units must all conform to the conventions of the target region, not simply be transliterated from the source. Style errors are weighted at minor or major depending on the style guide in force for the product.
What breaks i18n translation builds and never shows up in a word count?
Six silent failures break builds: dropped placeholders, mojibake from the wrong encoding, missing ICU plural categories, overlong strings that overflow fixed widths, untranslated keys committed as empty strings, and markup drift <Trans> components. None of these failures appear in a word count or a simple diff — they require a dedicated pre-commit check or a pseudo-localization pass to catch before the build pipeline runs. Framework-specific failures compound the risk. When ICU message formatting runs inside a server/client component architecture, a plugin class cannot pass directly from a Server Component to a Client Component — the ICU provider requires a deliberate 'use client' wrapper that word-count tooling and standard LQA sampling will not surface.itecture, a plugin class cannot be passed directly from a Server Component to a Client Component, so the ICU provider itself requires a deliberate 'use client' wrapper — an integration detail that neither word-count tooling nor standard LQA sampling will surface on its own.
- Dropped placeholders —
{{name}}deleted during translation. - Mojibake — file saved as Windows-1252 instead of UTF-8.
- Missing ICU categories —
zeroortwoomitted for Arabic. - Overflow — German string 40% longer than the English source blows the button width.
- Empty strings — fallback chain disabled for that key.
- Markup drift —
<0>…</0>left unclosed, React render fails.
How does i18n translation fit a certified translation production workflow?
On certified lanes, i18n translation runs the same gates as document work: a translator plus an independent reviewer per ISO 17100, LQA against an MQM-style scorecard at $40–$90 per 1,000 words, and — when the locale bundle feeds an immigration or legal UI — a signed certificate of accuracy on every page of printed evidence. The deliverable is a locale bundle plus the LQA report and, where printed evidence is required, a certification statement bound to the strings that render on the user's screen.
Internationalization is the engineering discipline that makes software adaptable to different languages and regions without requiring code changes; localization is the subsequent process of adapting that software to the linguistic, cultural, and technical requirements of a specific locale. i18n translation sits at the intersection of both — it is the step that takes the engineer's externalized strings and produces a fully adapted, reviewable resource file for each target locale. This means the translator is not just swapping words: they are responsible for preserving the technical structure (placeholders, ICU rules, encoding) that the internationalization layer depends on, while also satisfying the cultural and terminological expectations that localization demands.
A certified workflow treats each resource file format as a distinct document type with its own structural rules. A flat JSON file, a namespaced JSON bundle, a YAML file, a PO/POT catalog, or an XLIFF 1.2 or 2.0 package each imposes different constraints on how segments are delimited, how metadata is stored, and how the translation memory system reads and writes units. Translators working under ISO 17100 must demonstrate competence in whichever format the handoff uses — not merely language competence. The LQA reviewer then validates the file structurally as well as linguistically, confirming that the target-locale resource file is ready to drop into the build pipeline without modification.
When a locale bundle feeds a user-facing legal or government-adjacent interface, the certification statement is not a courtesy — it is a required artifact that attests to the completeness and accuracy of every string the end user sees. In those contexts, the workflow also mandates that the CAT environment or Translation Management System produce an auditable record linking each source segment to its reviewed translation, so the certifying translator signs against a traceable output rather than a reconstructed export.
How we run i18n translation jobs
We take an i18n translation job only when the four input artifacts arrive together: resource file, placeholder spec, ICU plural table, and screenshot or Storybook context for every ambiguous key. A handoff missing any of them comes back as a one-page defect list, not a quote. That refusal is the single biggest driver of a clean build at merge.
We will not translate directly in a copy of the source file. Keys get locked in an i18n-editor or TMS so only values are editable, and every placeholder class is validated before save. We decline the shortcut of pasting JSON into a general-purpose chatbot — placeholder parity, ICU category completeness, and encoding integrity are not probabilistic deliverables.
We will not sign a certification statement for a locale bundle that has not passed the LQA gate at $40–$90 per 1,000 words against an MQM-style scorecard aligned to ISO 17100. MT output ships only after human post-editing and that same gate — the price does not change because the first draft came from an engine.
Above 5,000 translation keys, four locales, or a weekly commit cadence, we move the program to a TMS connector. File-based editing stops producing the TM leverage and reviewer trail certified work needs; carrying on in an i18n-editor past that point is a defect waiting to be billed.
Six questions recur on every i18n translation brief: what the tool is for, whether it handles JSON, how blog-post localization fits, how web-dev projects actually run it, what i18n means in one line, and how it differs from l10n.
Frequently asked questions
What is the i18n Translation Tool used for?
The i18n Translation Tool is used to extract, translate, and repackage localizable strings stored in developer resource files — primarily JSON, YAML, and XLIFF — so that software interfaces can be shipped in multiple languages. Working translators and agencies use it to receive structured string files from dev teams, produce accurate first-draft or certified translations for each locale, and return locale-ready builds without breaking file syntax. It bridges the gap between a developer's codebase and a translator's workflow, cutting manual reformatting time significantly.
Can the i18n Translation Tool handle JSON files?
Yes, the i18n Translation Tool natively handles JSON files, which are the most common format for storing UI strings in modern web and mobile apps. It parses nested key-value structures, preserves interpolation placeholders (e.g., {{username}} or %s), and returns a locale-specific JSON file that drops straight back into the project. This means translators work only on the string values, never touching keys or code logic, which dramatically reduces the risk of introducing syntax errors into a production build.
How does i18n translation work for web development projects?
In web development, i18n translation works by externalizing all user-facing strings into resource files (JSON, YAML, or XLIFF), then loading the correct locale file at runtime based on the user's language setting. Developers tag strings with keys rather than hardcoding text, an i18n library (such as i18next, react-intl, or Vue I18n) fetches the matching translations, and the UI renders in the target language without a code change. Translators produce the locale files; the tool ensures formatting, pluralization rules, and placeholders remain intact across every language.
What does localization mean?
Localization (L10n) means adapting a product — its text, formats, imagery, and cultural references — so it feels native to a specific locale, not merely translated word-for-word. Beyond language, it covers date and number formats, currency symbols, right-to-left text direction, legal disclaimers, and culturally appropriate examples. For software, localization starts with i18n-ready code and ends with certified, locale-specific resource files delivered by professional translators. A fully localized product in, say, Brazilian Portuguese differs from European Portuguese not just in spelling but in tone, units, and regulatory language.
What is localisation in translation?
Localisation in translation refers to the process of adapting translated content to the cultural, legal, and technical norms of a specific target market — going beyond literal word substitution. A translator localising a SaaS product for the German market, for example, must handle formal address conventions (Sie vs. du), EU-specific GDPR language, decimal comma notation, and locale-coded date formats (DD.MM.YYYY). Localisation is considered a higher-skill deliverable than straight translation and is what agencies certify when signing off on a localized build.
What is 18 in i18n?
The 18 in i18n stands for the 18 letters between the first letter 'i' and the last letter 'n' in the word 'internationalization.' This style of abbreviation — called a numeronym — shortens long technical terms for convenience; 'localization' is similarly shortened to L10n (10 letters between L and n). The convention became common in software engineering during the 1980s and is now the industry-standard shorthand used in framework names, configuration keys, and file-format specifications across the entire software localization industry.
Why is localization called L10n?
Localization is called L10n for the same reason internationalization is called i18n: it is a numeronym where the number replaces the letters between the first and last character of the word (L + 10 letters + n). The convention keeps long compound terms manageable in code comments, CLI flags, and documentation. Both numeronyms originated in engineering communities — reportedly at DEC and later at Sun Microsystems in the 1980s — and have since been adopted universally across the software translation and SaaS industry.
Why use i18n?
Teams use i18n so that adding a new language requires only a new resource file, not a rewrite of application code. By externalizing strings into JSON, YAML, or XLIFF from the start, a single codebase can serve dozens of locales simultaneously — a critical commercial advantage when expanding into new markets. For translators and agencies, an i18n-structured project means clearly scoped work (a finite list of keys), consistent context, and the ability to produce and certify localized builds systematically rather than hunting for translatable text scattered through source code.
Where did the I18n come from?
The numeronym i18n is widely attributed to Digital Equipment Corporation (DEC) engineers in the early 1980s, who needed a compact way to reference 'internationalization' in internal documentation and memos. It gained broader adoption through UNIX and X Window System internationalization efforts, and by the 1990s it appeared in W3C standards documentation. Today it is embedded in the names of major frameworks and libraries — i18next, Rails I18n, Angular i18n — making it one of the most enduring pieces of software engineering shorthand in the industry.
Does it support blog post localization?
The i18n Translation Tool is optimized for structured developer resource files (JSON, YAML, XLIFF) rather than free-form content like blog posts, which are handled through CMS-based localization workflows. That said, if a blog or documentation site exports content to XLIFF or structured Markdown with YAML front matter, those files can move through the same i18n pipeline. Agencies producing certified translations of technical documentation — API guides, release notes, help-center articles — use XLIFF exports from platforms like Contentful or Phrase to keep content localization inside a single certified workflow.
Related
- i18n-editor: What Translators Use to Edit JSON Translation Files
- i18n: What Internationalization Means for Translators Producing Localized Builds
- memoQ as a CAT Tool: Features, Licensing, and Certified-Lane Fit
- Guides for translators and translation agencies
- Certificate of translation accuracy: what it must say
- Who can certify a translation?