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:
| Model | Carries order? | Carries separators / literals? | Examples |
|---|---|---|---|
| Pattern | yes | yes | DD/MM/YYYY, every dialect and library |
| Field bag | no | no | Intl 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, adateStyle/timeStylemismatch with no single fused preset, an Intl-only zone style (long,*Generic), and the flexibledayPeriod.
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 UnsupportedTokenErrortoIntlOptions 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.