0
# Internationalization
1

2
Comprehensive internationalization support with locale-aware formatting, RTL layout, and localization utilities. React Aria provides built-in support for over 30 languages with proper cultural adaptations.
3

4
## Capabilities
5

6
### I18n Provider
7

8
Provides internationalization context for the entire application.
9

10
```typescript { .api }
11
/**
12
 * I18n provider component that sets up locale context
13
 * @param props - I18n provider configuration
14
 * @returns Provider component
15
 */
16
function I18nProvider(props: I18nProviderProps): JSX.Element;
17

18
interface I18nProviderProps {
19
  /** Children to provide context to */
20
  children: ReactNode;
21
  /** Current locale */
22
  locale?: string;
23
  /** Map of localized strings */
24
  strings?: LocalizedStrings;
25
}
26

27
interface LocalizedStrings {
28
  [locale: string]: {
29
    [key: string]: string;
30
  };
31
}
32
```
33

34
### Locale Management
35

36
Provides current locale information and utilities.
37

38
```typescript { .api }
39
/**
40
 * Get current locale information
41
 * @returns Locale information
42
 */
43
function useLocale(): {
44
  /** Current locale string (e.g., 'en-US') */
45
  locale: string;
46
  /** Text direction for the locale */
47
  direction: 'ltr' | 'rtl';
48
};
49

50
/**
51
 * Check if current locale is right-to-left
52
 * @param locale - Locale to check (defaults to current)
53
 * @returns Whether locale is RTL
54
 */
55
function isRTL(locale?: string): boolean;
56

57
/**
58
 * Get the text direction for a locale
59
 * @param locale - Locale to check
60
 * @returns Text direction
61
 */
62
function getTextDirection(locale: string): 'ltr' | 'rtl';
63

64
/**
65
 * Get the reading direction for a locale
66
 * @param locale - Locale to check
67
 * @returns Reading direction
68
 */
69
function getReadingDirection(locale: string): 'ltr' | 'rtl';
70
```
71

72
### Date Formatting
73

74
Provides locale-aware date and time formatting.
75

76
```typescript { .api }
77
/**
78
 * Provides locale-aware date formatting
79
 * @param options - Date formatting options
80
 * @returns Date formatter instance
81
 */
82
function useDateFormatter(options?: DateFormatterOptions): DateFormatter;
83

84
interface DateFormatterOptions extends Intl.DateTimeFormatOptions {
85
  /** Calendar system to use */
86
  calendar?: string;
87
}
88

89
interface DateFormatter {
90
  /** Format a date */
91
  format(date: Date): string;
92
  /** Format a date to parts */
93
  formatToParts(date: Date): Intl.DateTimeFormatPart[];
94
  /** Format a date range */
95
  formatRange(startDate: Date, endDate: Date): string;
96
  /** Format a date range to parts */
97
  formatRangeToParts(startDate: Date, endDate: Date): Intl.DateTimeFormatPart[];
98
  /** Get supported locales */
99
  resolvedOptions(): Intl.ResolvedDateTimeFormatOptions;
100
}
101
```
102

103
**Usage Examples:**
104

105
```typescript
106
import { useDateFormatter } from "react-aria";
107

108
function DateDisplay({ date }) {
109
  const formatter = useDateFormatter({ 
110
    year: 'numeric',
111
    month: 'long', 
112
    day: 'numeric'
113
  });
114
  
115
  return <span>{formatter.format(date)}</span>;
116
}
117

118
// Relative time formatting
119
function RelativeTime({ date }) {
120
  const formatter = useDateFormatter({ 
121
    year: 'numeric',
122
    month: 'short',
123
    day: 'numeric',
124
    hour: 'numeric',
125
    minute: 'numeric'
126
  });
127
  
128
  return <time dateTime={date.toISOString()}>{formatter.format(date)}</time>;
129
}
130

131
// Date range formatting
132
function DateRange({ startDate, endDate }) {
133
  const formatter = useDateFormatter({
134
    month: 'short',
135
    day: 'numeric'
136
  });
137
  
138
  return <span>{formatter.formatRange(startDate, endDate)}</span>;
139
}
140
```
141

142
### Number Formatting
143

144
Provides locale-aware number, currency, and unit formatting.
145

146
```typescript { .api }
147
/**
148
 * Provides locale-aware number formatting
149
 * @param options - Number formatting options
150
 * @returns Number formatter instance
151
 */
152
function useNumberFormatter(options?: Intl.NumberFormatOptions): Intl.NumberFormat;
153
```
154

155
**Usage Examples:**
156

157
```typescript
158
import { useNumberFormatter } from "react-aria";
159

160
// Currency formatting
161
function Price({ amount, currency = 'USD' }) {
162
  const formatter = useNumberFormatter({
163
    style: 'currency',
164
    currency
165
  });
166
  
167
  return <span>{formatter.format(amount)}</span>;
168
}
169

170
// Percentage formatting
171
function Percentage({ value }) {
172
  const formatter = useNumberFormatter({
173
    style: 'percent',
174
    minimumFractionDigits: 1
175
  });
176
  
177
  return <span>{formatter.format(value)}</span>;
178
}
179

180
// Unit formatting
181
function Distance({ value, unit = 'kilometer' }) {
182
  const formatter = useNumberFormatter({
183
    style: 'unit',
184
    unit,
185
    unitDisplay: 'long'
186
  });
187
  
188
  return <span>{formatter.format(value)}</span>;
189
}
190

191
// Compact notation
192
function LargeNumber({ value }) {
193
  const formatter = useNumberFormatter({
194
    notation: 'compact',
195
    compactDisplay: 'short'
196
  });
197
  
198
  return <span>{formatter.format(value)}</span>;
199
}
200
```
201

202
### Text Collation
203

204
Provides locale-aware string comparison and sorting.
205

206
```typescript { .api }
207
/**
208
 * Provides locale-aware string collation
209
 * @param options - Collation options
210
 * @returns Collator instance
211
 */
212
function useCollator(options?: Intl.CollatorOptions): Intl.Collator;
213
```
214

215
**Usage Examples:**
216

217
```typescript
218
import { useCollator } from "react-aria";
219

220
// Sorting with proper locale collation
221
function SortedList({ items }) {
222
  const collator = useCollator({ 
223
    numeric: true,
224
    sensitivity: 'base'
225
  });
226
  
227
  const sortedItems = [...items].sort((a, b) => 
228
    collator.compare(a.name, b.name)
229
  );
230
  
231
  return (
232
    <ul>
233
      {sortedItems.map(item => (
234
        <li key={item.id}>{item.name}</li>
235
      ))}
236
    </ul>
237
  );
238
}
239

240
// Case-insensitive search
241
function SearchResults({ items, query }) {
242
  const collator = useCollator({
243
    sensitivity: 'base',
244
    ignorePunctuation: true
245
  });
246
  
247
  const filteredItems = items.filter(item =>
248
    collator.compare(item.name.toLowerCase(), query.toLowerCase()) === 0
249
  );
250
  
251
  return (
252
    <ul>
253
      {filteredItems.map(item => (
254
        <li key={item.id}>{item.name}</li>
255
      ))}
256
    </ul>
257
  );
258
}
259
```
260

261
### Text Filtering
262

263
Provides locale-aware text filtering and searching.
264

265
```typescript { .api }
266
/**
267
 * Provides locale-aware text filtering
268
 * @param options - Filter options
269
 * @returns Filter function
270
 */
271
function useFilter(options?: FilterOptions): Filter;
272

273
interface FilterOptions {
274
  /** Sensitivity level for matching */
275
  sensitivity?: 'base' | 'accent' | 'case' | 'variant';
276
  /** Whether to ignore punctuation */
277
  ignorePunctuation?: boolean;
278
  /** Numeric sorting */
279
  numeric?: boolean;
280
  /** Usage hint for optimization */
281
  usage?: 'sort' | 'search';
282
}
283

284
interface Filter {
285
  /** Check if text starts with query */
286
  startsWith(text: string, query: string): boolean;
287
  /** Check if text ends with query */
288
  endsWith(text: string, query: string): boolean;
289
  /** Check if text contains query */
290
  contains(text: string, query: string): boolean;
291
}
292
```
293

294
### String Localization
295

296
Provides localized string formatting with interpolation.
297

298
```typescript { .api }
299
/**
300
 * Provides localized string formatting
301
 * @param strings - Localized strings map
302
 * @returns String formatter function
303
 */
304
function useLocalizedStringFormatter(strings: LocalizedStrings): LocalizedStringFormatter;
305

306
/**
307
 * Provides message formatting with ICU syntax
308
 * @param locale - Target locale
309
 * @returns Message formatter function
310
 */
311
function useMessageFormatter(locale: string): FormatMessage;
312

313
interface LocalizedStringFormatter {
314
  /** Format a localized string with interpolation */
315
  format(key: string, values?: Record<string, any>): string;
316
}
317

318
type FormatMessage = (
319
  descriptor: { id: string; defaultMessage?: string; description?: string },
320
  values?: Record<string, any>
321
) => string;
322
```
323

324
**Usage Examples:**
325

326
```typescript
327
import { useLocalizedStringFormatter, useMessageFormatter } from "react-aria";
328

329
// Basic string localization
330
const strings = {
331
  'en-US': {
332
    'welcome': 'Welcome, {name}!',
333
    'items_count': 'You have {count} items'
334
  },
335
  'es-ES': {
336
    'welcome': '¡Bienvenido, {name}!',
337
    'items_count': 'Tienes {count} elementos'
338
  }
339
};
340

341
function Welcome({ userName, itemCount }) {
342
  const { format } = useLocalizedStringFormatter(strings);
343
  
344
  return (
345
    <div>
346
      <h1>{format('welcome', { name: userName })}</h1>
347
      <p>{format('items_count', { count: itemCount })}</p>
348
    </div>
349
  );
350
}
351

352
// ICU message formatting
353
function PluralMessage({ count }) {
354
  const formatMessage = useMessageFormatter('en-US');
355
  
356
  const message = formatMessage({
357
    id: 'item_count',
358
    defaultMessage: '{count, plural, =0 {No items} =1 {One item} other {# items}}'
359
  }, { count });
360
  
361
  return <span>{message}</span>;
362
}
363
```
364

365
### RTL Layout Support
366

367
Utilities for handling right-to-left layout and styling.
368

369
```typescript { .api }
370
/**
371
 * Get appropriate style properties for RTL layouts
372
 * @param props - Style properties to transform
373
 * @param locale - Target locale
374
 * @returns Transformed style properties
375
 */
376
function getRTLStyles(props: React.CSSProperties, locale?: string): React.CSSProperties;
377

378
/**
379
 * Transform logical properties for RTL
380
 * @param property - CSS property name
381
 * @param value - CSS property value
382
 * @param direction - Text direction
383
 * @returns Transformed property and value
384
 */
385
function transformRTLProperty(
386
  property: string, 
387
  value: string | number, 
388
  direction: 'ltr' | 'rtl'
389
): { property: string; value: string | number };
390

391
/**
392
 * Get the start/end properties for a direction
393
 * @param direction - Text direction
394
 * @returns Object with start and end property mappings
395
 */
396
function getDirectionalProperties(direction: 'ltr' | 'rtl'): {
397
  start: 'left' | 'right';
398
  end: 'left' | 'right';
399
};
400
```
401

402
**Usage Examples:**
403

404
```typescript
405
import { useLocale, getRTLStyles } from "react-aria";
406

407
// RTL-aware component styling
408
function DirectionalBox({ children }) {
409
  const { direction } = useLocale();
410
  
411
  const styles = getRTLStyles({
412
    paddingInlineStart: 16,
413
    paddingInlineEnd: 8,
414
    marginInlineStart: 'auto',
415
    borderInlineStartWidth: 2
416
  });
417
  
418
  return (
419
    <div style={styles} dir={direction}>
420
      {children}
421
    </div>
422
  );
423
}
424

425
// Conditional RTL styling
426
function FlexContainer({ children }) {
427
  const { direction } = useLocale();
428
  
429
  return (
430
    <div style={{
431
      display: 'flex',
432
      justifyContent: direction === 'rtl' ? 'flex-end' : 'flex-start',
433
      textAlign: direction === 'rtl' ? 'right' : 'left'
434
    }}>
435
      {children}
436
    </div>
437
  );
438
}
439
```
440

441
### Calendar Systems
442

443
Support for different calendar systems across cultures.
444

445
```typescript { .api }
446
/**
447
 * Get supported calendar systems
448
 * @returns Array of supported calendar identifiers
449
 */
450
function getSupportedCalendars(): string[];
451

452
/**
453
 * Get the default calendar for a locale
454
 * @param locale - Target locale
455
 * @returns Default calendar identifier
456
 */
457
function getDefaultCalendar(locale: string): string;
458

459
/**
460
 * Check if a calendar is supported
461
 * @param calendar - Calendar identifier
462
 * @returns Whether calendar is supported
463
 */
464
function isCalendarSupported(calendar: string): boolean;
465
```
466

467
## Types
468

469
```typescript { .api }
470
type Locale = string;
471

472
type Direction = 'ltr' | 'rtl';
473

474
interface LocaleInfo {
475
  /** Locale identifier */
476
  locale: Locale;
477
  /** Text direction */
478
  direction: Direction;
479
  /** Language code */
480
  language: string;
481
  /** Country/region code */
482
  region?: string;
483
  /** Script code */
484
  script?: string;
485
}
486

487
interface DateFormatterOptions extends Intl.DateTimeFormatOptions {
488
  /** Calendar system */
489
  calendar?: string;
490
  /** Number system */
491
  numberingSystem?: string;
492
  /** Time zone */
493
  timeZone?: string;
494
  /** Hour cycle */
495
  hourCycle?: 'h11' | 'h12' | 'h23' | 'h24';
496
}
497

498
interface LocalizedStrings {
499
  [locale: string]: {
500
    [key: string]: string | ((values: Record<string, any>) => string);
501
  };
502
}
503

504
interface CollationOptions extends Intl.CollatorOptions {
505
  /** Locale to use for collation */
506
  locale?: string;
507
  /** Custom collation rules */
508
  rules?: string;
509
}
510

511
interface FilterOptions {
512
  /** Sensitivity for matching */
513
  sensitivity?: 'base' | 'accent' | 'case' | 'variant';
514
  /** Whether to ignore punctuation */
515
  ignorePunctuation?: boolean;
516
  /** Numeric comparison */
517
  numeric?: boolean;
518
  /** Usage optimization */
519
  usage?: 'sort' | 'search';
520
}
521
```
522

523
**Supported Locales:**
524

525
React Aria includes built-in support for the following locales:
526

527
- Arabic (ar-AE)
528
- Bulgarian (bg-BG)
529
- Czech (cs-CZ)
530
- German (de-DE)
531
- Greek (el-GR)
532
- English (en-US)
533
- Spanish (es-ES)
534
- Finnish (fi-FI)
535
- French (fr-FR)
536
- Hebrew (he-IL)
537
- Croatian (hr-HR)
538
- Hungarian (hu-HU)
539
- Italian (it-IT)
540
- Japanese (ja-JP)
541
- Korean (ko-KR)
542
- Lithuanian (lt-LT)
543
- Latvian (lv-LV)
544
- Norwegian Bokmål (nb-NO)
545
- Dutch (nl-NL)
546
- Polish (pl-PL)
547
- Portuguese (pt-BR)
548
- Romanian (ro-RO)
549
- Russian (ru-RU)
550
- Slovak (sk-SK)
551
- Slovenian (sl-SI)
552
- Serbian (sr-SP)
553
- Swedish (sv-SE)
554
- Turkish (tr-TR)
555
- Ukrainian (uk-UA)
556
- Chinese Simplified (zh-CN)
557
- Chinese Traditional (zh-TW)
558

559
Each locale includes proper translations for accessibility strings, date/time formatting, and cultural adaptations.