# Message format

Source: https://verbaly.dev/docs/guide/format

One small syntax, powered by native `Intl` underneath: plurals, gender and formatting without learning full ICU.

## Interpolation

```
"Hola {name}"          → t('saludo', { name: 'Aron' })
```

Values format themselves by type: numbers via `Intl.NumberFormat`, dates via `Intl.DateTimeFormat`, strings as-is. A number reads the way the language writes it, so `2026` comes out as `2,026` in English: pass `String(year)` when the value is a label, like the year in a copyright line, and not a quantity. A missing param shows the placeholder literally and warns once naming the message, so it’s easy to spot and never a crash.

## Formatters

Append `:formatter` (with optional `/arg`) to a param:

| Syntax | Result |
| --- | --- |
| {n:number} | Number as the language writes it: `1,234.56` / `1234,56` |
| {n:integer} | Rounded, no decimals |
| {n:percent} | `0.5` → `50%` |
| {n:currency/EUR} | Currency with ISO code |
| {d:date/long} | `dateStyle`: short · medium · long · full |
| {d:time/short} | `timeStyle` variants |

Custom formatters plug in at instance creation. The full signature is `(value, locale, arg?) => string`, where `locale` is the active language and `arg` is whatever follows the `/` in the placeholder:

```
createVerbaly({
  formatters: { upper: (v) => String(v).toUpperCase() },
});
// "{word:upper}" → HOLA
```

## Relative time, lists & units

The format surface covers the rest of modern `Intl`, still with zero dependencies:

```
"Updated {when:relative}"       → Updated 2 hours ago · yesterday
"Ready {n:relative/day}"        → Ready in 3 days
"Works in {langs:list}"         → Works in English, Spanish, and Portuguese
"Pick {opts:list/or}"           → Pick red, green, or blue
"{d:unit/kilometer}"            → 3 km
```

- `relative`: pass a `Date` and the unit picks itself against now (`Intl.RelativeTimeFormat` with `numeric: 'auto'`, so you get *yesterday*, not *1 day ago*); pass a number with an explicit unit (`relative/hour`).
- `list`: arrays localize via `Intl.ListFormat`, conjunction by default, `/or` for disjunction, `/unit` for unit lists. Each item formats itself for the language.
- `unit`: any CLDR unit id (`kilometer`, `megabyte`, `liter`…) through `Intl.NumberFormat`.
- Bad data never crashes a render, and never slips by either. An unknown format, an invalid unit, a placeholder missing its argument, a list that is not a list: each one **warns once**, naming the message, and falls back to `String(value)`.

## Plurals and selects: one syntax

```
"{count | =0: sin mensajes | one: un mensaje | other: # mensajes}"
"{gender | male: él | female: ella | other: elle}"
```

- Numbers match `=N` exact values first, then `Intl.PluralRules` categories (`zero one two few many other`).
- Strings match their variant key, falling back to `other`.
- `#` renders the number, formatted for the language. Variants nest placeholders and blocks freely, and two blocks that end together close with `}}`.
- **Always include `other` in a plural block.** It is the catch-all, so a block without it renders nothing for any count it does not list. `verbaly check` fails on that, and also warns when a language needs forms your message lacks: Polish reaches `few` and `many` where English only needs `one` and `other`. If a catalog reaches your app without passing through the build, from a lazy loader or a CMS, the runtime warns in the console naming the message instead of rendering an empty string quietly. A gender or role block is different: leaving `other` out there is your choice, and Verbaly leaves it alone.

In the text you write in code, a block takes its value from `${…}`, right after its opening brace. The compiler turns it into the same message a catalog holds:

```
t`Tienes {${count} | one: # mensaje | other: # mensajes}`;
t`{${role} | admin: Administra el equipo | other: Ve el equipo}`;
t`Total: {${total}:currency/EUR}`;

// locales/es.json
"NASxvaOz": "Tienes {count | one: # mensaje | other: # mensajes}"
```

> **Writing a block in code**
>
> The format name goes right after the colon, with no space. Inside the block the syntax is the one above: `#` is the number and the escapes are the same. A block written around a bare name, like `{count | …}`, stays text, and `verbaly extract` shows the spelling that works.

## If you need ICU

Have existing ICU MessageFormat strings, or need its exact syntax? Write ICU and Verbaly detects it automatically and parses it into the same engine, with **zero extra dependencies**.

```
"{count, plural, one {# item} other {# items}}"
"{gender, select, male {he} female {she} other {they}}"
"{n, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}"
```

- Auto-detected per message: no config, no marker. Native and ICU messages coexist in the same catalog.
- Supports `plural`, `select`, `selectordinal` (real ordinal rules), `{n, number/date/time, style}`, `#`, `=N`, nesting and `'…'` quoting.
- **Checked like any other message.** A translation that flattened an ICU plural into plain text, or dropped a parameter from it, fails `verbaly check` exactly like a native one does. The same guard runs on what a machine translation returns and on what you import.
- Prefer the native syntax by default; reach for ICU only when you need it.
- ICU is read from your catalogs. Written inside `t``…` it stays text, and `verbaly extract` names the native block to write there instead.
- **You only pay for it if you use it.** Verbaly reads your catalogs at build time, and the ICU parser goes into your app only when one of your messages needs it. That is about 544 bytes, and there is nothing to switch on. Relative time works the same way: another 318 bytes that only travel when a message asks for them.

> **Messages that arrive after the build**
>
> Your catalogs are what Verbaly reads, so a message that reaches the app later, from a CMS or a fetched catalog, is the one case it cannot see coming. If those messages may use ICU or relative time, set `icu: true` or `relative: true` in your config. Without that, such a message shows its own source text or the raw value and says what is missing in the console, rather than half-rendering into something that looks almost right.

## Escapes

| Write | Get |
| --- | --- |
| {{ | Literal `{` |
| }} | Literal `}`, unless it closes two blocks at once |
| \|\| | Literal `\|` inside variants |
| ## | Literal `#` inside variants |

In a catalog, a literal `{` or `}` is always written doubled. Text written in your code gets that for free, because `extract` doubles them for you; a catalog written by hand has to do it itself, translations included.

A literal brace can sit right after a value: `` t`Selected {${count}}` `` shows "Selected {5}", and so does a price followed by `}`. Right after a block with variants, put a space before it: inside a block `}}` is an escape.

In rich messages (`data-verbaly-rich` or `<Trans>`) the numeric entity `&#123;` also shows a literal brace: it decodes after parsing, so it never touches the placeholder syntax.

> **Params are typed from the message**
>
> `{count | one: … | other: …}` infers `count: number`; selects infer `string`; `currency` infers `number`. Both the editor and CI catch a missing or misnamed param.
