0
# Internationalization
1

2
React Day Picker provides comprehensive internationalization support with built-in locale integration, custom calendar systems, and flexible date formatting options.
3

4
## Capabilities
5

6
### Locale Support
7

8
Built-in integration with date-fns locales for comprehensive internationalization.
9

10
```typescript { .api }
11
/**
12
 * Locale configuration interface from date-fns
13
 */
14
interface Locale {
15
  code: string;
16
  formatDistance?: Function;
17
  formatRelative?: Function;
18
  localize?: Function;
19
  formatLong?: Function;
20
  match?: Function;
21
  options?: {
22
    weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
23
    firstWeekContainsDate?: 1 | 2 | 3 | 4 | 5 | 6 | 7;
24
  };
25
}
26
```
27

28
**Usage Examples:**
29

30
```typescript
31
import { DayPicker } from "react-day-picker";
32
import { es, fr, de, ja } from "date-fns/locale";
33

34
// Spanish locale
35
<DayPicker locale={es} />
36

37
// French locale with Monday as first day of week
38
<DayPicker 
39
  locale={fr}
40
  weekStartsOn={1}
41
/>
42

43
// German locale
44
<DayPicker locale={de} />
45

46
// Japanese locale
47
<DayPicker locale={ja} />
48

49
// Multiple locales for different components
50
function MultiLingualCalendar({ userLocale }: { userLocale: string }) {
51
  const localeMap = {
52
    'es': es,
53
    'fr': fr, 
54
    'de': de,
55
    'ja': ja
56
  };
57
  
58
  return (
59
    <DayPicker 
60
      locale={localeMap[userLocale as keyof typeof localeMap]}
61
      weekStartsOn={userLocale === 'en' ? 0 : 1}
62
    />
63
  );
64
}
65
```
66

67
### DateLib Class
68

69
Custom date library wrapper providing locale-aware date operations.
70

71
```typescript { .api }
72
/**
73
 * A wrapper class around date-fns that provides utility methods for date 
74
 * manipulation and formatting with locale and timezone support
75
 */
76
class DateLib {
77
  /** The options for configuring the date library */
78
  readonly options: DateLibOptions;
79
  /** Overrides for the default date library functions */
80
  readonly overrides?: Partial<typeof DateLib.prototype>;
81
  
82
  /**
83
   * Creates an instance of DateLib
84
   * @param options - Configuration options for the date library
85
   * @param overrides - Custom overrides for the date library functions
86
   */
87
  constructor(options?: DateLibOptions, overrides?: Partial<typeof DateLib.prototype>);
88
  
89
  // Date creation
90
  /** Creates a new Date object representing today's date */
91
  today(): Date;
92
  /** Creates a new Date object with the specified year, month, and day */
93
  newDate(year: number, monthIndex: number, date: number): Date;
94
  
95
  // Date arithmetic
96
  /** Adds the specified number of days to the given date */
97
  addDays(date: Date, amount: number): Date;
98
  /** Adds the specified number of months to the given date */
99
  addMonths(date: Date, amount: number): Date;
100
  /** Adds the specified number of weeks to the given date */
101
  addWeeks(date: Date, amount: number): Date;
102
  /** Adds the specified number of years to the given date */
103
  addYears(date: Date, amount: number): Date;
104
  
105
  // Date differences
106
  /** Returns the number of calendar days between the given dates */
107
  differenceInCalendarDays(dateLeft: Date, dateRight: Date): number;
108
  /** Returns the number of calendar months between the given dates */
109
  differenceInCalendarMonths(dateLeft: Date, dateRight: Date): number;
110
  
111
  // Date ranges and intervals
112
  /** Returns the months between the given dates */
113
  eachMonthOfInterval(interval: { start: Date; end: Date }): Date[];
114
  
115
  // Week operations
116
  /** Returns the end of the broadcast week for the given date */
117
  endOfBroadcastWeek(date: Date): Date;
118
  /** Returns the end of the ISO week for the given date */
119
  endOfISOWeek(date: Date): Date;
120
  /** Returns the end of the week for the given date */
121
  endOfWeek(date: Date, options?: { weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 }): Date;
122
  /** Returns the start of the broadcast week for the given date */
123
  startOfBroadcastWeek(date: Date, dateLib: DateLib): Date;
124
  /** Returns the start of the ISO week for the given date */
125
  startOfISOWeek(date: Date): Date;
126
  /** Returns the start of the week for the given date */
127
  startOfWeek(date: Date, options?: { weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 }): Date;
128
  
129
  // Period operations
130
  /** Returns the end of the month for the given date */
131
  endOfMonth(date: Date): Date;
132
  /** Returns the end of the year for the given date */
133
  endOfYear(date: Date): Date;
134
  /** Returns the start of the day for the given date */
135
  startOfDay(date: Date): Date;
136
  /** Returns the start of the month for the given date */
137
  startOfMonth(date: Date): Date;
138
  /** Returns the start of the year for the given date */
139
  startOfYear(date: Date): Date;
140
  
141
  // Date formatting and localization
142
  /** Formats the given date using the specified format string */
143
  format(date: Date, formatStr: string, options?: DateLibOptions): string;
144
  /** Formats a number using the configured numbering system */
145
  formatNumber(value: number | string): string;
146
  
147
  // Date getters
148
  /** Returns the ISO week number for the given date */
149
  getISOWeek(date: Date): number;
150
  /** Returns the month of the given date */
151
  getMonth(date: Date, options?: { locale?: Locale }): number;
152
  /** Returns the year of the given date */
153
  getYear(date: Date, options?: { locale?: Locale }): number;
154
  /** Returns the local week number for the given date */
155
  getWeek(date: Date, options?: { weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6; firstWeekContainsDate?: 1 | 4; locale?: Locale }): number;
156
  
157
  // Date setters
158
  /** Sets the month of the given date */
159
  setMonth(date: Date, month: number): Date;
160
  /** Sets the year of the given date */
161
  setYear(date: Date, year: number): Date;
162
  
163
  // Date comparison
164
  /** Checks if the first date is after the second date */
165
  isAfter(date: Date, dateToCompare: Date): boolean;
166
  /** Checks if the first date is before the second date */
167
  isBefore(date: Date, dateToCompare: Date): boolean;
168
  /** Checks if the given dates are on the same day */
169
  isSameDay(dateLeft: Date, dateRight: Date): boolean;
170
  /** Checks if the given dates are in the same month */
171
  isSameMonth(dateLeft: Date, dateRight: Date): boolean;
172
  /** Checks if the given dates are in the same year */
173
  isSameYear(dateLeft: Date, dateRight: Date): boolean;
174
  
175
  // Array operations
176
  /** Returns the latest date in the given array of dates */
177
  max(dates: Date[]): Date;
178
  /** Returns the earliest date in the given array of dates */
179
  min(dates: Date[]): Date;
180
  
181
  // Type checking
182
  /** Checks if the given value is a Date object */
183
  isDate(value: unknown): value is Date;
184
}
185

186
/**
187
 * Configuration options for the DateLib class
188
 */
189
interface DateLibOptions {
190
  /** A constructor for the Date object */
191
  Date?: typeof Date;
192
  /** A locale to use for formatting dates */
193
  locale?: Locale;
194
  /** A time zone to use for dates */
195
  timeZone?: string;
196
  /** The numbering system to use for formatting numbers */
197
  numerals?: Numerals;
198
  /** The index of the first day of the week (0 - Sunday) */
199
  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
200
  /** The day of January that is always in the first week of the year */
201
  firstWeekContainsDate?: 1 | 4;
202
  /** Enable DD and DDDD for week year tokens */
203
  useAdditionalWeekYearTokens?: boolean;
204
  /** Enable YY and YYYY for day of year tokens */
205
  useAdditionalDayOfYearTokens?: boolean;
206
}
207

208
/**
209
 * Numeral system types supported for formatting
210
 */
211
type Numerals = 
212
  | "latn"     // Latin (Western Arabic)
213
  | "arab"     // Arabic-Indic
214
  | "arabext"  // Eastern Arabic-Indic (Persian)
215
  | "deva"     // Devanagari
216
  | "beng"     // Bengali
217
  | "guru"     // Gurmukhi
218
  | "gujr"     // Gujarati
219
  | "orya"     // Oriya
220
  | "tamldec"  // Tamil
221
  | "telu"     // Telugu
222
  | "knda"     // Kannada
223
  | "mlym";    // Malayalam
224
```
225

226
**Usage Examples:**
227

228
```typescript
229
import { DateLib } from "react-day-picker";
230
import { fr } from "date-fns/locale";
231

232
// Create custom DateLib with French locale
233
const frenchDateLib = new DateLib({
234
  locale: fr,
235
  weekStartsOn: 1, // Monday
236
  firstWeekContainsDate: 4
237
});
238

239
// Use with DayPicker
240
<DayPicker dateLib={frenchDateLib} />
241

242
// Custom date operations
243
const today = new Date();
244
const nextWeek = frenchDateLib.addDays(today, 7);
245
const formatted = frenchDateLib.format(nextWeek, "EEEE, d MMMM yyyy");
246
// Result: "lundi, 15 janvier 2024" (in French)
247
```
248

249
### Persian/Jalali Calendar System 
250

251
Support for Persian (Jalali) calendar system with RTL text direction.
252

253
```typescript { .api }
254
/**
255
 * Persian calendar DayPicker component
256
 * Available from "react-day-picker/persian"
257
 */
258
function DayPicker(props: DayPickerProps): React.ReactElement;
259

260
/**
261
 * Get DateLib configured for Persian calendar
262
 * @param options - Persian calendar options
263
 * @returns DateLib instance for Persian dates
264
 */
265
function getDateLib(options?: PersianDateLibOptions): DateLib;
266

267
interface PersianDateLibOptions extends DateLibOptions {
268
  /** Persian locale (default: faIR) */
269
  locale?: Locale;
270
  /** Week starts on Saturday for Persian calendar */
271
  weekStartsOn?: 6;
272
}
273

274
/** Persian locale */
275
const faIR: Locale;
276

277
/** English locale for Persian calendar */
278
const enUS: Locale;
279
```
280

281
**Usage Examples:**
282

283
```typescript
284
// Import Persian calendar variant
285
import { DayPicker } from "react-day-picker/persian";
286
import "react-day-picker/style.css";
287

288
// Basic Persian calendar
289
function PersianCalendar() {
290
  const [selected, setSelected] = useState<Date>();
291
  
292
  return (
293
    <DayPicker
294
      mode="single"
295
      selected={selected}
296
      onSelect={setSelected}
297
      dir="rtl" // Right-to-left text direction
298
    />
299
  );
300
}
301

302
// Persian calendar with custom configuration
303
import { DayPicker, getDateLib, faIR } from "react-day-picker/persian";
304

305
function CustomPersianCalendar() {
306
  const persianDateLib = getDateLib({
307
    locale: faIR,
308
    weekStartsOn: 6 // Saturday
309
  });
310
  
311
  return (
312
    <DayPicker
313
      mode="single"
314
      dateLib={persianDateLib}
315
      dir="rtl"
316
      weekStartsOn={6}
317
    />
318
  );
319
}
320
```
321

322
### Time Zone Support
323

324
Integration with time zone aware dates using TZDate.
325

326
```typescript { .api }
327
/**
328
 * Time zone aware Date class (re-exported from @date-fns/tz)
329
 */
330
class TZDate extends Date {
331
  constructor(date: Date | string | number, timeZone: string);
332
  
333
  /** Get the time zone identifier */
334
  getTimezone(): string;
335
  /** Convert to different time zone */
336
  withTimeZone(timeZone: string): TZDate;
337
}
338

339
/**
340
 * DayPicker props for time zone support
341
 */
342
interface PropsBase {
343
  /** Time zone identifier (e.g., "America/New_York") */
344
  timeZone?: string;
345
  /** Current date in the specified time zone */
346
  today?: Date | TZDate;
347
  /** Selected dates in the specified time zone */
348
  selected?: Date | TZDate | (Date | TZDate)[] | DateRange;
349
}
350
```
351

352
**Usage Examples:**
353

354
```typescript
355
import { DayPicker, TZDate } from "react-day-picker";
356

357
// Calendar with New York time zone
358
function TimeZoneCalendar() {
359
  const [selected, setSelected] = useState<Date>();
360
  const timeZone = "America/New_York";
361
  
362
  return (
363
    <DayPicker
364
      mode="single"
365
      selected={selected}
366
      onSelect={setSelected}
367
      timeZone={timeZone}
368
      today={new TZDate(new Date(), timeZone)}
369
    />
370
  );
371
}
372

373
// Multi-timezone calendar
374
function MultiTimezoneCalendar() {
375
  const [timezone, setTimezone] = useState("UTC");
376
  const [selected, setSelected] = useState<Date>();
377
  
378
  const timezones = [
379
    "UTC",
380
    "America/New_York", 
381
    "Europe/London",
382
    "Asia/Tokyo"
383
  ];
384
  
385
  return (
386
    <div>
387
      <select value={timezone} onChange={(e) => setTimezone(e.target.value)}>
388
        {timezones.map(tz => (
389
          <option key={tz} value={tz}>{tz}</option>
390
        ))}
391
      </select>
392
      
393
      <DayPicker
394
        mode="single"
395
        selected={selected}
396
        onSelect={setSelected}
397
        timeZone={timezone}
398
        today={new TZDate(new Date(), timezone)}
399
      />
400
    </div>
401
  );
402
}
403
```
404

405
### Numeral Systems
406

407
Support for different numeral systems (Arabic-Indic, Persian, etc.).
408

409
```typescript { .api }
410
/**
411
 * Numeral system enumeration
412
 */
413
enum Numerals {
414
  /** Western Arabic numerals (0-9) */
415
  latn = "latn",
416
  /** Arabic-Indic numerals (٠-٩) */
417
  arab = "arab", 
418
  /** Extended Arabic-Indic numerals */
419
  arabext = "arabext",
420
  /** Persian numerals (۰-۹) */
421
  pers = "pers"
422
}
423

424
/**
425
 * Props for custom numeral system
426
 */
427
interface PropsBase {
428
  /** Numeral system for date display */
429
  numerals?: Numerals;
430
}
431
```
432

433
**Usage Examples:**
434

435
```typescript
436
import { DayPicker, Numerals } from "react-day-picker";
437
import { ar } from "date-fns/locale";
438

439
// Arabic calendar with Arabic-Indic numerals
440
<DayPicker
441
  locale={ar}
442
  numerals={Numerals.arab}
443
  dir="rtl"
444
/>
445

446
// Persian calendar with Persian numerals  
447
import { DayPicker } from "react-day-picker/persian";
448

449
<DayPicker
450
  numerals={Numerals.pers}
451
  dir="rtl"
452
/>
453
```
454

455
### Broadcast Calendar Support
456

457
Support for broadcast/retail calendar systems used in television and retail industries.
458

459
```typescript { .api }
460
/**
461
 * Props for broadcast calendar support
462
 */
463
interface PropsBase {
464
  /** Enable broadcast calendar (weeks start on Monday, 4-4-5 week pattern) */
465
  broadcastCalendar?: boolean;
466
}
467

468
/**
469
 * Helper functions for broadcast calendar
470
 */
471
function startOfBroadcastWeek(date: Date): Date;
472
function endOfBroadcastWeek(date: Date): Date;
473
function getBroadcastWeeksInMonth(date: Date): CalendarWeek[];
474
```
475

476
**Usage Examples:**
477

478
```typescript
479
// Broadcast calendar for retail/TV industry
480
<DayPicker
481
  broadcastCalendar={true}
482
  weekStartsOn={1} // Always Monday for broadcast calendar
483
  showWeekNumber={true}
484
/>
485

486
// Custom broadcast week calculations
487
import { startOfBroadcastWeek, endOfBroadcastWeek } from "react-day-picker";
488

489
const today = new Date();
490
const weekStart = startOfBroadcastWeek(today);
491
const weekEnd = endOfBroadcastWeek(today);
492
console.log(`Broadcast week: ${weekStart} to ${weekEnd}`);
493
```