Arkian logo
Start free
Menu
← All articles

JSON vs YAML for Localization: Which Format Fits Your Team

JSON vs YAML for Localization: Which Format Fits Your Team

Developer comparing JSON and YAML localization files

For most small teams shipping a web or mobile app, JSON is the safer default for translation files, and YAML is the better pick when humans edit the files by hand and need inline notes. Both can hold the same strings. The real differences are how they handle comments, whitespace, plurals and validation, and those decide how many broken builds you see after a translation round.

This guide walks through each difference with the specifics that matter in localization work, then gives you a decision table you can apply to your own project.

Arkian
Keep Localization Files Organized
Arkian automates multilingual scripts, voice outputs, and structured language packages, with validation and packaging built into the workflow.
Explore Arkian

TL;DR

  • JSON is strict and bracket-based, so whitespace mistakes can’t silently corrupt a translation file. It has no comments, though.
  • YAML is easier to read and lets you add notes next to keys, but indentation errors and tab characters cause parsing problems.
  • Neither format knows anything about plurals. You need a convention, usually built on Unicode CLDR categories, and a check that enforces it.
  • Pick the format your i18n library already reads. Switching formats rarely fixes a localization problem. Validation does.
  • Whichever you choose, check every locale file automatically before release: missing keys, missing plural forms and broken placeholders.

Table of Contents

What JSON and YAML have in common

Both formats represent the same building blocks: strings, numbers, booleans, null, lists and nested objects. For translation files you almost only use two of them: nested objects (keys grouped by screen or feature) and strings (the text itself).

The two formats are also closely related. The YAML 1.2 revision’s stated main goal was bringing YAML into compliance with JSON as an official subset, so a valid JSON document is generally readable by a YAML 1.2 parser. The reverse is not true: YAML features such as comments don’t survive a trip into JSON.

That means conversion is cheap in one direction and lossy in the other. If your team may ever move from YAML to JSON, any translator notes written as YAML comments will be dropped unless you move them into a separate field first.

What JSON and YAML have in common — overview diagram

Where JSON wins for localization

Strict structure

JSON uses braces, brackets, quotes and commas. Indentation is cosmetic. You can minify a file onto one line, reformat it with any editor, and it still means the same thing. For a small team where translators, developers and automated tools all touch the same files, that predictability is worth a lot.

YAML, by contrast, uses indentation to define structure. The YAML 1.2.2 specification forbids tab characters for indentation so files stay portable across systems. In practice that means a contributor whose editor inserts a tab, or who pastes a block with mixed spacing, can produce a parsing error or, worse, a key that quietly lands at the wrong nesting level. JSON’s bracket-based structure is immune to that whole class of mistake.

Tooling is everywhere

JSON is native to JavaScript and well supported across front-end frameworks and mobile toolchains. Most translation tooling can read and write it, and standard parsers are strict, so a malformed file fails loudly rather than loading half a language.

Schema validation

JSON has a standard, machine-readable way to say what a file must look like. JSON Schema is a vocabulary for validating the structure of JSON documents, and localization teams can use it to enforce rules across every locale: required keys, string-only values, and a consistent set of plural keys such as _one and _other. One schema, run against en, de, ja and the rest, catches drift before a reviewer ever sees it.

The cost of JSON

The main drawback is the absence of comments. You can’t write a note such as “this is a button label, keep it under 12 characters” beside a string. Teams work around it with a parallel key (for example a _context sibling), a separate metadata file, or a naming convention. All of these work. None is as natural as a comment.

JSON also makes long strings awkward. Multiline text needs escapes, and quotes inside strings need backslashes, which makes review harder for translators reading raw files.

Where YAML wins for localization

Readability

YAML drops most punctuation. A nested block of keys and values reads almost like an outline, and long strings can be written across lines without escape sequences. If your files are edited by hand by non-developers, such as a marketer or a freelance translator opening a text editor, YAML often feels friendlier.

Comments, with a limit

YAML allows comments, so a developer can leave a note for translators on its own line or beside a key. There is a limit worth knowing: the YAML 1.2.2 specification says comments must not appear inside scalar values. You can annotate a key-value pair, but not drop a note into the middle of a translated string. For localization, that is usually what you want anyway, because the note stays out of the text that ships.

The catch is the one-way conversion above. Comments are lost when a YAML file is exported to JSON, so anything important enough to survive a pipeline should live in a real field.

The cost of YAML

Whitespace sensitivity is the big one, and it bites hardest on small teams without a dedicated localization engineer. Indentation errors, tabs mixed with spaces, and unquoted strings that a parser interprets as something other than text are all common causes of broken locale files. Quote any string that begins with a special character, contains a colon followed by a space, or could be read as a boolean or number. Test it with the parser your app actually uses, because behavior differs between YAML versions and libraries.

Plurals: neither format helps you

This is the point most JSON vs YAML comparisons skip, and it is where localization breaks in production.

Neither format has a built-in concept of plural forms. Languages differ widely: some have two forms like English, some only one, and some several. The shared reference for this is Unicode CLDR, which defines the plural categories (zero, one, two, few, many, other). The CLDR 49 alpha announcement lists 100 languages at the modern level, described as suitable for full UI internationalization.

So in either format you must adopt a convention. A common one in JSON looks like this:

{
  "cart": {
    "items_one": "{{count}} item",
    "items_other": "{{count}} items"
  }
}

The YAML equivalent is the same keys with different punctuation. The format changes nothing about the problem: English needs two keys, while a language such as Russian or Arabic needs more. A file that looks complete in English will be incomplete in those languages unless every CLDR category the language requires is present.

The practical fix is a check, not a format change. JSON gives you a head start because a schema can express the required keys, but you can write the same check for YAML with a script. Our guide to catching missing CLDR plurals in CI shows what that validation covers, and our note on ICU message format covers the alternative of putting plural logic inside the string itself.

Placeholders and locale codes break both formats equally

Two other failure points have nothing to do with JSON or YAML, and they cause more shipped bugs than the file syntax does.

Placeholders. A translator who edits {{count}} into {{ Count }} or drops it entirely will break the interface in that language only. Compare the set of placeholders in every translated string against the source string. We cover that approach in how small teams catch broken tokens in CI.

Locale codes. pt-BR, pt_BR and pt are not interchangeable in every library, and the file naming has to match what the loader expects. See our rules on BCP 47 language codes for the common traps.

Side-by-side comparison

Criterion JSON YAML
Comments Not supported; use a sibling key or separate file Supported beside keys, not inside string values
Whitespace risk None, indentation is cosmetic High, tabs forbidden and indentation defines structure
Readability for non-developers Moderate, quotes and escapes add noise Good, minimal punctuation
Multiline strings Needs `
` escapes Block styles, no escapes needed
Schema validation Standard JSON Schema Possible, often by validating converted data
Plural handling Convention only Convention only
Conversion to the other format Loads in a YAML 1.2 parser Comments are lost going to JSON
Failure mode Loud parse error Parse error or silently misplaced key

How to choose

Start with the constraint you can’t change, then apply these questions in order.

  1. What does your i18n library read? If your framework expects one format, use it. Converting at build time adds a step that can fail.
  2. Who edits the files? If translators or non-technical staff open raw files, YAML’s readability and comments help. If files are touched mainly by tools and developers, JSON’s strictness helps.
  3. How many languages and contributors? More locales and more hands mean more chances for a whitespace slip. That favors JSON, or YAML with a strict linter.
  4. Do you need translator context? In JSON, plan for a context field or metadata file from day one. In YAML, comments can do the job, but export them if the files move between systems.
  5. Can you validate automatically? If the answer is no today, choose the format whose failures are loudest. That is JSON.

For a team of two to ten people shipping a mobile or web app in several languages, the safe recommendation is JSON for the strings and a short schema to guard the structure. Use YAML when the framework you’ve committed to expects it, and add a linter that rejects tabs.

A note on automation in your pipeline

Once validation runs on every change, the format matters less because mistakes are caught before release. The same thinking applies beyond strings: if you publish localized web pages, regenerating language-related output on each change is easier to maintain than editing by hand, as in this guide to automating hreflang tags in CI/CD. Treat locale files, metadata and page markup as generated artifacts with checks, not as documents someone remembers to update.

Our perspective

We build localization production for small teams, and the pattern we see is consistent: format debates take up more time than they deserve, while the failures that hurt are missing plural forms, altered placeholders and files that don’t match what the app loads.

Our perspective — overview diagram

Our view is that a small team should choose the format its framework already reads, then spend the saved effort on validation and packaging. A reviewable, validated package for each language is worth more than the perfect file syntax. That is why Arkian produces the output in the format your project expects, whether that is JSON or YAML, and validates it before packaging, without asking for access to your repository or requiring a full translation management system.

If you must hand-edit files, we’d lean JSON for safety and add context in a separate field. If your translators live in the files, we’d lean YAML and lint for tabs. In both cases, the check matters more than the choice.

— Arkian

Getting validated language files without a TMS

If you want the translation, structure checks and packaging handled in one run, Arkian’s localization strings service produces app strings in JSON, YAML, iOS strings and Android XML, packaged and ready for review. Pricing is on the pricing page: the Membership is 19.00 CAD per month, and one-off packs are Starter at 29.00 CAD, Pro at 79.00 CAD and Studio at 249.00 CAD. You can also see the approach applied to a real product in the Quiet Harbour case study.

FAQ

Is YAML better than JSON for translation files?

Not universally. YAML is easier to read and allows comments, which helps hand-edited files. JSON is stricter and immune to indentation errors, which helps teams where many people and tools touch the files. The better choice is usually the one your i18n library already supports.

Can I convert YAML translation files to JSON?

Yes, the data structures map across cleanly, since both represent nested objects and strings. The one thing you lose is comments, so move any translator notes into real fields before converting. Run your validation checks on the converted files too.

How do I handle plurals in JSON or YAML?

Use a naming convention based on CLDR plural categories, such as _one and _other keys, or put plural logic in an ICU message. Then check every language has the categories it needs. The file format does not enforce this for you.

Why do YAML translation files break so easily?

Because structure depends on indentation, and tabs are not allowed for indentation in the YAML specification. A stray tab, inconsistent spacing or an unquoted special character can cause a parse error or move a key to the wrong level. A linter in your CI pipeline catches most of these.

Sources