How to Translate YAML Files Without Breaking the Build

Quick answer — YAML translation is a question of scope, not language. Keys, anchors and references are structure that must stay in English; only the string values a user will read should change, and indentation has to survive exactly.

Keys are code, values are content

A YAML localization file is a tree of keys pointing at strings. The key checkout.button.submit is an identifier the application looks up. The string it points at is what a person reads.

Translate the key and the lookup fails. That is the single rule, and almost every YAML translation problem is a violation of it.

Indentation is syntax

YAML has no braces. Structure is expressed purely through indentation, so a translated file that has picked up a stray space at the start of a line is a different structure, or invalid. This is why round-tripping YAML through a text translator so often produces a file that will not parse. The tool has no reason to know the leading whitespace is load-bearing.

Placeholders inside strings

Values commonly contain interpolation: Hello, %{name} or {{count}} items. Those tokens must come through untouched, and their position may need to move for the target language's word order while the token itself stays identical.

A translation that renders %{name} as %{nombre} produces a runtime error or a literal placeholder shown to a user.

Plurals are not one string

Many YAML localization formats express plural forms as a nested set — one, other, and in some languages few, many, zero. English needs two forms. Arabic needs six. A translation process that maps one English string to one target string cannot represent that, so the file has to be able to grow forms that the source does not have.

Anchors and references

&anchor and *reference let a value be defined once and reused. Translating the anchor name breaks every reference to it; translating the value once correctly updates everywhere it is used, which is the behaviour you want.

Why memory matters in config

Application strings change constantly and mostly in small increments. A release adds nine strings and edits two out of four thousand.

translation memory means only those eleven reach a model, and the rest return their approved renderings unchanged — which is also what keeps terminology stable across releases rather than drifting each time somebody re-translates a file.

The route through

Upload or connect the file, set key and value scope, protect placeholders, choose languages, review.

document translation preserves the structure and quality control catches placeholder damage before it ships.

Format details and limits are on the YAML translation integration page.

Multi-line strings have three syntaxes

YAML expresses long values as a literal block with a pipe, a folded block with a right angle bracket, or a plain quoted string. The three preserve line breaks differently.

A translation that turns a folded block into a literal one changes how the text renders everywhere it is used. That is a formatting bug with no error message and no obvious cause, which makes it expensive to find later.

Comments carry instructions

Lines beginning with a hash are frequently the only guidance a translator gets: a note that a string appears on a button, or a maximum length. They are not rendered anywhere, so they are easy to strip.

Keep them. A comment saying "max 20 characters" prevents a class of layout bug that no amount of later review will catch reliably.

Where to start

Run one file and diff it against the source. If the key tree is identical and only the values changed, the pipeline is set up correctly.

FAQ

What should be translated in a YAML file? Only the string values a user will read. Keys, anchors and references are identifiers the application looks up, so translating them breaks the lookup and usually the build.

Why does a translated YAML file fail to parse? Usually indentation. YAML expresses structure entirely through leading whitespace, so a stray space introduced during round-tripping produces either a different structure or an invalid file.

How are placeholders handled? They must come through untouched. Tokens like %{name} or {{count}} can move position for the target language's word order, but translating the token itself causes a runtime error or shows the placeholder to a user.

How are plurals represented? As a nested set of forms. English needs two and Arabic needs six, so the target file has to be able to grow plural forms the English source does not have.