To translate JSON, YAML, XML, XLIFF and localization files into any language, the target must preserve both human meaning and machine structure. People searching for JSON translation, YAML translation, XML translation, XLIFF translation, software localization translation or AI translation of localization files need natural target strings without breaking keys, tags, variables, placeholders, plural logic, escapes, encoding, comments, file structure or import and export behaviour.
Word-for-word translation can still damage a localization file because only part of the file is meant to be translated. Keys may be machine identifiers, tags may control markup, placeholders may inject names or numbers at runtime, and plural branches may differ across languages. A fluent target string is unusable if a brace disappears, an XML tag is translated, a YAML indentation level changes, or every plural case is forced into the same English-style singular/plural logic.
This guide develops a practical method for translating JSON, YAML, XML, XLIFF and other localization files without breaking keys, placeholders or plurals. It covers translatable values, keys, attributes, tags, entities, escaping, indentation, encoding, variables, positional placeholders, ICU-style messages, plural categories, select logic, XLIFF units, segmentation, comments, developer notes, AI and machine translation, validation, worked examples, practice and final quality assurance.
The Core Localization-File Principle
Translate only the human-facing message while preserving the machine contract: file syntax → key → translatable value → placeholder → plural/select logic → metadata → validation.
Localization files sit between language and software. The translator must know which parts are linguistic content and which parts are executable or structural. The safest workflow treats machine-facing tokens as protected data and target-language text as the editable layer.
The Ten-Part Translation Method
- 1. Keys and Identifiers: keep machine-facing keys unchanged unless the software explicitly localizes them.
- 2. Translatable Values: identify exactly which string values are user-facing.
- 3. JSON Syntax: preserve braces, commas, quotes and valid escaping.
- 4. YAML Structure: preserve indentation, colons, quoting and scalar style.
- 5. XML Tags and Attributes: keep element names and structural attributes intact.
- 6. XLIFF Units and Segments: preserve translation-unit identity, source/target relationships and metadata.
- 7. Placeholders and Variables: preserve token spelling, count and meaning.
- 8. Plural and Select Logic: respect target-language grammatical categories rather than English-only assumptions.
- 9. Escapes, Entities and Special Characters: preserve runtime-safe encoding while allowing correct target typography.
- 10. Comments, Notes and Non-Production Metadata: keep translator guidance separate from shipped user text.
1. Keys and Identifiers
A common failure point is translating readable keys such as checkout_title or error_message because they look like English. Localization files mix human language with syntax, so the translator must separate those layers before editing.
The mechanism is classifying key and value roles before any language work. This protects the machine contract while giving the target language enough freedom to sound natural.
Worked example: In JSON, “checkout_title”: “Checkout” usually means the key remains checkout_title while only the value is translated. The acceptance test is whether the target both parses successfully and displays the intended meaning in context.
A reliable check is to diff source and target key sets and require an exact match. If parsing, import, placeholder or runtime behaviour differs, the translation has broken the file rather than merely changed its wording.
Key integrity supports APIs, analytics and template systems. The general lesson is that structured translation needs linguistic QA and software QA together.
2. Translatable Values
A common failure point is translating configuration values, codes or enum tokens that are not language. Localization files mix human language with syntax, so the translator must separate those layers before editing.
The mechanism is mapping each value to its runtime use before translating. This protects the machine contract while giving the target language enough freedom to sound natural.
Worked example: A value “USD” may be a currency code rather than text that should become a local word. The acceptance test is whether the target both parses successfully and displays the intended meaning in context.
A reliable check is to preview or trace the value in the product context. If parsing, import, placeholder or runtime behaviour differs, the translation has broken the file rather than merely changed its wording.
Context mapping prevents false localization. The general lesson is that structured translation needs linguistic QA and software QA together.
3. JSON Syntax
A common failure point is introducing smart quotes, missing commas or unescaped characters during editing. Localization files mix human language with syntax, so the translator must separate those layers before editing.
The mechanism is locking syntax and validating after every translation batch. This protects the machine contract while giving the target language enough freedom to sound natural.
Worked example: A translated quote mark inside a JSON string may require escaping; the structural double quotes around the value must remain valid JSON. The acceptance test is whether the target both parses successfully and displays the intended meaning in context.
A reliable check is to parse the target file with a JSON validator. If parsing, import, placeholder or runtime behaviour differs, the translation has broken the file rather than merely changed its wording.
Syntax validation catches failures language review cannot. The general lesson is that structured translation needs linguistic QA and software QA together.
4. YAML Structure
A common failure point is changing indentation or colon placement while wrapping translated text. Localization files mix human language with syntax, so the translator must separate those layers before editing.
The mechanism is treating whitespace and scalar markers as part of the file contract. This protects the machine contract while giving the target language enough freedom to sound natural.
Worked example: A multiline YAML value can break if indentation is reduced by one level. The acceptance test is whether the target both parses successfully and displays the intended meaning in context.
A reliable check is to parse the target and compare object structure with the source. If parsing, import, placeholder or runtime behaviour differs, the translation has broken the file rather than merely changed its wording.
Whitespace discipline matters in configuration-like formats. The general lesson is that structured translation needs linguistic QA and software QA together.
5. XML Tags and Attributes
A common failure point is translating tag names or breaking entity escaping. Localization files mix human language with syntax, so the translator must separate those layers before editing.
The mechanism is separating markup from text nodes and explicitly marked translatable attributes. This protects the machine contract while giving the target language enough freedom to sound natural.
Worked example: may need only Save translated; the button tag remains unchanged. The acceptance test is whether the target both parses successfully and displays the intended meaning in context.
A reliable check is to parse the XML and compare element trees. If parsing, import, placeholder or runtime behaviour differs, the translation has broken the file rather than merely changed its wording.
Markup preservation supports HTML and structured documents. The general lesson is that structured translation needs linguistic QA and software QA together.
6. XLIFF Units and Segments
A common failure point is editing IDs or moving target text outside its unit. Localization files mix human language with syntax, so the translator must separate those layers before editing.
The mechanism is treating unit IDs and segment structure as protected while translating the target payload. This protects the machine contract while giving the target language enough freedom to sound natural.
Worked example: An XLIFF unit can carry context, notes and state used by CAT tools; those relationships should survive. The acceptance test is whether the target both parses successfully and displays the intended meaning in context.
A reliable check is to reimport the target file into the localization tool and inspect unit alignment. If parsing, import, placeholder or runtime behaviour differs, the translation has broken the file rather than merely changed its wording.
Round-trip testing protects translation workflows. The general lesson is that structured translation needs linguistic QA and software QA together.
7. Placeholders and Variables
A common failure point is translating {name}, %s, %(count)d or ${total} as if they were ordinary words. Localization files mix human language with syntax, so the translator must separate those layers before editing.
The mechanism is extracting placeholders before translation and comparing them afterward. This protects the machine contract while giving the target language enough freedom to sound natural.
Worked example: “Hello {name}” may become a different word order, but {name} must still appear exactly once unless the runtime supports another rule. The acceptance test is whether the target both parses successfully and displays the intended meaning in context.
A reliable check is to run a placeholder-set equality check. If parsing, import, placeholder or runtime behaviour differs, the translation has broken the file rather than merely changed its wording.
Token preservation transfers to prompts and notification templates. The general lesson is that structured translation needs linguistic QA and software QA together.
8. Plural and Select Logic
A common failure point is forcing one/other logic onto languages requiring additional plural forms. Localization files mix human language with syntax, so the translator must separate those layers before editing.
The mechanism is separating message logic from wording and using locale-supported plural categories. This protects the machine contract while giving the target language enough freedom to sound natural.
Worked example: Some languages require categories such as few or many; a target cannot simply translate the English singular and plural branches. The acceptance test is whether the target both parses successfully and displays the intended meaning in context.
A reliable check is to test representative numbers for the target locale. If parsing, import, placeholder or runtime behaviour differs, the translation has broken the file rather than merely changed its wording.
Plural-aware design is essential for grammatical localization. The general lesson is that structured translation needs linguistic QA and software QA together.
9. Escapes, Entities and Special Characters
A common failure point is replacing escape sequences or entities with visually similar but structurally unsafe text. Localization files mix human language with syntax, so the translator must separate those layers before editing.
The mechanism is distinguishing displayed character from source representation. This protects the machine contract while giving the target language enough freedom to sound natural.
Worked example: \n may represent a line break and & may represent an ampersand in XML context; they are not casual punctuation. The acceptance test is whether the target both parses successfully and displays the intended meaning in context.
A reliable check is to render and parse the target to verify both display and syntax. If parsing, import, placeholder or runtime behaviour differs, the translation has broken the file rather than merely changed its wording.
Encoding discipline helps web, email and document pipelines. The general lesson is that structured translation needs linguistic QA and software QA together.
10. Comments, Notes and Non-Production Metadata
A common failure point is translating developer comments into production strings or leaking notes into UI. Localization files mix human language with syntax, so the translator must separate those layers before editing.
The mechanism is classifying comments, translator notes and descriptions before sending content to translation. This protects the machine contract while giving the target language enough freedom to sound natural.
Worked example: A note saying “button label, max 15 chars” guides the translator but should not appear to users. The acceptance test is whether the target both parses successfully and displays the intended meaning in context.
A reliable check is to preview production output and search for note leakage. If parsing, import, placeholder or runtime behaviour differs, the translation has broken the file rather than merely changed its wording.
Metadata hygiene protects user experience. The general lesson is that structured translation needs linguistic QA and software QA together.
Worked Example Laboratory
Example 1: JSON Placeholder
{“welcome”:”Hello, {name}!”} The key and placeholder are protected; only the human message changes.
Translate the greeting around {name}, then validate JSON and placeholder count. This preserves both language and executable structure.
Example 2: YAML Multiline Text
help: | followed by several indented lines. Indentation defines one multiline scalar.
Translate line content while preserving the scalar marker and indentation level. This preserves both language and executable structure.
Example 3: XML Inline Markup
Preserve tag names and nesting; translate the visible words. This preserves both language and executable structure.
Example 4: Plural Message
one branch handles one item; other or additional locale branches handle other counts. The grammatical logic may vary by target locale.
Use the target locale’s supported plural categories rather than forcing an English pair. This preserves both language and executable structure.
Example 5: XLIFF Segment
A unit contains source, target, note and identifier. Each part has a workflow role.
Translate the target content, retain IDs and notes, then round-trip through the CAT/localization system. This preserves both language and executable structure.
Plural Rules Are Language Logic
Pluralization is not simply singular versus plural. Localization systems may support locale-specific categories and selection rules. Translators and developers should work from the target locale’s actual grammatical needs rather than copying the source branch count mechanically.
Test real numbers, including zero, one, two, teen values and larger values relevant to the product. The target message must remain grammatical when variables are inserted at runtime.
Placeholders Need Semantic Context
A placeholder can represent a person, count, date, file name, currency or arbitrary string. The target language may need different word order, agreement or case around it. Give translators a sample value and explanation rather than only the token name.
Positional placeholders need special care. If a runtime supports reordering, use the correct positional syntax. If it does not, developers may need to redesign the message instead of forcing unnatural target grammar.
Segmentation and Context
XLIFF and CAT workflows may segment content into units or sentences. Over-segmentation can hide relationships across strings. A label such as “Open” can mean a verb, adjective or status. Context notes, screenshots and neighboring strings help resolve that ambiguity.
Do not merge or split units casually if translation memory, IDs or product code depend on the existing segmentation. Structural changes should be coordinated with the localization pipeline.
Round-Trip Testing
A file that parses locally may still fail import into a translation management or build system. Export the target, import it through the normal pipeline and generate a localized build or preview. This catches encoding, state, placeholder and segmentation problems.
Round-trip testing should include version control diffs. Large unexpected structural diffs often indicate tooling or formatting changes unrelated to translation and should be reviewed before release.
AI and Machine Translation
AI can translate structured files safely only when the prompt makes the protected syntax explicit. Prefer workflows that extract translatable text from the format rather than asking a model to rewrite the whole raw file.
If raw-file translation is unavoidable, ask the model to preserve every key, tag, placeholder, escape and comment marker. Then validate with actual parsers and placeholder checks. A model’s claim that the file is valid is not a substitute for machine validation.
For ICU-style or other message syntax, provide examples of allowed plural/select forms. The translator should change human-facing phrases while preserving selector keywords and variable references required by the runtime.
Practice and Checking
Practice 1: Key Diff
Translate a small JSON resource file. Complete the language pass without altering protected syntax.
Compare source and target key sets and require exact equality. Record failures under key, parser, placeholder, plural, encoding, segmentation or context.
Practice 2: Placeholder Audit
Use strings with named, positional and numeric placeholders. Complete the language pass without altering protected syntax.
Extract placeholder sets before and after translation and compare. Record failures under key, parser, placeholder, plural, encoding, segmentation or context.
Practice 3: Plural Test
Translate a count message for a language with richer plural rules. Complete the language pass without altering protected syntax.
Render representative numbers and inspect grammar. Record failures under key, parser, placeholder, plural, encoding, segmentation or context.
Practice 4: YAML Parse Test
Translate multiline YAML strings. Complete the language pass without altering protected syntax.
Run a parser and compare resulting data structure. Record failures under key, parser, placeholder, plural, encoding, segmentation or context.
Practice 5: XML Tree Test
Translate text containing inline tags and entities. Complete the language pass without altering protected syntax.
Parse source and target and compare tree structure. Record failures under key, parser, placeholder, plural, encoding, segmentation or context.
Practice 6: XLIFF Round Trip
Translate a small XLIFF file in the normal localization workflow. Complete the language pass without altering protected syntax.
Export, reimport and verify IDs, notes, states and target text. Record failures under key, parser, placeholder, plural, encoding, segmentation or context.
Independent-Use Workflow
- Identify the file format and parser or localization system that consumes it.
- Separate translatable text from keys, tags, IDs, comments and configuration values.
- Extract and protect every placeholder and variable.
- Translate complete messages with runtime context.
- Apply target-locale plural and select logic where supported.
- Preserve escapes, entities, indentation and encoding requirements.
- Validate JSON, YAML or XML syntax with a real parser.
- Run placeholder and key-set equality checks.
- Round-trip XLIFF and similar resources through the normal pipeline.
- Preview the localized build and test representative runtime values.
Useful Internal Routing
For general translation reasoning, use The Universal Five-Layer Translation Method. For AI prompt templates and protected variables, use How to Translate AI Prompts, System Instructions and Prompt Templates Without Changing Constraints or Intent.
For website and app context, use How to Translate Websites, Apps and Interface Text Without Breaking Meaning or User Experience. For final QA, use How to Check Translation Accuracy Before You Send, Submit or Publish.
Frequently Asked Questions
Should JSON keys be translated?
Usually no if software expects exact keys. Translate human-facing values and preserve machine-facing identifiers unless the system explicitly localizes them.
Can AI translate YAML or XML files directly?
It can assist, but raw-file translation is risky. Extract translatable text where possible, then validate the final file with actual parsers.
What is the biggest placeholder risk?
Deleting, duplicating, translating or changing a token so runtime substitution fails or inserts the wrong value.
Why are plurals difficult?
Languages differ in the number and meaning of grammatical plural categories. English-style singular/other logic is not universal.
Should XLIFF IDs be changed?
Normally no. IDs, unit relationships and workflow metadata should remain stable unless the localization system explicitly requires a change.
What about comments and translator notes?
Keep them separate from production text. They provide context but should not leak into the user interface.
How do I check a translated localization file?
Parse it, compare keys and placeholders, test plural/select logic, round-trip through the pipeline and preview the localized product.
What is the best final test?
A valid target file should import cleanly, preserve machine structure, render natural target strings and behave correctly with representative runtime values.
The Rule to Keep
Structured localization translation is successful when the software still understands the file and the user understands the message. Keys, tags, placeholders, plural logic and encoding must survive while the target language becomes natural.
Translate the string, preserve the contract.
Deep Practice: Validate Structure and Runtime Together
Take a translated resource file and run four independent checks: parse the file, compare key sets, compare placeholder sets, and render sample messages with real values. A file can pass three checks and still fail the fourth, which is why structural and linguistic validation need to be separate.
Then review the version-control diff. The ideal localization diff should concentrate on translatable values and intentional plural or locale changes. Unexpected changes to keys, indentation, IDs, tags or metadata deserve investigation before release.
Deep Practice: Validate Structure and Runtime Together
Take a translated resource file and run four independent checks: parse the file, compare key sets, compare placeholder sets, and render sample messages with real values. A file can pass three checks and still fail the fourth, which is why structural and linguistic validation need to be separate.
Then review the version-control diff. The ideal localization diff should concentrate on translatable values and intentional plural or locale changes. Unexpected changes to keys, indentation, IDs, tags or metadata deserve investigation before release.
Deep Practice: Validate Structure and Runtime Together
Take a translated resource file and run four independent checks: parse the file, compare key sets, compare placeholder sets, and render sample messages with real values. A file can pass three checks and still fail the fourth, which is why structural and linguistic validation need to be separate.
Then review the version-control diff. The ideal localization diff should concentrate on translatable values and intentional plural or locale changes. Unexpected changes to keys, indentation, IDs, tags or metadata deserve investigation before release.
Deep Practice: Validate Structure and Runtime Together
Take a translated resource file and run four independent checks: parse the file, compare key sets, compare placeholder sets, and render sample messages with real values. A file can pass three checks and still fail the fourth, which is why structural and linguistic validation need to be separate.
Then review the version-control diff. The ideal localization diff should concentrate on translatable values and intentional plural or locale changes. Unexpected changes to keys, indentation, IDs, tags or metadata deserve investigation before release.
Deep Practice: Validate Structure and Runtime Together
Take a translated resource file and run four independent checks: parse the file, compare key sets, compare placeholder sets, and render sample messages with real values. A file can pass three checks and still fail the fourth, which is why structural and linguistic validation need to be separate.
Then review the version-control diff. The ideal localization diff should concentrate on translatable values and intentional plural or locale changes. Unexpected changes to keys, indentation, IDs, tags or metadata deserve investigation before release.
Deep Practice: Validate Structure and Runtime Together
Take a translated resource file and run four independent checks: parse the file, compare key sets, compare placeholder sets, and render sample messages with real values. A file can pass three checks and still fail the fourth, which is why structural and linguistic validation need to be separate.
Then review the version-control diff. The ideal localization diff should concentrate on translatable values and intentional plural or locale changes. Unexpected changes to keys, indentation, IDs, tags or metadata deserve investigation before release.
Deep Practice: Validate Structure and Runtime Together
Take a translated resource file and run four independent checks: parse the file, compare key sets, compare placeholder sets, and render sample messages with real values. A file can pass three checks and still fail the fourth, which is why structural and linguistic validation need to be separate.
Then review the version-control diff. The ideal localization diff should concentrate on translatable values and intentional plural or locale changes. Unexpected changes to keys, indentation, IDs, tags or metadata deserve investigation before release.
Deep Practice: Validate Structure and Runtime Together
Take a translated resource file and run four independent checks: parse the file, compare key sets, compare placeholder sets, and render sample messages with real values. A file can pass three checks and still fail the fourth, which is why structural and linguistic validation need to be separate.
Then review the version-control diff. The ideal localization diff should concentrate on translatable values and intentional plural or locale changes. Unexpected changes to keys, indentation, IDs, tags or metadata deserve investigation before release.
Deep Practice: Validate Structure and Runtime Together
Take a translated resource file and run four independent checks: parse the file, compare key sets, compare placeholder sets, and render sample messages with real values. A file can pass three checks and still fail the fourth, which is why structural and linguistic validation need to be separate.
Then review the version-control diff. The ideal localization diff should concentrate on translatable values and intentional plural or locale changes. Unexpected changes to keys, indentation, IDs, tags or metadata deserve investigation before release.
Deep Practice: Validate Structure and Runtime Together
Take a translated resource file and run four independent checks: parse the file, compare key sets, compare placeholder sets, and render sample messages with real values. A file can pass three checks and still fail the fourth, which is why structural and linguistic validation need to be separate.
Then review the version-control diff. The ideal localization diff should concentrate on translatable values and intentional plural or locale changes. Unexpected changes to keys, indentation, IDs, tags or metadata deserve investigation before release.
Deep Practice: Validate Structure and Runtime Together
Take a translated resource file and run four independent checks: parse the file, compare key sets, compare placeholder sets, and render sample messages with real values. A file can pass three checks and still fail the fourth, which is why structural and linguistic validation need to be separate.
Then review the version-control diff. The ideal localization diff should concentrate on translatable values and intentional plural or locale changes. Unexpected changes to keys, indentation, IDs, tags or metadata deserve investigation before release.
Deep Practice: Validate Structure and Runtime Together
Take a translated resource file and run four independent checks: parse the file, compare key sets, compare placeholder sets, and render sample messages with real values. A file can pass three checks and still fail the fourth, which is why structural and linguistic validation need to be separate.
Then review the version-control diff. The ideal localization diff should concentrate on translatable values and intentional plural or locale changes. Unexpected changes to keys, indentation, IDs, tags or metadata deserve investigation before release.
Deep Practice: Validate Structure and Runtime Together
Take a translated resource file and run four independent checks: parse the file, compare key sets, compare placeholder sets, and render sample messages with real values. A file can pass three checks and still fail the fourth, which is why structural and linguistic validation need to be separate.
Then review the version-control diff. The ideal localization diff should concentrate on translatable values and intentional plural or locale changes. Unexpected changes to keys, indentation, IDs, tags or metadata deserve investigation before release.
Deep Practice: Validate Structure and Runtime Together
Take a translated resource file and run four independent checks: parse the file, compare key sets, compare placeholder sets, and render sample messages with real values. A file can pass three checks and still fail the fourth, which is why structural and linguistic validation need to be separate.
Then review the version-control diff. The ideal localization diff should concentrate on translatable values and intentional plural or locale changes. Unexpected changes to keys, indentation, IDs, tags or metadata deserve investigation before release.
Deep Practice: Validate Structure and Runtime Together
Take a translated resource file and run four independent checks: parse the file, compare key sets, compare placeholder sets, and render sample messages with real values. A file can pass three checks and still fail the fourth, which is why structural and linguistic validation need to be separate.
Then review the version-control diff. The ideal localization diff should concentrate on translatable values and intentional plural or locale changes. Unexpected changes to keys, indentation, IDs, tags or metadata deserve investigation before release.
Deep Practice: Validate Structure and Runtime Together
Take a translated resource file and run four independent checks: parse the file, compare key sets, compare placeholder sets, and render sample messages with real values. A file can pass three checks and still fail the fourth, which is why structural and linguistic validation need to be separate.
Then review the version-control diff. The ideal localization diff should concentrate on translatable values and intentional plural or locale changes. Unexpected changes to keys, indentation, IDs, tags or metadata deserve investigation before release.
Deep Practice: Validate Structure and Runtime Together
Take a translated resource file and run four independent checks: parse the file, compare key sets, compare placeholder sets, and render sample messages with real values. A file can pass three checks and still fail the fourth, which is why structural and linguistic validation need to be separate.
Then review the version-control diff. The ideal localization diff should concentrate on translatable values and intentional plural or locale changes. Unexpected changes to keys, indentation, IDs, tags or metadata deserve investigation before release.
Deep Practice: Validate Structure and Runtime Together
Take a translated resource file and run four independent checks: parse the file, compare key sets, compare placeholder sets, and render sample messages with real values. A file can pass three checks and still fail the fourth, which is why structural and linguistic validation need to be separate.
Then review the version-control diff. The ideal localization diff should concentrate on translatable values and intentional plural or locale changes. Unexpected changes to keys, indentation, IDs, tags or metadata deserve investigation before release.