Glossary / Locale-aware dates

Locale-aware dates

Locale-aware date formatting presents a date according to a user’s language, region, calendar, and preferences—for example, ordering day/month/year, choosing month names, selecting a 12- or 24-hour clock, and formatting relative dates. Applications should store a clear canonical date or instant and format it at the UI boundary using locale data. A date-only value, a local wall-clock time, and a moment on the global timeline are different domain types and must not be conflated.

Data semantics first

• Instant: a unique moment on the UTC timeline, commonly stored as ISO-8601 with an offset or as epoch time.
• Plain date: a calendar date without time or zone, such as a birthday or invoice date. Converting it to UTC midnight can shift the displayed day in another zone.
• Local date-time: wall-clock fields without an offset/zone; it may be ambiguous or nonexistent during daylight-saving changes.
• Use an explicit calendar and time zone when the domain requires them. Locale controls presentation; time zone controls mapping between instants and local clocks.
• JavaScript Intl.DateTimeFormat(locale, options) formats dates and times; formatRange may present intervals. Do not hard-code patterns such as MM/DD/YYYY.
• Parsing is separate from formatting. Native Date parsing of non-standard localized strings is unreliable; use a deliberate input format and validate it.
• Calendar systems can differ; Intl supports locale extensions and options, but product semantics may require Gregorian dates or a specified calendar.

Common bugs and tests

Test dates around midnight, year boundaries, leap days, daylight-saving transitions, and users in different zones. Specify the time zone for deterministic server rendering and tests. Beware that JavaScript Date represents an instant and its default methods may use the host time zone. For date-only data, use a representation/library that preserves date semantics instead of creating an arbitrary instant. Validate that labels and input controls explain which calendar or zone is intended.

Interview questions

1. Why can a birthday shift by one day? Treating a plain date as a UTC instant and formatting in a negative offset can display the previous calendar day.
2. Locale versus time zone? Locale controls conventions and language; time zone maps instants to local clock/date values.
3. Why not store 25/12/2026? It is ambiguous display text; store a canonical value and localize when rendering.
4. What happens at daylight-saving transitions? Some local times occur twice or not at all; define disambiguation behavior for scheduling.
5. How do you test date formatting? Pin locale, time zone, calendar, and clock, then test boundary dates and relevant locales.

References

• MDN: Intl.DateTimeFormat
• Unicode CLDR: Date/Time Patterns