DocuAlign
Translate YAML files without breaking indentation

YAML is indentation-sensitive, so translation errors can become parsing errors. The safest workflow separates translatable values from keys and structure.

Follow the workflow below, then use the matching DocuAlign tool to keep structure visible while you review.

Open matching translatorBrowse guides

How to Translate YAML Files Without Breaking Indentation

Translate YAML and YML files safely by preserving keys, indentation, nesting, and configuration-like structure.

Step-by-step workflow

  1. 01Confirm whether the YAML file is a localization file, config-like content, or documentation source.
  2. 02Protect keys and indentation before translating values.
  3. 03Keep nested paths visible so reviewers know where each string appears.
  4. 04Export the translated YAML without changing whitespace-sensitive structure.
  5. 05Run the translated file through the app or parser before publishing.

What to protect during translation

  • Indentation, nested paths, anchors, aliases, and list markers.
  • Application keys, config keys, route names, and machine-readable values.
  • Quotes around strings that contain punctuation, colons, braces, or leading zeros.

Pre-export checks

  • Load the translated YAML with the same parser used by the app.
  • Compare nested key paths against the source file.
  • Review quoted strings and multiline blocks for accidental formatting changes.

Common mistakes to avoid

  • AvoidChanging indentation while editing translated values.
  • AvoidTranslating keys that the application expects to remain stable.
  • AvoidRemoving quotes around strings that need quoting in YAML.
FAQ

Questions about this workflow

Why is YAML translation fragile?

YAML uses indentation to express structure, so whitespace changes can alter or break the file.

Can YAML keys be translated?

Usually no. In app localization files, keys should remain stable and only values should be translated.

How do I check translated YAML?

Load it with your parser or app and inspect nested strings in context.