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 LibraryThe 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:
| Layer | What it models | Where it lives |
|---|---|---|
| Grammar (dialect) | A formatting language: token grammar, literal escaping, canonical meanings | Dialects |
| Tool (library) | One specific tool built on a dialect: which tokens it renders, its aliases, its limitations | Libraries |
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.