---
title: "How do I write line breaks and special characters in YAML localization files?"
description: "Use `\\n` in a double-quoted value or a block scalar (`|` keeps line breaks, `>` folds them). Quote values with a space-hash or colon-space sequence, values starting with `*`, `&`, `!`, `%`, `[` or `{`, and `yes`, `no`, `on`, `off` or `null`, which Ruby's YAML 1.1 parser reads as booleans or nil."
category: localization-files
date: 2026-10-09
canonical: https://localizely.com/i18n-questions/localization-files/how-do-i-write-line-breaks-and-special-characters-in-yaml-localization-files/
---

# How do I write line breaks and special characters in YAML localization files?

For a line break, put `\n` in a double-quoted value or use a block scalar. For everything else there is one rule: if a value contains or starts with a character that means something in YAML, quote it.

```yaml
en:
  address: "Line one\nLine two"
  terms: |
    First paragraph.
    Second paragraph.
  intro: >
    A long sentence written on
    several lines that becomes
    one line with spaces.
```

`|` keeps every line break. `>` turns a single line break into a space and keeps an empty line as a paragraph break. Both end with one trailing newline; write `|-` or `>-` to drop it. Only double quotes understand backslash escapes such as `\n`, `\t`, `\"` and `\\`. Single quotes take everything literally, and their only escape is a doubled quote for an apostrophe: `'It''s ready'`. The [YAML 1.2 spec](https://yaml.org/spec/1.2.2/#73-flow-scalar-styles) has the full list of escapes.

Values that must be quoted:

- A `#` preceded by a space starts a comment, so `Item #1 of 3` is stored as `Item`. Write `"Item #1 of 3"`.
- A colon followed by a space inside an unquoted value is read as a nested mapping and fails the parse: `error: Error: file not found` needs quotes.
- A value may not start with an indicator character: `*` (alias), `&` (anchor), `!` (tag), `%` (directive), `[` or `{` (flow collection), `|` or `>` (block scalar), a quote, or `-`, `?` and `:` followed by a space. `@` and the backtick are reserved and cause a parse error at the start of a value. So `*Required field` and `[beta]` go in quotes.
- Ruby's Psych is built on libyaml, which implements YAML 1.1. In that version unquoted `yes`, `no`, `y`, `n`, `on`, `off`, `true` and `false` (in any capitalization) become booleans, and `~`, `null` or an empty value become nil. The classic case is `confirm: Yes` turning into `true`; write `confirm: "Yes"`. Unquoted numbers are converted too, so `"1.10"` as a version label needs quotes or it becomes `1.1`.

When in doubt, double-quote the value. Quoting never changes the meaning of a string; it only removes the ambiguity.

Two Rails details. A `\n` does nothing in HTML; render such a string with [`simple_format`](https://api.rubyonrails.org/classes/ActionView/Helpers/TextHelper.html#method-i-simple_format), which turns single newlines into `<br />` and blank lines into `<p>` tags, or put `<br>` into a key ending in `_html`. And indentation must be spaces, never tabs; a block scalar's lines must be indented deeper than its key.

To check a whole file quickly, paste it into the [YAML validator](/yaml-validator/). The layout of Rails locale files is described at [Rails YAML file](/rails-yaml-file/).

Source: https://localizely.com/i18n-questions/localization-files/how-do-i-write-line-breaks-and-special-characters-in-yaml-localization-files/