XLIFF vs YAML: Which Localization Format Fits Your Team
XLIFF vs YAML: Which Localization Format Fits Your Team

XLIFF and YAML are not really rivals. XLIFF is an exchange format built to move source text and translations between tools and translators. YAML is a general-purpose data format that many frameworks use to store strings at runtime. If your app reads YAML and your translators work in a professional tool, you will probably end up using both, with a conversion step in between. If you are a small team with no translation tools in the loop, YAML alone is usually the simpler choice.
This guide explains what each format does, how they handle keys, context, plurals and placeholders, what can go wrong when you convert, and how to decide.
TL;DR
- XLIFF is a bilingual interchange format for translation tools. YAML is a human-friendly data format that frameworks such as Rails and Symfony read directly.
- XLIFF carries source, target, notes and inline codes in one file. Plain YAML carries a key and a value, so context has to live in comments, naming or a side file.
- Choose YAML when developers edit strings by hand and your framework loads it. Choose XLIFF when translators or CAT tools are involved.
- Most conversion bugs happen at plurals, placeholders and comments. Validate the output before it ships.
- You can also skip the decision: generate each format from one approved source and let the packaging step handle conversion.
Table of Contents
- What XLIFF and YAML actually are
- How each format stores a string
- Side-by-side comparison
- Keys, context and metadata
- Plurals and placeholders
- When each format fits your workflow
- What can change or get lost in conversion
- Check your stack before you commit
- Our perspective
- Getting delivery-ready files without the format debate
- A practical decision path
- FAQ
- Sources
What XLIFF and YAML actually are
XLIFF stands for XML Localization Interchange File Format. The OASIS XLIFF 2.0 specification defines it as a bilingual document format that holds source text, the corresponding translations and auxiliary data that supports the translation process. OASIS describes its purpose as carrying localizable data from one step of the localization process to the next while keeping tools interoperable, as stated in the XLIFF 2.1 announcement.
YAML is a recursive acronym: YAML Ain’t Markup Language. The YAML 1.2.2 specification calls it a human-friendly data serialization language, useful for everything from configuration files to messaging. It was never designed for translation. It just happens to be readable, which is why Rails keeps its locale files in config/locales/*.yml and other stacks follow suit.
That difference in purpose explains almost every trade-off below. XLIFF is a container for a process. YAML is a container for data.
Is YAML just JSON?
Not quite, though they overlap. Both describe maps, lists and scalar values. YAML uses indentation and supports comments, anchors and multi-line strings. JSON uses braces and quotes and has no comments. For localization, the comment support is the practical difference, and the indentation is the practical risk. If you are weighing those two, our comparison of JSON vs YAML for localization goes further.
How each format stores a string
Here is the same string in both formats.
en:
checkout:
pay_button: "Pay %{amount}"
<unit id="checkout.pay_button">
<notes><note>Button on the final checkout screen</note></notes>
<segment>
<source>Pay <ph id="1" equiv="amount"/></source>
<target>Payer <ph id="1" equiv="amount"/></target>
</segment>
</unit>
The YAML file is shorter and a developer can read it at a glance. The XLIFF unit is longer, but it holds a note for the translator, marks the placeholder as a protected inline code, and keeps the source and the target side by side. Per the OASIS specification, a file can start with only source-language text and receive targets later, which is how translation tools hand work back and forth.
Side-by-side comparison
| Criterion | XLIFF | YAML |
|---|---|---|
| Primary purpose | Exchanging translation data between tools | Storing structured data, including app strings |
| Source and target together | Yes, in one unit | No, one file per language |
| Context for translators | Notes, annotations, metadata | Comments or key names |
| Placeholders | Inline codes that tools can protect | Plain text inside the value |
| Plurals | Modules and attributes, depending on version | Convention-based key sets, depending on framework |
| Human readability | Verbose | High |
| Diff-friendly in version control | Noisy | Clean |
| Tool support | Broad CAT and review tooling | Framework loaders and text editors |
| Typical consumer | Translators and localization tools | Your running application |
Neither column wins outright. They answer different questions.
Keys, context and metadata
In YAML, the key path is the identity of the string. A key such as checkout.pay_button tells a developer where it lives, but it tells a translator almost nothing. You can add comments above keys, but whether those comments survive a round trip depends on the parser. Many parsers discard them.
XLIFF treats context as a first-class citizen. Notes, annotations and extra metadata sit inside the unit, so a reviewer sees them next to the text. This is why XLIFF is the usual answer when professional translators or review tools are involved. The comparison pieces that rank for this query mostly agree on this point, and also on a caveat worth keeping: the format matters less than supplying real context for every string.
If your team stays in YAML, put the context in a consistent place. A short comment per key works, and so does a separate metadata file per language. We cover the second approach in structured metadata generation.
Plurals and placeholders
This is where formats get tested.
Plural rules differ by language. English has two forms, Russian has more, and Arabic has six. A string that reads fine in English can break in another language if the file only offers “one” and “other”.
In XLIFF, newer versions address this directly. Symfony’s documentation says the Plural, Gender and Select module in XLIFF 2.2 expresses variation through unit and segment attributes, and that Symfony’s loader converts those forms into ICU MessageFormat strings. See the Symfony XLIFF reference. Older XLIFF 1.2 files have no such module, so plural handling there depends on conventions your tools agree on.
In YAML, plurals follow whatever your framework expects: often a set of keys such as one, other and, for some languages, few or many. Nothing in the format enforces that all required forms exist, so a missing one fails silently until a user sees it.
Placeholders are the second hazard. XLIFF can mark them as inline codes so a tool refuses to translate or delete them. In YAML a placeholder is just characters inside a string, so a translator or machine translation engine can rename %{amount} or drop it. Whichever format you use, check every translated string for the same placeholders as its source. Our guide to ICU message format checks lists the three we run before anything ships, and catching missing CLDR plurals in CI shows how to automate the plural check.
When each format fits your workflow
Choose YAML when
- Developers write and edit strings themselves.
- Your framework loads YAML natively, as Rails does.
- You want clean diffs and small pull requests.
- Translation is done by a small group, or by an automated process that returns files in the same format.
If that describes you, a YAML file per locale is hard to beat for simplicity. We handle that case in localizing YAML language files.
Choose XLIFF when
- Translators work in CAT tools or review platforms that expect it.
- You outsource translation and need to hand over source, context and constraints in one file.
- You build for Apple platforms, where Xcode exports and imports localizations as XLIFF.
- You need a preview-and-test loop for translated layouts.
Microsoft’s guidance on exchanging localizable resources describes this kind of workflow: CAT tools extract the translatable text, keep non-translatable material in skeleton files, and use those files to rebuild translated source files for preview and testing. Microsoft notes this matters because translation can change text length, fonts, directionality, pagination and wrapping. For a practical look at that loop on the Apple side, see our XLIFF localization workflow article.
A translated string that no longer fits its button is a real bug, and it only shows up when you actually test the layout. Effective app localization covers why testing in the target market matters before launch.
Use both when
Many teams keep YAML (or JSON, or Android XML) as the runtime format and treat XLIFF as the interchange layer. Developers see clean files, translators see rich units. The cost is a conversion step, and that is where the risk sits.

What can change or get lost in conversion
Converting between the two is easy to start and easy to get subtly wrong. Online converters advertise that they keep keys, plurals and placeholders, which is a useful baseline, but check each of these against your own files:
- Comments. YAML comments often have no home in XLIFF, or become notes only if the converter maps them. Going the other way, XLIFF notes usually vanish in YAML.
- Source text. YAML locale files hold one language each. When you build XLIFF from them, you pair a source file with a target file. If the key sets differ, you get orphans and gaps.
- Plural structure. Key-based YAML plurals and XLIFF plural constructs are different models. A converter has to translate between them, and ICU-style strings may be flattened or split.
- Placeholders. A converter may turn
%{name}into an inline code or leave it as plain text. Both can be valid, but your pipeline must expect one of them. - Whitespace and quoting. YAML is indentation-sensitive. A stray tab, an unquoted colon or a value that looks like a boolean can change meaning. Quote values consistently.
- XLIFF version. XLIFF 1.2 and 2.x have different structures, and not every tool reads both. Symfony 8.1, for instance, added support for XLIFF 2.1 and 2.2, so check your own framework’s version support rather than assuming.
- Key order and IDs. Reordering is harmless in YAML but can break ID matching in tools that depend on stable unit IDs.
A simple safeguard: convert, then convert back, and diff the result against the original. Anything that disappears in the round trip is something you have to preserve another way.
Check your stack before you commit
Support varies by ecosystem. The Composer Translation Validator documentation lists XLIFF support for TYPO3 CMS and optional support for Symfony, and YAML support mainly for Symfony, along with Laravel. That is one PHP-world snapshot, not a universal rule.
Before choosing, answer four questions:
- Which format does your framework or platform load natively?
- Which format do your translators or review tools accept?
- Does your build fail when a locale is missing a key or a plural form?
- Who owns the conversion, and is it automated?
If the first two answers differ, plan for conversion and validation from day one.
Our perspective
We build localization production for small teams, and we see the same pattern repeatedly. Teams pick a format early, then spend months fighting the mismatch between what developers want and what translators or tools need. The format is rarely the real problem. The real problem is that nobody owns the path from approved source text to files the app can load.

Our view is that format should be an output, not a decision you carry around. Keep one approved source, generate each target format from it (JSON, iOS strings, Android XML, YAML), validate placeholders and plurals on the way out, and package the result so a reviewer can inspect it before release. That is how we work with the Quiet Harbour app: one source, several languages, a consistent product experience. You can read the details in the Quiet Harbour case study.
It also means you do not need repository access or a full translation management system to get there. We explain that approach in localization without repository access.
— Arkian
Getting delivery-ready files without the format debate
If you would rather not hand-maintain converters, Arkian generates localization strings from your approved source and ships them through structured packaging as reviewable, delivery-ready language files, with an organized output folder structure. Plans are on the pricing page: a membership at CA$19.00 per month, or one-off packs at CA$29.00 (Starter), CA$79.00 (Pro) and CA$249.00 (Studio).
A practical decision path
- List your consumers. Name what loads the files (framework, app) and who edits them (developers, translators, tools).
- Pick the runtime format first. Use whatever your framework loads natively.
- Add XLIFF only if a tool or translator needs it. Do not add a format just because it is the standard.
- Automate conversion and test the round trip. Do not rely on manual exports.
- Validate before release. Check placeholder parity, required plural forms, and key coverage for every locale.
- Preview real layouts. Longer strings and right-to-left languages break screens that looked fine in English.
FAQ
What is an XLIFF file?
An XLIFF file is an XML document that holds source text, its translations and supporting data such as notes and inline codes. Translation tools use it to pass content between steps of a localization process. A file can start with only source text and gain translated targets later.
What does YAML stand for?
YAML stands for “YAML Ain’t Markup Language,” a recursive acronym. The YAML specification describes it as a human-friendly data serialization language. It is widely used for configuration and, in some frameworks, for translation files.
Is XLIFF better than YAML for translation?
For working with translators and CAT tools, usually yes, because it carries context, placeholders and source-target pairs together. For runtime use and hand editing by developers, YAML is simpler and diffs better. Many teams keep YAML in the app and use XLIFF only for exchange.
Can I convert YAML to XLIFF without losing data?
Only if you check the risky areas: comments, plurals, placeholders and key coverage. Convert, convert back, and diff the result against the original. Add validation to your build so a lost plural form or placeholder fails before release.
Sources
- XLIFF Version 2.0, OASIS
- XLIFF V2.1 OASIS Standard published
- YAML Ain’t Markup Language revision 1.2.2
- The XLIFF format, Symfony Docs
- Exchanging localizable resources, Microsoft Learn
- File Formats, Composer Translation Validator
- Reach new markets with effective app localisation