Skip to Content
Core ConceptsHow It Works

How It Works

rosetta-date maps every recognized token to a canonical semantic representation before rendering it in the target dialect. The representation records what the token means independently of any dialect:

Source Library → Source Dialect → Canonical Representation → Target Dialect → Target Library

The canonical hub

The canonical model is a neutral vocabulary of date-field meanings: “calendar year”, “2-digit month”, “day of year, ordinal”, and so on. Each dialect declares how its tokens map to and from this vocabulary.

Because every dialect maps to and from the shared vocabulary, a dialect needs two mappings to interoperate with all the others. The engine operates on canonical fields instead of pair-specific rules.

A new dialect or library connects to the canonical model instead of defining converters for every existing dialect.

Why route through meaning?

Consider YYYY. In the Moment.js grammar it is a calendar year; in LDML it is a week-numbering year, and the calendar year is yyyy. A naive find-and-replace would silently corrupt the format. By resolving each token to its canonical meaning first, rosetta-date selects the target token for that meaning. For example, YYYY (moment) becomes yyyy (ldml), while moment’s week-numbering gggg becomes ldml’s YYYY.

The two layers

The model has two layers:

LayerWhat it modelsWhere it lives
Grammar (dialect)A formatting language: token grammar, literal escaping, canonical meaningsDialects
Tool (library)One specific tool built on a dialect: which tokens it renders, its aliases, its limitationsLibraries

Translating between dialects performs grammar conversion. Translating between libraries adds tool-specific checks and flags tokens a tool cannot render. See Dialects & Libraries for selection guidance.

Last updated on