Skip to Content
Introduction

rosetta-date

A translation engine for date-formatting languages.

rosetta-date translates date-format strings between formatting languages by routing recognized tokens through a canonical intermediate representation before rendering them in the target language.

import { convert } from 'rosetta-date' import { ldml, moment } from 'rosetta-date/dialects' convert('YYYY-MM-DD', { from: moment, to: ldml }) // 'yyyy-MM-dd'

Although YYYY-MM-DD and yyyy-MM-dd look different, they express the same date format using different formatting languages. rosetta-date rewrites the token string while leaving date values untouched.

Why it exists

Moving a format string from one date library to another is deceptively error-prone. YYYY means a calendar year in Moment.js but a week-numbering year in LDML; D is a day of month in one and a day of year in another. Hand-translating these tables is exactly the kind of work that looks trivial and quietly ships bugs. Migrating a Moment.js format to date-fns is one call:

import { convert } from 'rosetta-date' import { dateFns, momentjs } from 'rosetta-date/libraries' convert('dddd, MMMM Do YYYY', { from: momentjs, to: dateFns }) // 'EEEE, MMMM do yyyy'

Each grammar maps its tokens to canonical fields once. A token that converts cleanly round-trips faithfully. The unsupported-token policy handles tokens with no clean counterpart and preserves them as literals by default.

Highlights

  • 🔁 Bidirectional: Each dialect parses tokens to canonical fields and renders canonical fields back to tokens.
  • 🧭 Canonical semantic model: Tokens convert through shared meanings instead of pairwise dialect mappings.
  • 🧩 Extensible by design: New dialects map to the canonical model; libraries extend or narrow a dialect.
  • 🛡️ Escape-aware tokenizer: Literals round-trip across dialects.
  • 🌐 Intl adapter: Convert a token pattern to Intl.DateTimeFormat options and back.
  • 🔍 Introspectable: describe reports what a pattern means, and explain reports what a conversion would do.
  • 🌳 Tree-shakeable: Dialects and libraries ship from their own entrypoints.
  • 🪶 Zero runtime dependencies: No runtime dependencies.

Where to go next

Last updated on