npm-react-aria

1
# Internationalization
2

3
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.
4

5
## Capabilities
6

7
### I18n Provider
8

9
Provides internationalization context for the entire application.
10

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

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

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

35
### Locale Management
36

37
Provides current locale information and utilities.
38

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

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

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

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

73
### Date Formatting
74

75
Provides locale-aware date and time formatting.
76

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

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

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

104
**Usage Examples:**
105

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

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

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

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

143
### Number Formatting
144

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

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

156
**Usage Examples:**
157

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

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

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

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

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

203
### Text Collation
204

205
Provides locale-aware string comparison and sorting.
206

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

216
**Usage Examples:**
217

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

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

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

262
### Text Filtering
263

264
Provides locale-aware text filtering and searching.
265

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

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

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

295
### String Localization
296

297
Provides localized string formatting with interpolation.
298

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

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

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

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

325
**Usage Examples:**
326

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

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

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

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

366
### RTL Layout Support
367

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

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

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

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

403
**Usage Examples:**
404

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

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

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

442
### Calendar Systems
443

444
Support for different calendar systems across cultures.
445

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

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

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

468
## Types
469

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

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

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

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

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

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

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

524
**Supported Locales:**
525

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

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

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