Lesson 4.1: Structured Data Formats (JSON, YAML & XML)

1. Human Impact & Context

Imagine a localization team delivering 20 localized language files for a mobile banking application or game release. The build pipeline runs automatically at midnight—and fails completely. The culprit isn't a bad translation or a missing word; it's a single unescaped quotation mark inside a German JSON file or a stray space indent in a YAML configuration asset.

When translators work directly within raw code data formats without proper file filtering or schema validation, syntax errors inevitably corrupt the codebase:

• JSON (JavaScript Object Notation): A missing comma or an unescaped inner double quote ("btn_text": "Click "Here"") breaks the parser, throwing a SyntaxError: Unexpected token that crashes the application startup script.

• YAML (YAML Ain't Markup Language): YAML relies on strict white-space indentation instead of braces. If a translator uses tab characters or shifts indentation by one space, the parser misinterprets the entire data hierarchy or rejects the file outright.

• XML (Extensible Markup Language): Unescaped ampersands (&) or missing closing tags (</string>) render Android or iOS string resource files invalid.

As a localization engineer, you must ensure that human translators never break software data structures, and that source assets strictly conform to parser rules before and after translation.

2. Core Mechanics & Technical Concepts

Syntax Rules & Escaping Traps across Primary Data Formats

                     ┌─────────────────────────────────────────┐
                     │     Structured Data Syntax Rules        │
                     └────────────────────┬────────────────────┘
                                          │
        ┌─────────────────────────────────┼─────────────────────────────────┐
        ▼                                 ▼                                 ▼
┌───────────────┐                 ┌───────────────┐                 ┌───────────────┐
│     JSON      │                 │     YAML      │                 │      XML      │
└───────┬───────┘                 └───────┬───────┘                 └───────┬───────┘
        │                                 │                                 │
        ▼                                 ▼                                 ▼
 Strict Double Quotes             Indent-Sensitive (Spaces)         Predefined Entity Escaping
Keys & string values must use     Uses exact space counts (2 or 4). Reserved characters (&, <, >)
double quotes. Inner quotes must  Tabs are strictly illegal in YAML   must be escaped as entity
be escaped as \".                 data blocks.                      refs (&amp;, &lt;, &gt;).

1. JSON (Strict Escaping & Formatting)

• Rule: Keys and string values must use double quotes ("). Single quotes (') are illegal in standard JSON.

• Escaping: Inner double quotes inside a string value must be escaped with a backslash (\").

  • Bad: "msg": "Press "Submit" to continue"

  • Good: "msg": "Press \"Submit\" to continue"

• Trailing Commas: Commas are required between key-value pairs, but trailing commas after the final key in an object are illegal in standard JSON.

2. YAML (Indentation & String Boundaries)

• Rule: Indentation represents hierarchy. Tabs are strictly forbidden—only spaces are allowed (typically 2 or 4 spaces per indentation level).

• Multiline Strings: Block scalars (| for literal newlines, > for folded text) dictate how multiline UI or dialogue strings are parsed:

  YAML

  # Literal block scalar (preserves exact line breaks)
  dialogue_block: |
    Line one of NPC dialogue.
    Line two of NPC dialogue.
  

3. XML (Entity Escaping & Tag Balancing)

• Rule: All tags must be balanced and correctly nested (<string name="title">Text</string>).

• Entity Escaping: Five core characters must be escaped as XML entity references:

  • & &

  • < &lt;

  • > >

  • " "

  • ' '

3. Real-World Industry Application

4. Cross-Platform Execution (Validating Formats in VS Code)

In Visual Studio Code, you can instantly catch and resolve structural syntax errors before assets enter the build pipeline:

1. Verify Language Mode: Ensure the status bar displays JSON, YAML, or XML mode for the active file.

2. Problems Panel (Cmd + Shift + M / Ctrl + Shift + M): Open the Problems panel to inspect real-time linter diagnostics, pointing to exact line and column numbers where syntax is broken.

3. Format Document (Option + Shift + F / Alt + Shift + F): Instantly format JSON or XML documents to enforce valid indentation and detect missing braces/tags.

5. Next Steps & Lab Practice

Now that you understand the syntax requirements, boundary escaping, and indentation rules of JSON, YAML, and XML, you are ready to troubleshoot broken structured data assets.

Proceed to 🛠️ Hands-On Lab 4.1: Structured Data Parsing & Filter Configuration, or create a quick knowledge check!