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
```