A practical guide to localizing JSON, YAML, and 17 other file formats

Translating a UI string is the easy part. Translating a UI string inside a JSON file without breaking the JSON is where most localization pipelines quietly fail. The text comes back translated and correct, and the file fails to parse, or worse, parses fine but renders {{user_name}} as {{nom d'utilisateur}} in production.

The failure modes that show up over and over

Broken structure. JSON, YAML, and XML are all whitespace- and syntax-sensitive. A translation pass that treats the file as plain text — rather than understanding which parts are structure and which parts are translatable content — can produce a file that no longer parses, or one that parses but has silently reordered or dropped keys.

Mistranslated placeholders. Almost every format has some form of interpolation: {{name}}, %s, {count}, <0>bold text</0>. These need to be preserved exactly, not translated, and not have their surrounding punctuation shifted in a way that breaks the interpolation syntax. This is the single most common thing that breaks silently — the file is valid, the translation reads fine to a reviewer skimming it, and it still crashes in production because a variable name got translated.

Flattened nesting. Deeply nested JSON or YAML structures are easy for a naive line-by-line translation process to flatten or duplicate, especially with keys that repeat across locales.

Format-specific quirks. XLIFF has translation units and state attributes that need to round-trip correctly. ARB files (used by Flutter) have metadata keys prefixed with @ that describe the translatable key next to them and must never be translated themselves. PO files have plural forms that vary in count by language — English has two plural forms, Arabic has six.

What "handling a format" actually requires

Supporting a file format for localization isn't just "read the file, translate the strings, write the file back." It requires understanding, per format:

• Which parts of the file are structure and which are translatable content
• Which values are placeholders/variables that must be preserved verbatim
• Which keys are metadata that should never be translated
• How the format's specific pluralization or interpolation rules work

Humlens handles this across 19 supported formats — including JSON, YAML, PO, XLIFF, ARB, and others — importing the file, translating only the translatable content, and exporting back into a file that's structurally identical to the source except for the translated values. Placeholders are detected and preserved automatically rather than relying on a translator to recognize and skip them by hand.

The review step still matters

Even with structure-aware translation, a human review pass catches what automated checks can't: whether a translation actually reads naturally, whether a shortened string for a UI-constrained locale still makes sense, whether a plural form was applied correctly for a language with unfamiliar plural rules. The goal isn't to remove review — it's to make sure review time goes toward those judgment calls instead of toward re-discovering broken JSON.

See supported file formats, or read how text localization works end-to-end.