Skip to Content
GuidesIntl Options

Intl Options

The rosetta-date/intl adapter converts between token strings and native Intl.DateTimeFormat options for locale-aware formatting.

import { toIntlOptions } from 'rosetta-date/intl' import { moment } from 'rosetta-date/dialects' const options = toIntlOptions('YYYY-MM-DD HH:mm', { from: moment }) // { year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', hourCycle: 'h23' } new Intl.DateTimeFormat('pt-BR', options).format(new Date())

Why a separate surface

Unlike the other endpoints, Intl.DateTimeFormat takes an unordered options bag. The locale decides the layout at format time:

ModelCarries order?Carries separators / literals?Examples
PatternyesyesDD/MM/YYYY, every dialect and library
Field bagnonoIntl options

Converting between these models loses order and literal separators. The adapter therefore uses its own pair of functions instead of acting as an endpoint for convert.

toIntlOptions: pattern to options

toIntlOptions(format, { from }) reads the locale-agnostic intent out of a format string.

import { toIntlOptions } from 'rosetta-date/intl' import { moment } from 'rosetta-date/dialects' toIntlOptions('h:mm A', { from: moment }) // { hour: 'numeric', minute: '2-digit', hourCycle: 'h12' }

Literals and field order are dropped because the locale decides where separators go and whether the day leads. 'DD/MM/YYYY' and 'YYYY-MM-DD' produce the same options. A pt-BR formatter renders those options in the Brazilian layout, while an en-US formatter uses the American layout.

The AM/PM markers A and a have no Intl option, so on their own they are dropped or throw under 'throw'. An h11 or h12 hour already carries the 12-hour cycle through hourCycle.

fromIntlOptions: options to pattern

fromIntlOptions(intlOptions, { to }) converts options to a token pattern. dateStyle and timeStyle map to the target’s localized presets, which the library resolves for its locale at format time. The conversion therefore needs no locale argument.

import { fromIntlOptions } from 'rosetta-date/intl' import { dayjs } from 'rosetta-date/libraries' fromIntlOptions({ dateStyle: 'short' }, { to: dayjs }) // 'L' fromIntlOptions({ dateStyle: 'long', timeStyle: 'long' }, { to: dayjs }) // 'LLL'

Targeting a library returns its preset, such as L for Moment.js or Day.js and P for date-fns. Presets let the target library apply its own locale. See Localized presets.

Components reconstruct a skeleton

When the options are a component bag rather than a style, there is no order or separator to recover without a locale. The output is a skeleton with fields in CLDR canonical order and no separators:

fromIntlOptions({ year: 'numeric', month: '2-digit', day: '2-digit' }, { to: ldml }) // 'yyyyMMdd'

A round trip preserves the field set, not the layout. Calling toIntlOptions and then fromIntlOptions recovers the components, but not the separators or ordering.

Unsupported fields

The canonical vocabulary is a strict superset of what Intl.DateTimeFormat can express. Fields with no equivalent are routed to onUnsupportedToken:

  • toIntlOptions: quarter, week-numbering year, week of year, day-of-year, ordinals, epoch, the AM/PM marker, stand-alone names, and the numeric / short weekday forms.
  • fromIntlOptions: a preset against a pure dialect that has no preset token, a dateStyle / timeStyle mismatch with no single fused preset, an Intl-only zone style (long, *Generic), and the flexible dayPeriod.

The policy is narrower than the dialect-to-dialect one: only 'throw' and 'drop' (the default) apply, since there is no output string to literalize and no target dialect for a handler.

toIntlOptions('[Q]Q YYYY', { from: moment }) // { year: 'numeric' }; quarter dropped toIntlOptions('Q', { from: moment, onUnsupportedToken: 'throw' }) // throws UnsupportedTokenError

toIntlOptions produces options for human-readable output. Intl.DateTimeFormat renders a GMT-prefixed offset (GMT+05:00), not a bare ISO +05:00. The ISO offsets that emit Z at zero have no Intl equivalent at all. Keep machine-readable ISO timestamps as a plain convert between dialects.

Last updated on