Skip to content

Guides

Message 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:

SyntaxResult
{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

Plurals and selects: one syntax

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

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}"

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}}"

Escapes

WriteGet
{{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.

↑↓to moveEnterto open
Copied to clipboard