YAML

Translate nested YAML string values without changing catalog keys, and choose a different handler when the root or schema carries special meaning.

The yaml file handler translates string values in nested mappings and sequences. It keeps the keys that application code uses for lookup, along with numbers and booleans. Use it for a catalog whose structure stays the same across locales.

Decide whether generic YAML fits #

For example, this catalog groups checkout messages without a locale wrapper:

yaml
checkout:
  title: Complete your order
  steps:
    - Review your items
    - Confirm delivery
  retries: 3

The handler selects checkout.title and both sequence strings. retries stays numeric. A quoted identifier would also be selected because it is a string. Keep that distinction in mind when choosing which data belongs in the catalog.

Use Locale-root YAML for a Rails-style en: wrapper that must become the target locale. Generic YAML retains en:, even when the filename changes to es.yml. Rails can then ignore the content because its root still names English.

Use OpenAPI for an API specification. Generic YAML would also select string-valued operation identifiers, references, and examples. A .yml extension cannot distinguish these intentions.

Reuse and reconstruction #

The current source defines the output tree. A previous source establishes whether each string path changed, and the existing target supplies values at matching paths. New translations replace changed strings; unchanged strings can retain their existing translations even when selected by key or term scope.

The CLI supplies its saved baseline for --key, so that selection does not reliably regenerate unchanged YAML wording. Adding --force to the same command does not change this. Edit the target directly for an exact correction, or save accepted targets and use a scoped whole-file --force without --key for regeneration. Review the whole file after replacement.

Reconstruction uses a YAML syntax tree to retain comments and anchor structure while replacing values. Serialization can normalize formatting. Comments remain document material rather than translator instructions. Check aliases with your YAML consumer, particularly when one value appears through several references.

A key-scoped run can drop an unresolved out-of-scope mapping string when no target value exists. Sequence strings retain their source value to avoid shifting positions. Partial scope therefore does not prove that every string in the file is translated.

Configure and load the catalog #

Set format: "yaml" explicitly for .yaml or .yml sources in CLI configuration. Push discovery excludes YAML files without an explicit format. The GitHub App has its own repository selection.

Match the target path to the application's loader. A source such as config/locales/checkout.en.yml and one at locales/en/checkout.yml need different path derivation. Sequence positions also identify messages: moving a sequence item can change which existing translation matches it. Inspect the loaded catalog after structural edits. For Rails lookup, locale selection, and fallback, use Localize a Rails app with the locale-root handler.