YAML vs JSON for translation files: nesting, comments, and version control

Plenty of software projects — especially web frameworks and JavaScript-heavy stacks — store translations as YAML or JSON rather than in a platform-specific resource format. Both are perfectly capable of representing the same data: nested keys, one file per language. But they are not interchangeable in practice, because the differences show up not in what they can store but in how they behave when a human edits them and a version control system tries to merge two people's changes.

Nesting and key paths

Both formats support nested objects, and translation tooling almost always uses that nesting to group keys by screen or feature, addressing a specific string by a dotted key path like nav.settings.title rather than a single flat key.

{
  "nav": {
    "settings": { "title": "Settings" }
  },
  "errors": {
    "network": "Could not connect. Check your connection and try again."
  }
}

The same structure in YAML relies on indentation instead of braces and quotes around every key:

nav:
  settings:
    title: Settings
errors:
  network: Could not connect. Check your connection and try again.

Comments — a real structural difference

JSON has no comment syntax at all; there is no standard way to leave a note for a translator inside the file itself. Teams work around this with a convention — a sibling key ending in a suffix like _comment, or a separate metadata file — but that is a workaround, not a feature of the format.

YAML supports comments natively with a hash character, which makes it possible to put translator-facing context directly next to the string it describes, the same role a comment plays in a .strings or .properties file.

errors:
  # Shown when a network request times out; keep it short, fits a small toast
  network: Could not connect. Check your connection and try again.

Multiline strings and indentation hazards

YAML has dedicated syntax for multiline text — a block scalar starting with | (preserving line breaks) or > (folding them into spaces) — which reads far more naturally for a paragraph of text than a JSON string with escaped \n sequences packed onto one line. This is one of the clearer ergonomic wins YAML has over JSON for prose-heavy content like terms-of-service text or long in-game dialogue.

The cost of that readability is that YAML's structure is defined by whitespace, and indentation mistakes are both easy to make and often silent. Mixing tabs and spaces, or shifting a line by one column, can change which key a value belongs to without producing any parse error — the file remains valid YAML, just not the structure the author intended. JSON has the opposite problem: its structure is explicit and indentation-independent, so a misplaced brace or missing comma fails loudly and immediately, which is safer for anyone hand-editing translated content but exactly why JSON has no comments and no forgiving multiline syntax — the format trades expressiveness for that strictness.

Anchors, trailing commas, and duplicate keys

YAML supports anchors and aliases — naming a block of content once with & and reusing it elsewhere with * — which can avoid repeating a string that genuinely appears twice with the same meaning, but in a translation file this is a hazard more often than a convenience: a translator has no reliable way to know a value is aliased rather than literal, and an anchor reused where a language actually needs different wording for the two contexts silently produces a wrong translation neither editor will catch by looking at the file.

JSON was designed without trailing commas, so an extra comma after the last item in an object or array is a straightforward parse error, not a warning. YAML tooling is more permissive about small trailing whitespace but strict about indentation, so the classes of mistakes that fail loudly differ between the two formats even though both are, at their core, whitespace-adjacent syntaxes.

Duplicate keys are the sharpest difference. Neither the JSON specification nor the YAML specification requires a parser to reject duplicate keys, and in practice most parsers for both formats silently accept a duplicate and keep only one value — typically the last one encountered — rather than raising an error. A translator who copy-pastes a block and forgets to rename a key can overwrite an existing translation with no warning from the file format itself; catching this requires a linter or schema check layered on top, not something either format guarantees for free.

Merge-conflict behavior in version control

Both formats are line-based text, so both work with a standard line-diff merge tool, but they do not behave identically under conflict. JSON's explicit braces and commas mean an automatic three-way merge that resolves cleanly on one branch but leaves a dangling comma or an unbalanced brace on the other is a common, annoying failure mode — the file can look merged and still fail to parse.

YAML avoids the trailing-comma class of conflict entirely, since there are no commas to leave dangling, but a merge that interleaves lines from two branches at slightly different indentation levels can silently produce a structurally different tree — reparenting a key under the wrong parent — without any conflict marker at all, because the merge tool sees no textual conflict, only different amounts of leading whitespace. Neither format is safe to trust blindly after an automatic merge; a JSON diff at least tends to fail visibly, while a bad YAML merge can pass validation and still be wrong.

What this means for translators editing files directly

When a translator works in the raw file rather than through a dedicated tool, JSON's strictness is a net safety feature — a syntax mistake is caught immediately rather than shipped — while YAML's comments and multiline blocks are a real ergonomic gain for anyone leaving context or writing long prose. Neither format is objectively better; the practical answer for most projects is to decide based on how translation actually happens: hand-edited by people in an editor, YAML's comments earn their keep despite the indentation risk; edited exclusively through a tool that serializes the file, JSON's strictness and simpler diffs are usually the safer default.