0
# React Aria I18n
1

2
React Aria I18n provides comprehensive internationalization support for React applications through hooks and components that handle locale-specific formatting, text processing, and accessibility features. It leverages browser Intl APIs for performance without large locale data downloads, supports over 30 languages with built-in RTL support, and integrates seamlessly with React Aria's accessibility ecosystem.
3

4
## Package Information
5

6
- **Package Name**: @react-aria/i18n
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @react-aria/i18n`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  I18nProvider, 
16
  useLocale, 
17
  useDateFormatter, 
18
  useNumberFormatter,
19
  useLocalizedStringFormatter
20
} from "@react-aria/i18n";
21
```
22

23
For CommonJS:
24

25
```javascript
26
const { 
27
  I18nProvider, 
28
  useLocale, 
29
  useDateFormatter, 
30
  useNumberFormatter 
31
} = require("@react-aria/i18n");
32
```
33

34
Server-side imports:
35

36
```typescript
37
import { PackageLocalizationProvider } from "@react-aria/i18n/server";
38
```
39

40
## Basic Usage
41

42
```typescript
43
import { I18nProvider, useLocale, useDateFormatter } from "@react-aria/i18n";
44

45
function App() {
46
  return (
47
    <I18nProvider locale="es-ES">
48
      <DateDisplay />
49
    </I18nProvider>
50
  );
51
}
52

53
function DateDisplay() {
54
  const { locale, direction } = useLocale();
55
  const formatter = useDateFormatter({ 
56
    dateStyle: "full", 
57
    timeStyle: "short" 
58
  });
59
  
60
  return (
61
    <div dir={direction}>
62
      <p>Locale: {locale}</p>
63
      <p>Date: {formatter.format(new Date())}</p>
64
    </div>
65
  );
66
}
67
```
68

69
## Architecture
70

71
React Aria I18n is built around several key components:
72

73
- **Context System**: `I18nProvider` manages locale state with automatic RTL detection
74
- **Formatting Hooks**: Locale-aware hooks for dates, numbers, lists, and strings
75
- **Utility Functions**: RTL detection and locale processing utilities
76
- **Server Support**: SSR-compatible components for localization injection
77
- **Performance**: Automatic caching and browser Intl API integration
78

79
## Capabilities
80

81
### Core Context and Locale Management
82

83
Context provider and locale detection for establishing internationalization context throughout the application.
84

85
```typescript { .api }
86
interface I18nProviderProps {
87
  children: ReactNode;
88
  locale?: string;
89
}
90

91
function I18nProvider(props: I18nProviderProps): JSX.Element;
92

93
interface Locale {
94
  locale: string;
95
  direction: Direction;
96
}
97

98
function useLocale(): Locale;
99
```
100

101
[Context and Locale](./context-locale.md)
102

103
### Date and Time Formatting
104

105
Locale-aware date and time formatting with calendar support and automatic locale updates.
106

107
```typescript { .api }
108
interface DateFormatterOptions extends Intl.DateTimeFormatOptions {
109
  calendar?: string;
110
}
111

112
function useDateFormatter(options?: DateFormatterOptions): DateFormatter;
113
```
114

115
[Date and Time Formatting](./date-time-formatting.md)
116

117
### Number and List Formatting
118

119
Numeric formatting and list presentation for different locales and cultural contexts.
120

121
```typescript { .api }
122
function useNumberFormatter(options?: NumberFormatOptions): Intl.NumberFormat;
123

124
function useListFormatter(options?: Intl.ListFormatOptions): Intl.ListFormat;
125
```
126

127
[Number and List Formatting](./number-list-formatting.md)
128

129
### String Localization and Search
130

131
Advanced string handling including localization, collation, and locale-aware text filtering.
132

133
```typescript { .api }
134
function useLocalizedStringFormatter<K extends string = string, T extends LocalizedString = string>(
135
  strings: LocalizedStrings<K, T>,
136
  packageName?: string
137
): LocalizedStringFormatter<K, T>;
138

139
interface Filter {
140
  startsWith(string: string, substring: string): boolean;
141
  endsWith(string: string, substring: string): boolean;
142
  contains(string: string, substring: string): boolean;
143
}
144

145
function useFilter(options?: Intl.CollatorOptions): Filter;
146

147
function useCollator(options?: Intl.CollatorOptions): Intl.Collator;
148
```
149

150
[String Localization and Search](./string-localization.md)
151

152
### Server-Side Rendering Support
153

154
Components and utilities for server-side localization with client hydration support.
155

156
```typescript { .api }
157
interface PackageLocalizationProviderProps {
158
  locale: string;
159
  strings: PackageLocalizedStrings;
160
  nonce?: string;
161
}
162

163
function PackageLocalizationProvider(props: PackageLocalizationProviderProps): JSX.Element | null;
164

165
function getPackageLocalizationScript(locale: string, strings: PackageLocalizedStrings): string;
166
```
167

168
[Server-Side Rendering Support](./server-support.md)
169

170
## Utility Types
171

172
```typescript { .api }
173
type Direction = "ltr" | "rtl";
174

175
type FormatMessage = (key: string, variables?: {[key: string]: any}) => string;
176

177
type PackageLocalizedStrings = {
178
  [packageName: string]: Record<string, LocalizedString>;
179
};
180

181
// Re-exported from @internationalized packages
182
type LocalizedStrings<K extends string = string, T extends LocalizedString = string> = Record<string, Record<K, T>>;
183
type LocalizedString = string | LocalizedStringParams;
184
type NumberFormatOptions = Intl.NumberFormatOptions;
185
```
186

187
## Utility Functions
188

189
```typescript { .api }
190
/**
191
 * Determines if a locale is read right to left using Intl.Locale
192
 * @param localeString - BCP47 language code
193
 * @returns true if locale is RTL, false otherwise
194
 */
195
function isRTL(localeString: string): boolean;
196

197
/**
198
 * Gets the default browser/system locale
199
 * @returns Locale object with detected locale and direction
200
 */
201
function getDefaultLocale(): Locale;
202

203
/**
204
 * Hook that returns the current browser/system language and updates when it changes
205
 * @returns Locale object that updates on language change events
206
 */
207
function useDefaultLocale(): Locale;
208
```