YAML Translation Files (.yml, .yaml)

Format, editor, and workflow for the human-readable translation format used by Rails, Symfony, Hugo, and Jekyll.

YAML is a human-readable, indentation-based text format that has become the default translation format for several major frameworks — most notably Ruby on Rails (i18n gem), Symfony, Hugo, and Jekyll. A YAML translation file groups keys under a top-level locale code and uses nesting to organize them, so the file reads almost like plain English. It supports comments (which JSON does not), multi-line strings, and references — making it pleasant for translators to read directly. The trade-off: YAML is indentation-sensitive, so a single misaligned space breaks parsing.

Key facts

What it is: human-readable, indentation-based translation file
File extensions: .yml or .yaml
Encoding: UTF-8
Supports comments: yes (lines starting with #)
Plurals: framework-defined (Rails uses CLDR keys; Symfony uses intervals)
Used by: Ruby on Rails, Symfony, Hugo, Jekyll, Drupal config, many Rust / Go / Python projects

What a YAML translation file looks like

A typical YAML translation file (Rails-style) starts with a locale code at the top level and nests translation keys underneath. Plurals use CLDR keys (one,other, etc.) as nested children, and placeholders are framework-specific — Rails uses %{name}, Symfony uses {name}:

de:
  greeting: "Hallo, %{name}!"
  cart:
    item:
      one: "1 Artikel in Ihrem Warenkorb"
      other: "%{count} Artikel in Ihrem Warenkorb"
  errors:
    not_found: "Seite nicht gefunden"
    forbidden: "Zugriff verweigert"
  # Reviewed by translator on 2026-04-12
  legal:
    terms: "Nutzungsbedingungen"
    privacy: "Datenschutzerklärung"

Editing YAML translation files

Code editors (VS Code, Sublime Text, IntelliJ): YAML syntax highlighting and formatters catch most indentation errors. Use yamllint or your editor\'s built-in validator after every edit.
Cloud TMS platforms (Locize, Phrase, Crowdin, Weblate): import YAML, edit in a CAT-style UI, export back to YAML — translators never have to read YAML syntax.
Spreadsheet workflows: some teams export YAML to CSV / XLSX for translator handoff, then import back. Most TMS platforms handle the round-trip automatically.

Common YAML translation workflows

Rails apps. The default — Rails ships a config/locales/ folder with one .yml per locale. Add de.yml, copy the en.yml structure, translate the values.
Symfony. Translation files live under translations/, named like messages.de.yaml. Symfony picks them up automatically.
Hugo / Jekyll static sites. Locale strings live in i18n/de.yml (Hugo) or _data/de.yml (Jekyll). Templates reference them with {{ T "key" }} or similar.
Translator handoff. Export YAML to a TMS or to CSV/XLSX, translate, import back. Locize keeps the YAML structure intact on round-trip.

How to edit YAML translation files in Locize

Locize imports and exports YAML for round-tripping translations between your Rails / Symfony / Hugo project and the CAT view:

Get started
Import your .yml or .yaml file
Edit translations in the CAT view with translation memory, glossary, and style guide applied automatically
Use bulk actions for AI / machine translation, then route results through a review workflow
Export back to YAML — or convert to JSON, gettext, XLIFF, or any other supported format

Frequently asked questions

What is a YAML translation file?

A YAML translation file (.yml or .yaml) is a human-readable text file that maps translation keys to translated strings using indentation-based syntax. It is the standard format in Ruby on Rails (i18n gem), Symfony, Hugo, Jekyll, and many static-site generators. Compared to JSON, YAML is more compact, supports comments, and is easier for translators to read directly — at the cost of being indentation-sensitive.

YAML vs JSON for translations: which is better?

YAML is more human-readable and supports comments, which helps translators. JSON is stricter and avoids the indentation-sensitivity that makes YAML easy to break. For developer-driven workflows JSON is often safer; for translator-friendly handoff YAML is more pleasant. Tools like Locize support both — pick the one your stack expects (Rails / Symfony / Hugo: YAML; React / next-i18next / Vue: JSON).

How do I edit YAML translation files?

Any text editor with YAML syntax highlighting (VS Code, Sublime, IntelliJ) opens YAML translation files. Validate after editing to avoid indentation errors. For team workflows, use a translation management system that imports YAML — Locize, Phrase, Crowdin, Weblate — to edit translations in a CAT-style UI without exposing translators to YAML syntax directly.

How does YAML handle plurals?

It depends on the framework. Rails i18n uses CLDR plural keys (`one`, `other`, `few`, `many`, etc.) under each translation key. Symfony uses interval-based pluralization syntax. The YAML format itself does not enforce a plural convention — your i18n library does. Locize preserves whichever convention your file uses on import and export.

Why does my YAML translation break?

Almost always indentation. YAML uses spaces (not tabs) for nesting, and a single misaligned space breaks parsing. Other common causes: unquoted strings starting with `:` or `-`, special characters that need quoting, and using a tab anywhere. Run `yamllint` or your editor's YAML validator after every edit.

Which frameworks use YAML for translations?

Ruby on Rails (i18n gem, default format), Symfony (translation YAML files), Hugo (i18n folder), Jekyll (data files), Drupal (config translations), and many Rust, Go, and Python projects that prefer YAML over JSON. Most static-site generators default to YAML for i18n content.

Translate YAML without breaking indentation.

Import, edit with translation memory, glossary and AI, review, and export — all in one place.

Start free trial