0
# I18n Interface
1

2
The I18n class is the core component of @lingui/core, providing comprehensive internationalization capabilities including message translation, locale management, and event-driven locale switching.
3

4
## Capabilities
5

6
### Creating I18n Instances
7

8
Factory function for creating configured I18n instances.
9

10
```typescript { .api }
11
/**
12
 * Creates a new I18n instance with optional configuration
13
 * @param params - Configuration options for the I18n instance
14
 * @returns New I18n instance
15
 */
16
function setupI18n(params?: I18nProps): I18n;
17

18
interface I18nProps {
19
  /** Initial locale to activate */
20
  locale?: Locale;
21
  /** List of fallback locales for formatting */
22
  locales?: Locales;
23
  /** Message catalogs for all locales */
24
  messages?: AllMessages;
25
  /** @deprecated Locale data (plurals are now automatic) */
26
  localeData?: AllLocaleData;
27
  /** Missing message handler - string or function */
28
  missing?: string | ((locale: string, id: string) => string);
29
}
30
```
31

32
**Usage Examples:**
33

34
```typescript
35
import { setupI18n } from "@lingui/core";
36

37
// Basic setup
38
const i18n = setupI18n({
39
  locale: "en",
40
  messages: {
41
    en: { "Hello": "Hello" },
42
    es: { "Hello": "Hola" }
43
  }
44
});
45

46
// Setup with missing message handler
47
const i18n = setupI18n({
48
  locale: "en",
49
  missing: (locale, id) => `Missing translation: ${id} (${locale})`
50
});
51
```
52

53
### I18n Class
54

55
Main internationalization class providing translation and locale management.
56

57
```typescript { .api }
58
class I18n extends EventEmitter<Events> {
59
  constructor(params: I18nProps);
60
  
61
  /** Current active locale */
62
  readonly locale: Locale;
63
  /** Active locales list for formatting fallbacks */
64
  readonly locales?: Locales;
65
  /** Messages for the current locale */
66
  readonly messages: Messages;
67
  /** @deprecated Locale data (automatic plurals) */
68
  readonly localeData: LocaleData;
69
}
70

71
type Events = {
72
  change: () => void;
73
  missing: (event: MissingMessageEvent) => void;
74
};
75
```
76

77
### Translation Methods
78

79
Core translation functionality supporting multiple message formats.
80

81
```typescript { .api }
82
/**
83
 * Translate a message descriptor
84
 * @param descriptor - Message descriptor with id, values, etc.
85
 * @returns Translated and formatted message
86
 */
87
_(descriptor: MessageDescriptor): string;
88

89
/**
90
 * Translate a message by ID with optional values and options
91
 * @param id - Message ID to translate
92
 * @param values - Placeholder values for interpolation
93
 * @param options - Translation options including format overrides
94
 * @returns Translated and formatted message
95
 */
96
_(id: string, values?: Values, options?: MessageOptions): string;
97

98
/**
99
 * Alias for the _ method
100
 */
101
t: I18n["_"];
102
```
103

104
**Usage Examples:**
105

106
```typescript
107
// Using message descriptors
108
const msg = i18n._({
109
  id: "welcome",
110
  values: { name: "Alice" },
111
  message: "Welcome {name}!"
112
});
113

114
// Using string ID
115
const greeting = i18n._("hello", { name: "Bob" });
116

117
// Using t alias
118
const farewell = i18n.t("goodbye");
119

120
// With formatting options
121
const price = i18n._("price", { amount: 99.99 }, {
122
  formats: { amount: { style: "currency", currency: "USD" } }
123
});
124
```
125

126
### Message Loading
127

128
Methods for loading and managing message catalogs.
129

130
```typescript { .api }
131
/**
132
 * Load messages for all locales
133
 * @param allMessages - Object mapping locales to message catalogs
134
 */
135
load(allMessages: AllMessages): void;
136

137
/**
138
 * Load messages for a specific locale
139
 * @param locale - Target locale
140
 * @param messages - Message catalog for the locale
141
 */
142
load(locale: Locale, messages: Messages): void;
143

144
/**
145
 * Load messages and activate locale in one operation
146
 * @param options - Locale, locales, and messages to load and activate
147
 */
148
loadAndActivate(options: LoadAndActivateOptions): void;
149

150
interface LoadAndActivateOptions {
151
  /** Locale to activate */
152
  locale: Locale;
153
  /** Optional fallback locales */
154
  locales?: Locales;
155
  /** Compiled message catalog */
156
  messages: Messages;
157
}
158
```
159

160
**Usage Examples:**
161

162
```typescript
163
// Load all messages at once
164
i18n.load({
165
  en: { "hello": "Hello", "goodbye": "Goodbye" },
166
  es: { "hello": "Hola", "goodbye": "Adiós" },
167
  fr: { "hello": "Bonjour", "goodbye": "Au revoir" }
168
});
169

170
// Load messages for specific locale
171
i18n.load("de", { "hello": "Hallo", "goodbye": "Auf Wiedersehen" });
172

173
// Load and activate in one call
174
i18n.loadAndActivate({
175
  locale: "it",
176
  messages: { "hello": "Ciao", "goodbye": "Arrivederci" }
177
});
178
```
179

180
### Locale Management
181

182
Methods for activating and managing locales.
183

184
```typescript { .api }
185
/**
186
 * Activate a locale for translations
187
 * @param locale - Locale to activate
188
 * @param locales - Optional fallback locales for formatting
189
 */
190
activate(locale: Locale, locales?: Locales): void;
191
```
192

193
**Usage Examples:**
194

195
```typescript
196
// Activate single locale
197
i18n.activate("fr");
198

199
// Activate with fallbacks
200
i18n.activate("fr-CA", ["fr-CA", "fr", "en"]);
201
```
202

203
### Message Compilation
204

205
Runtime message compilation for development and dynamic scenarios.
206

207
```typescript { .api }
208
/**
209
 * Set a message compiler for runtime compilation
210
 * @param compiler - Function to compile ICU messages
211
 * @returns I18n instance for chaining
212
 */
213
setMessagesCompiler(compiler: MessageCompiler): I18n;
214

215
type MessageCompiler = (message: string) => CompiledMessage;
216
```
217

218
**Usage Examples:**
219

220
```typescript
221
import { compileMessage } from "@lingui/message-utils/compileMessage";
222

223
// Enable runtime compilation (typically for development)
224
i18n.setMessagesCompiler(compileMessage);
225
```
226

227
### Locale Data Loading (Deprecated)
228

229
**@deprecated** Plural rules are now automatically loaded from Intl.PluralRules.
230

231
```typescript { .api }
232
/**
233
 * @deprecated Load locale data for pluralization (no longer needed)
234
 * @param allLocaleData - All locale data object
235
 */
236
loadLocaleData(allLocaleData: AllLocaleData): void;
237

238
/**
239
 * @deprecated Load locale data for a specific locale (no longer needed)  
240
 * @param locale - Target locale
241
 * @param localeData - Locale-specific data
242
 */
243
loadLocaleData(locale: Locale, localeData: LocaleData): void;
244
```
245

246
### Formatting Methods
247

248
Built-in formatting for common data types.
249

250
```typescript { .api }
251
/**
252
 * Format a date using current locale(s)
253
 * @param value - Date to format (string or Date object)
254
 * @param format - Intl.DateTimeFormat options
255
 * @returns Formatted date string
256
 */
257
date(value: string | Date, format?: Intl.DateTimeFormatOptions): string;
258

259
/**
260
 * Format a number using current locale(s)
261
 * @param value - Number to format
262
 * @param format - Intl.NumberFormat options
263
 * @returns Formatted number string
264
 */
265
number(value: number, format?: Intl.NumberFormatOptions): string;
266
```
267

268
**Usage Examples:**
269

270
```typescript
271
// Format dates
272
const shortDate = i18n.date(new Date(), { dateStyle: "short" });
273
const longDate = i18n.date("2023-12-25", { 
274
  weekday: "long", 
275
  year: "numeric", 
276
  month: "long", 
277
  day: "numeric" 
278
});
279

280
// Format numbers
281
const currency = i18n.number(1234.56, { 
282
  style: "currency", 
283
  currency: "EUR" 
284
});
285
const percentage = i18n.number(0.85, { 
286
  style: "percent" 
287
});
288
```
289

290
### Event Handling
291

292
The I18n class extends EventEmitter to provide reactive locale and message management.
293

294
```typescript { .api }
295
// Inherited from EventEmitter
296
on(event: "change", listener: () => void): () => void;
297
on(event: "missing", listener: (event: MissingMessageEvent) => void): () => void;
298
removeListener(event: "change" | "missing", listener: Function): void;
299
emit(event: "change" | "missing", ...args: any[]): void;
300
```
301

302
**Usage Examples:**
303

304
```typescript
305
// Listen for locale changes
306
const unsubscribe = i18n.on("change", () => {
307
  console.log("Locale changed to:", i18n.locale);
308
  // Update UI, rerender components, etc.
309
});
310

311
// Listen for missing translations
312
i18n.on("missing", ({ locale, id }) => {
313
  console.warn(`Missing translation for "${id}" in locale "${locale}"`);
314
  // Log to analytics, show developer warnings, etc.
315
});
316

317
// Cleanup listener
318
unsubscribe();
319
```
320

321
## Default I18n Instance
322

323
@lingui/core provides a default pre-configured I18n instance for simple use cases.
324

325
```typescript { .api }
326
/**
327
 * Default I18n instance created with setupI18n()
328
 * Ready to use but requires locale activation and message loading
329
 */
330
const i18n: I18n;
331
```
332

333
**Usage Examples:**
334

335
```typescript
336
import { i18n } from "@lingui/core";
337

338
// Use the default instance
339
i18n.load("en", { "hello": "Hello world!" });
340
i18n.activate("en");
341
const message = i18n._("hello");
342
```