Calendars and languages

Month names, weekday names, digits, the order of day and month, the first day of the week and the text direction all come from the browser's Intl. Nothing is bundled, and every locale the browser knows works.

createDatePicker(input, { locale: 'ar-EG' }); // Arabic, right-to-left, Saturday-first grid
createDatePicker(input, { locale: 'ar-AE' }); // Monday-first, as the UAE's week has been since 2022
createDatePicker(input, { locale: 'ur-PK' }); // Sunday-first
createDatePicker(input, { locale: 'de-CH', weekStart: 1 });

Right-to-left locales mirror the whole panel, and arrow keys follow what people see: ← moves to the next day.

Hijri and Persian calendars#

createDatePicker(input, { locale: 'ar-SA', calendar: 'islamic-umalqura' });
createDatePicker(input, { locale: 'fa-IR', calendar: 'persian' });

The grid, heading, navigation and typed numbers all use that calendar. The stored value is still a Gregorian ISO date, so your database and API don't change.

Supported calendars: islamic-umalqura (the Saudi Umm al-Qura calendar), islamic-civil, islamic-tbla, persian and buddhist.

How they're tested: every day from 1900 to 2100 is converted to each calendar and back, and must match.

Two calendars at once#

Useful in the Gulf, where both are in daily use:

createDatePicker(input, { secondaryCalendar: 'islamic-umalqura' });

Each day shows its Hijri day underneath, and the heading shows the Hijri months the grid spans, e.g. Ramadan – Shawwal 1447 AH.

Translating the interface#

Dates come from Intl, but the buttons and the messages are words. Fifteen languages are written, and none of them is in your bundle until you ask for it:

Arabic · Urdu · French · German · Spanish · Portuguese · Italian · Dutch · Turkish · Russian · Polish · Hindi · Indonesian · Chinese · Japanese

import { createDatePicker } from '@devix-labs/date-picker';
import { registerAll } from '@devix-labs/date-picker/locales';

registerAll();                                   // every language, once, at startup
createDatePicker(input, { locale: 'ar-AE' });    // now Arabic throughout

One language, which is what most sites need — your bundler ships only what you name:

import { registerStrings } from '@devix-labs/date-picker';
import { ar, ur } from '@devix-labs/date-picker/locales';

registerStrings('ar', ar);
registerStrings('ur', ur);

A pack is around 0.5 KB gzipped; all fifteen together are 7.5 KB, and the widget itself does not carry any of it. Registering is global, so <dx-date-picker locale="ar"> in markup is translated too — markup has nowhere to pass an object.

ar covers ar-EG, ar-AE and every other Arabic region. Register an exact tag when a country needs different wording, and it wins for that country only:

registerStrings('pt-BR', brazilian); // pt still serves pt-PT

What a pack does that a table of strings cannot#

Each pack is a function of the locale it is used with, so it can be right about two things a fixed object gets wrong:

• Digits. ar-EG writes ٧ and ar-AE writes 7. The same pack does both.
• Plurals. Arabic has six forms and a dual — one day, two days, a few days, many days — and Russian and Polish have four between them. The count of nights in a range agrees with the number in front of it, through Intl.PluralRules.

ar('ar-EG').days(2);  // يومان   — the dual, not "٢ أيام"
ar('ar-AE').days(3);  // 3 أيام
ru('ru').days(5);     // 5 дней  — not "5 день"

Range preset names are translated with everything else, so an Arabic range picker does not show Last 7 days beside its calendar.

Your own words#

strings still wins over a registered pack, one key at a time:

createDatePicker(input, { locale: 'fr', strings: { today: 'Ce jour' } });

And a language nobody has written yet is one object away — a plain object is accepted as well as a function:

import { registerStrings } from '@devix-labs/date-picker';

registerStrings('sw', { today: 'Leo', clear: 'Futa', chooseDate: 'Chagua tarehe' });

The complete list of keys is DEFAULT_STRINGS, exported from the package. Anything you leave out falls back to English rather than showing a blank button.