0
# Localization and Internationalization
1

2
Complete internationalization (i18n) support for React DatePicker with date-fns locale integration, enabling global applications with proper date formatting, month/day names, and calendar behavior for different cultures and languages.
3

4
## Capabilities
5

6
### Locale Management
7

8
Functions for registering, setting, and managing locales for internationalization.
9

10
```typescript { .api }
11
/**
12
 * Register a date-fns locale for use with DatePicker
13
 * @param localeName - Name identifier for the locale (e.g., "es", "fr", "de")
14
 * @param localeData - date-fns locale object
15
 */
16
function registerLocale(localeName: string, localeData: LocaleObject): void;
17

18
/**
19
 * Set the default locale for all DatePicker instances
20
 * @param locale - Registered locale name to use as default
21
 */
22
function setDefaultLocale(locale: string): void;
23

24
/**
25
 * Get the currently set default locale
26
 * @returns Current default locale name
27
 */
28
function getDefaultLocale(): string;
29

30
/**
31
 * Get locale object for formatting and parsing
32
 * @param locale - Locale name or locale object
33
 * @returns date-fns locale object or undefined
34
 */
35
function getLocaleObject(locale?: Locale): LocaleObject | undefined;
36
```
37

38
### Locale-Aware Formatting Functions
39

40
Functions for formatting dates and date components with locale support.
41

42
```typescript { .api }
43
/**
44
 * Get formatted weekday name in specified locale
45
 * @param date - Date to get weekday from
46
 * @param formatFunc - Formatting function ("format" for long, "short", or "min")
47
 * @param locale - Locale for formatting
48
 * @returns Formatted weekday name
49
 */
50
function getFormattedWeekdayInLocale(
51
  date: Date,
52
  formatFunc: string,
53
  locale?: Locale
54
): string;
55

56
/**
57
 * Get short weekday name in locale
58
 * @param date - Date to get weekday from
59
 * @param locale - Locale for formatting
60
 * @returns Short weekday name (e.g., "Mon", "Tue")
61
 */
62
function getWeekdayShortInLocale(date: Date, locale?: Locale): string;
63

64
/**
65
 * Get minimal weekday name in locale
66
 * @param date - Date to get weekday from
67
 * @param locale - Locale for formatting
68
 * @returns Minimal weekday name (e.g., "M", "T")
69
 */
70
function getWeekdayMinInLocale(date: Date, locale?: Locale): string;
71

72
/**
73
 * Get month name in specified locale
74
 * @param month - Month number (0-11)
75
 * @param locale - Locale for formatting
76
 * @returns Full month name
77
 */
78
function getMonthInLocale(month: number, locale?: Locale): string;
79

80
/**
81
 * Get short month name in locale
82
 * @param month - Month number (0-11)  
83
 * @param locale - Locale for formatting
84
 * @returns Short month name
85
 */
86
function getMonthShortInLocale(month: number, locale?: Locale): string;
87

88
/**
89
 * Get quarter name in locale
90
 * @param quarter - Quarter number (1-4)
91
 * @param locale - Locale for formatting
92
 * @returns Quarter name (e.g., "Q1", "1st quarter")
93
 */
94
function getQuarterShortInLocale(quarter: number, locale?: Locale): string;
95
```
96

97
## Types
98

99
```typescript { .api }
100
/**
101
 * Locale specification - either string identifier or locale object
102
 */
103
type Locale = string | LocaleObject;
104

105
/**
106
 * date-fns locale object interface
107
 */
108
interface LocaleObject {
109
  code?: string;
110
  formatDistance?: Function;
111
  formatRelative?: Function;
112
  localize?: {
113
    ordinalNumber: Function;
114
    era: Function;
115
    quarter: Function;
116
    month: Function;
117
    day: Function;
118
    dayPeriod: Function;
119
  };
120
  formatLong?: {
121
    date: Function;
122
    time: Function;
123
    dateTime: Function;
124
  };
125
  match?: {
126
    ordinalNumber: Function;
127
    era: Function;
128
    quarter: Function;
129
    month: Function;
130
    day: Function;
131
    dayPeriod: Function;
132
  };
133
  options?: {
134
    weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
135
    firstWeekContainsDate?: 1 | 2 | 3 | 4 | 5 | 6 | 7;
136
  };
137
}
138
```
139

140
## Usage Examples
141

142
### Basic Locale Setup
143

144
```typescript
145
import { registerLocale, setDefaultLocale, getDefaultLocale } from "react-datepicker";
146
import { es, fr, de, ja } from "date-fns/locale";
147

148
// Register multiple locales
149
registerLocale("es", es);
150
registerLocale("fr", fr);
151
registerLocale("de", de);
152
registerLocale("ja", ja);
153

154
// Set Spanish as default
155
setDefaultLocale("es");
156

157
console.log(getDefaultLocale()); // "es"
158
```
159

160
### Using Locales with DatePicker
161

162
```typescript
163
import React, { useState } from "react";
164
import DatePicker from "react-datepicker";
165
import { registerLocale } from "react-datepicker";
166
import { es, fr, de } from "date-fns/locale";
167

168
// Register locales
169
registerLocale("es", es);
170
registerLocale("fr", fr);
171
registerLocale("de", de);
172

173
function MultiLanguageDatePicker() {
174
  const [startDate, setStartDate] = useState<Date | null>(new Date());
175
  const [locale, setLocale] = useState("es");
176

177
  return (
178
    <div>
179
      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
180
        <option value="en">English</option>
181
        <option value="es">Español</option>
182
        <option value="fr">Français</option>
183
        <option value="de">Deutsch</option>
184
      </select>
185
      
186
      <DatePicker
187
        selected={startDate}
188
        onChange={(date) => setStartDate(date)}
189
        locale={locale}
190
        dateFormat="PP" // Localized long date format
191
        placeholderText="Selecciona una fecha"
192
      />
193
    </div>
194
  );
195
}
196
```
197

198
### Calendar Start Day Configuration
199

200
```typescript
201
import { registerLocale } from "react-datepicker";
202
import { enGB, de } from "date-fns/locale";
203

204
// Register UK locale (Monday start) and German locale
205
registerLocale("en-GB", enGB);
206
registerLocale("de", de);
207

208
function WeekStartDatePicker() {
209
  const [date, setDate] = useState<Date | null>(null);
210

211
  return (
212
    <DatePicker
213
      selected={date}
214
      onChange={setDate}
215
      locale="en-GB" // Week starts on Monday
216
      inline
217
    />
218
  );
219
}
220
```
221

222
### Custom Date Formats by Locale
223

224
```typescript
225
import React, { useState } from "react";
226
import DatePicker from "react-datepicker";
227
import { registerLocale } from "react-datepicker";
228
import { enUS, enGB, de, ja } from "date-fns/locale";
229

230
registerLocale("en-US", enUS);
231
registerLocale("en-GB", enGB);
232
registerLocale("de", de);
233
registerLocale("ja", ja);
234

235
const localeFormats = {
236
  "en-US": "MM/dd/yyyy",
237
  "en-GB": "dd/MM/yyyy",
238
  "de": "dd.MM.yyyy",
239
  "ja": "yyyy年MM月dd日"
240
};
241

242
function LocalizedFormatDatePicker() {
243
  const [date, setDate] = useState<Date | null>(new Date());
244
  const [currentLocale, setCurrentLocale] = useState("en-US");
245

246
  return (
247
    <div>
248
      <select 
249
        value={currentLocale} 
250
        onChange={(e) => setCurrentLocale(e.target.value)}
251
      >
252
        <option value="en-US">US English</option>
253
        <option value="en-GB">UK English</option>
254
        <option value="de">German</option>
255
        <option value="ja">Japanese</option>
256
      </select>
257
      
258
      <DatePicker
259
        selected={date}
260
        onChange={setDate}
261
        locale={currentLocale}
262
        dateFormat={localeFormats[currentLocale]}
263
      />
264
    </div>
265
  );
266
}
267
```
268

269
### Time Picker with Locale
270

271
```typescript
272
import { registerLocale } from "react-datepicker";
273
import { fr, de } from "date-fns/locale";
274

275
registerLocale("fr", fr);
276
registerLocale("de", de);
277

278
function LocalizedTimePicker() {
279
  const [date, setDate] = useState<Date | null>(new Date());
280

281
  return (
282
    <DatePicker
283
      selected={date}
284
      onChange={setDate}
285
      showTimeSelect
286
      timeFormat="HH:mm"
287
      timeIntervals={15}
288
      timeCaption="Heure" // French for "Time"
289
      dateFormat="Pp" // Localized date and time format
290
      locale="fr"
291
    />
292
  );
293
}
294
```
295

296
### Locale-Aware Date Range Picker
297

298
```typescript
299
import { registerLocale } from "react-datepicker";
300
import { es } from "date-fns/locale";
301

302
registerLocale("es", es);
303

304
function SpanishDateRangePicker() {
305
  const [startDate, setStartDate] = useState<Date | null>(null);
306
  const [endDate, setEndDate] = useState<Date | null>(null);
307

308
  return (
309
    <DatePicker
310
      selected={startDate}
311
      onChange={(dates: [Date | null, Date | null]) => {
312
        const [start, end] = dates;
313
        setStartDate(start);
314
        setEndDate(end);
315
      }}
316
      startDate={startDate}
317
      endDate={endDate}
318
      selectsRange
319
      locale="es"
320
      dateFormat="dd 'de' MMMM 'de' yyyy"
321
      placeholderText="Selecciona rango de fechas"
322
      rangeSeparator=" hasta "
323
    />
324
  );
325
}
326
```
327

328
### Dynamic Locale Loading
329

330
```typescript
331
import React, { useState, useEffect } from "react";
332
import DatePicker, { registerLocale } from "react-datepicker";
333

334
// Dynamic import function for locales
335
async function loadLocale(localeCode: string) {
336
  try {
337
    const localeModule = await import(`date-fns/locale/${localeCode}`);
338
    return localeModule.default;
339
  } catch (error) {
340
    console.error(`Failed to load locale: ${localeCode}`, error);
341
    return null;
342
  }
343
}
344

345
function DynamicLocaleDatePicker() {
346
  const [date, setDate] = useState<Date | null>(new Date());
347
  const [currentLocale, setCurrentLocale] = useState("en");
348
  const [loadedLocales, setLoadedLocales] = useState<Set<string>>(new Set(["en"]));
349

350
  const handleLocaleChange = async (newLocale: string) => {
351
    if (!loadedLocales.has(newLocale)) {
352
      const localeData = await loadLocale(newLocale);
353
      if (localeData) {
354
        registerLocale(newLocale, localeData);
355
        setLoadedLocales(prev => new Set([...prev, newLocale]));
356
      }
357
    }
358
    setCurrentLocale(newLocale);
359
  };
360

361
  return (
362
    <div>
363
      <select 
364
        value={currentLocale}
365
        onChange={(e) => handleLocaleChange(e.target.value)}
366
      >
367
        <option value="en">English</option>
368
        <option value="es">Spanish</option>
369
        <option value="fr">French</option>
370
        <option value="de">German</option>
371
        <option value="it">Italian</option>
372
        <option value="pt">Portuguese</option>
373
        <option value="ru">Russian</option>
374
        <option value="ja">Japanese</option>
375
        <option value="ko">Korean</option>
376
        <option value="zh-CN">Chinese (Simplified)</option>
377
      </select>
378
      
379
      <DatePicker
380
        selected={date}
381
        onChange={setDate}
382
        locale={currentLocale}
383
        dateFormat="PP"
384
        showMonthDropdown
385
        showYearDropdown
386
      />
387
    </div>
388
  );
389
}
390
```
391

392
### Right-to-Left (RTL) Language Support
393

394
```typescript
395
import { registerLocale } from "react-datepicker";
396
import { ar, he, fa } from "date-fns/locale";
397

398
registerLocale("ar", ar); // Arabic
399
registerLocale("he", he); // Hebrew
400
registerLocale("fa", fa); // Persian/Farsi
401

402
function RTLDatePicker() {
403
  const [date, setDate] = useState<Date | null>(new Date());
404
  const [locale, setLocale] = useState("ar");
405

406
  return (
407
    <div dir={locale === "ar" || locale === "he" || locale === "fa" ? "rtl" : "ltr"}>
408
      <DatePicker
409
        selected={date}
410
        onChange={setDate}
411
        locale={locale}
412
        dateFormat="PP"
413
        className={locale === "ar" ? "arabic-calendar" : ""}
414
        calendarClassName="rtl-calendar"
415
      />
416
    </div>
417
  );
418
}
419
```
420

421
## Common Locale Configurations
422

423
### Popular Locales Setup
424

425
```typescript
426
import { registerLocale, setDefaultLocale } from "react-datepicker";
427
import {
428
  enUS, enGB, enCA, enAU,  // English variants
429
  es, esES, esMX,          // Spanish variants  
430
  fr, frCA,                // French variants
431
  de, deAT, deCH,          // German variants
432
  it, itCH,                // Italian variants
433
  pt, ptBR,                // Portuguese variants
434
  ru,                      // Russian
435
  ja,                      // Japanese
436
  ko,                      // Korean
437
  zhCN, zhTW,              // Chinese variants
438
  ar, arSA,                // Arabic variants
439
  hi,                      // Hindi
440
  nl, nlBE,                // Dutch variants
441
  sv, svFI,                // Swedish variants
442
  da,                      // Danish
443
  no, nb,                  // Norwegian variants
444
  fi,                      // Finnish
445
  pl,                      // Polish
446
  cs,                      // Czech
447
  hu,                      // Hungarian
448
  th,                      // Thai
449
  vi,                      // Vietnamese
450
  id,                      // Indonesian
451
  ms,                      // Malaysian
452
  tr,                      // Turkish
453
  he,                      // Hebrew
454
} from "date-fns/locale";
455

456
// Register all common locales
457
const locales = {
458
  "en-US": enUS, "en-GB": enGB, "en-CA": enCA, "en-AU": enAU,
459
  "es": es, "es-ES": esES, "es-MX": esMX,
460
  "fr": fr, "fr-CA": frCA,
461
  "de": de, "de-AT": deAT, "de-CH": deCH,
462
  "it": it, "it-CH": itCH,
463
  "pt": pt, "pt-BR": ptBR,
464
  "ru": ru, "ja": ja, "ko": ko,
465
  "zh-CN": zhCN, "zh-TW": zhTW,
466
  "ar": ar, "ar-SA": arSA, "hi": hi,
467
  "nl": nl, "nl-BE": nlBE,
468
  "sv": sv, "sv-FI": svFI, "da": da,
469
  "no": no, "nb": nb, "fi": fi, "pl": pl,
470
  "cs": cs, "hu": hu, "th": th, "vi": vi,
471
  "id": id, "ms": ms, "tr": tr, "he": he
472
};
473

474
// Register all locales
475
Object.entries(locales).forEach(([name, locale]) => {
476
  registerLocale(name, locale);
477
});
478

479
// Set default based on browser locale
480
const browserLocale = navigator.language || "en-US";
481
if (locales[browserLocale]) {
482
  setDefaultLocale(browserLocale);
483
}
484
```