Formats

Messagevisor locale formats are named preset collections for Intl-style formatting. They give Product Managers, translators, and engineers a shared vocabulary for number, currency, date, time, relative time, and date-time-range output.

Messagevisor intentionally supports a documented subset of the JavaScript Intl APIs:

• formats.number uses Intl.NumberFormat
• formats.date uses Intl.DateTimeFormat
• formats.time uses Intl.DateTimeFormat
• formats.dateTimeRange uses Intl.DateTimeFormat.formatRange
• formats.relative uses Intl.RelativeTimeFormat

The rendered examples on this page were verified with the JavaScript runtime using en-US. Exact punctuation, spaces, calendar names, compact labels, unit labels, and time zone labels can vary slightly across runtimes and ICU data versions, but the configuration patterns are the same.

Cross-SDK consistency#

Messagevisor treats JavaScript Intl as the reference for the portable formatter contract. Java and Swift SDKs map the same format presets to ICU4J and Foundation APIs rather than rewriting strings by hand.

Formatter behavior falls into three profiles:

SDKs must not add locale-specific or time-zone-specific string hacks to force a fixture to pass. If a platform formats Bengali digits, Dutch unit names, or a time-zone label differently, Messagevisor records that as an explicit runtime expectation unless the difference can be solved by passing better standard options to the platform formatter.

Where formats live#

Formats are authored in locale files:

description: English base
formats:
  number:
    money:
      style: currency
      currency: USD
      currencyDisplay: symbol
  date:
    long:
      year: numeric
      month: long
      day: numeric
  time:
    short:
      hour: numeric
      minute: 2-digit

Targets can override locale formats per locale. See Targets.

Locales can inherit formats from other locales with inheritFormatsFrom. See Inheritance for the full workflow and prune --formats cleanup.

Quick selection guide#

Allowed combinations#

These rules mirror the supported Intl subset and help avoid presets that JavaScript runtimes reject:

• Currency fields (currency, currencyDisplay, currencySign) require style: currency.
• Unit fields (unit, unitDisplay) require style: unit.
• compactDisplay only applies when notation: compact.
• dateStyle and timeStyle cannot be mixed with granular fields such as year, month, day, hour, minute, or timeZoneName in the same date/time preset.
• dateStyle belongs to date and date-time-range presets. timeStyle belongs to time and date-time-range presets.
• currency and timeZone can be supplied per call in the SDK. Per-call values win over preset values, instance defaults, and SDK fallbacks.

Number formats#

Number presets are passed to Intl.NumberFormat.

formats:
  number:
    decimal:
      maximumFractionDigits: 2
    fixed2:
      minimumFractionDigits: 2
      maximumFractionDigits: 2
    compactShort:
      notation: compact
      compactDisplay: short
    signAlways:
      signDisplay: always
      maximumFractionDigits: 0

Number options#

Number outputs#

Input values used below include 1234.5, -1234.5, 0, 0.125, 1234567, and 1.234.

Currency, percent, and unit formats#

Currency, percent, and unit presets are still formats.number presets, but they use a non-default style.

formats:
  number:
    money:
      style: currency
      currency: USD
      currencyDisplay: symbol
    moneyAccounting:
      style: currency
      currency: USD
      currencySign: accounting
    percent:
      style: percent
      maximumFractionDigits: 1
    distanceKm:
      style: unit
      unit: kilometer
      unitDisplay: short

Currency and unit options#

Runtime currency resolution is:

1. per-call options.currency
2. preset currency
3. SDK instance currency
4. SDK fallback USD

Currency, percent, and unit outputs#

Intl.NumberFormat expects fractional values for percent style. For example, 0.125 renders as 12.5%, not 0.125%.

Date and time formats#

Date, time, and date-time-range presets are passed to Intl.DateTimeFormat.

Use style presets when you want locale-appropriate output:

formats:
  date:
    fullStyle:
      dateStyle: full
    shortStyle:
      dateStyle: short
  time:
    shortStyle:
      timeStyle: short
      timeZone: UTC

Use field presets when you need exact components:

formats:
  date:
    weekdayLong:
      weekday: long
      year: numeric
      month: long
      day: numeric
      timeZone: UTC
    buddhistCalendar:
      year: numeric
      month: long
      day: numeric
      calendar: buddhist
      timeZone: UTC
  time:
    fractional:
      hour: numeric
      minute: 2-digit
      second: 2-digit
      fractionalSecondDigits: 3
      timeZone: UTC

Date and time options#

Runtime time zone resolution is:

1. per-call options.timeZone
2. preset timeZone
3. SDK instance timeZone
4. SDK fallback UTC

Date outputs#

The date examples use 2026-05-12T08:30:45.678Z.

Time outputs#

The time examples use 2026-05-12T08:30:45.678Z unless the row mentions another value.

Date-time range formats#

Date-time range presets use the same date and time options, then render with formatRange.

formats:
  dateTimeRange:
    short:
      year: 2-digit
      month: numeric
      day: numeric
      hour: numeric
      minute: 2-digit
      timeZone: UTC
    event:
      year: numeric
      month: short
      day: numeric
      hour: numeric
      minute: 2-digit
      timeZone: UTC
    fullStyle:
      dateStyle: full
      timeStyle: short
      timeZone: UTC

The range examples use 2026-05-12T08:00:00Z to 2026-05-12T09:30:00Z.

Relative time formats#

Relative time presets are passed to Intl.RelativeTimeFormat.

formats:
  relative:
    auto:
      numeric: auto
      style: long
    short:
      numeric: auto
      style: short
    narrow:
      numeric: always
      style: narrow

Relative formatter calls also include a unit at runtime, such as second, minute, hour, day, week, month, quarter, or year.

Using named formats in messages#

When using the ICU module, messages can reference named presets by name:

translations:
  checkout.total:
    en-US: "Total: {amount, number, money}"
  checkout.due:
    en-US: "Due: {date, date, long}"
  checkout.time:
    en-US: "Time: {time, time, short}"

The part after the format type, such as money, long, or short, must match a key in the corresponding locale format family.

Applications can also call SDK format helpers directly:

m.formatNumber(12, "money", { currency: "EUR" });
m.formatDate(startsAt, "weekday", { timeZone: "Europe/Amsterdam" });
m.formatTime(startsAt, "short", { timeZone: "America/New_York" });
m.formatDateTimeRange(startsAt, endsAt, "event", { timeZone: "UTC" });

Format resolution order#

At runtime, format presets for a given locale and target follow this priority chain:

1. SDK constructor defaultFormats for the active locale, as runtime defaults
2. inherited locale formats via inheritFormatsFrom
3. locale's own formats
4. target-level format overrides for that locale
5. per-call overrides passed at evaluation time

This means target-level overrides can give you a different currency or date style for a specific deployment surface without changing the base locale definition.

Constructor defaultFormats are useful as fallback presets before a datafile is loaded or when a datafile omits a preset. Authored datafile formats win for same-named presets, and per-call overrides remain strongest.

Format inheritance example#

formats:
  number:
    money:
      style: currency
      currency: USD
  date:
    long:
      year: numeric
      month: long
      day: numeric

inheritFormatsFrom: en
formats:
  number:
    money:
      currency: GBP   # only overrides the currency; other money fields are inherited

The resolved en-GB formats will have money.currency: GBP but will still carry money.style: currency from en.

Advanced playground#

projects/project-1 includes a format gallery under locales/en.yml and locales/en-US.yml. It is useful when you want to adjust a preset and verify the rendered output through the CLI before copying the pattern into docs or a real project.

Nested or highly specialized format presets are best introduced only when a product surface needs them. Most teams can start with a small shared set for money, percentages, dates, times, relative time, and event ranges.

What formats are not#

Formats are not:

• ICU plural or select rule definitions
• module definitions
• arbitrary custom formatter code

Plural and select behavior in ICU messages comes from locale-specific plural rules built into the ICU library, not from adding extra format families.

Related#

• Locales
• Inheritance
• Targets
• Evaluation
• Examples
• Modules / ICU