0
# @lingui/core
1

2
@lingui/core is the essential internationalization (i18n) library that provides core functionality for JavaScript applications requiring multilingual support. It offers comprehensive API for message formatting using the ICU MessageFormat standard, enabling developers to handle complex pluralization, number formatting, date formatting, and context-sensitive translations with a lightweight runtime and zero dependencies.
3

4
## Package Information
5

6
- **Package Name**: @lingui/core
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @lingui/core`
10

11
## Core Imports
12

13
```typescript
14
import { setupI18n, I18n, i18n } from "@lingui/core";
15
import { formats } from "@lingui/core";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { setupI18n, I18n, i18n, formats } = require("@lingui/core");
22
```
23

24
Macro imports (compile-time):
25

26
```typescript
27
import { t, plural, select, defineMessage, msg } from "@lingui/core/macro";
28
```
29

30
## Basic Usage
31

32
```typescript
33
import { setupI18n } from "@lingui/core";
34

35
// Create and configure I18n instance
36
const i18n = setupI18n({
37
  locale: "en",
38
  messages: {
39
    en: {
40
      "Hello {name}": "Hello {name}",
41
      "greeting": "Welcome!"
42
    },
43
    es: {
44
      "Hello {name}": "Hola {name}",
45
      "greeting": "¡Bienvenido!"
46
    }
47
  }
48
});
49

50
// Activate a locale
51
i18n.activate("es");
52

53
// Translate messages
54
const greeting = i18n._("greeting"); // "¡Bienvenido!"
55
const welcome = i18n._("Hello {name}", { name: "María" }); // "Hola María"
56

57
// Format numbers and dates
58
const price = i18n.number(1234.56, { style: "currency", currency: "EUR" });
59
const today = i18n.date(new Date(), { dateStyle: "medium" });
60
```
61

62
## Architecture
63

64
@lingui/core is built around several key components:
65

66
- **I18n Class**: Central internationalization manager providing translation, formatting, and locale management
67
- **Macro System**: Compile-time translation helpers for optimal performance and developer experience
68
- **Message Compilation**: ICU MessageFormat parsing and compilation for efficient runtime execution
69
- **Event System**: Reactive locale changes and missing message handling
70
- **Formatting Engine**: Intl API-based number, date, and plural formatting with memoization
71
- **Type Safety**: Full TypeScript integration with comprehensive type definitions
72

73
## Capabilities
74

75
### Core I18n Interface
76

77
Central internationalization class providing translation methods, locale management, and message loading. The primary interface for all i18n operations.
78

79
```typescript { .api }
80
function setupI18n(params?: I18nProps): I18n;
81

82
class I18n extends EventEmitter<Events> {
83
  constructor(params: I18nProps);
84
  readonly locale: Locale;
85
  readonly locales?: Locales;
86
  readonly messages: Messages;
87
  
88
  _(descriptor: MessageDescriptor): string;
89
  _(id: string, values?: Values, options?: MessageOptions): string;
90
  t: I18n["_"];
91
  
92
  load(allMessages: AllMessages): void;
93
  load(locale: Locale, messages: Messages): void;
94
  loadAndActivate(options: LoadAndActivateOptions): void;
95
  activate(locale: Locale, locales?: Locales): void;
96
  
97
  date(value: string | Date, format?: Intl.DateTimeFormatOptions): string;
98
  number(value: number, format?: Intl.NumberFormatOptions): string;
99
}
100

101
const i18n: I18n;
102
```
103

104
[I18n Interface](./i18n.md)
105

106
### Macro Functions
107

108
Compile-time translation macros that optimize messages during build time for maximum runtime performance. These functions are transformed by Babel during compilation.
109

110
```typescript { .api }
111
function t(descriptor: MacroMessageDescriptor): string;
112
function t(literals: TemplateStringsArray, ...placeholders: MessagePlaceholder[]): string;
113
function t(i18n: I18n): {
114
  (literals: TemplateStringsArray, ...placeholders: any[]): string;
115
  (descriptor: MacroMessageDescriptor): string;
116
};
117

118
function plural(
119
  value: number | string | LabeledExpression<number | string>,
120
  options: ChoiceOptions
121
): string;
122

123
function selectOrdinal(
124
  value: number | string | LabeledExpression<number | string>,
125
  options: ChoiceOptions
126
): string;
127

128
function select(
129
  value: string | LabeledExpression<string>,
130
  choices: SelectOptions
131
): string;
132

133
function defineMessage(descriptor: MacroMessageDescriptor): MessageDescriptor;
134
function defineMessage(literals: TemplateStringsArray, ...placeholders: MessagePlaceholder[]): MessageDescriptor;
135

136
const msg: typeof defineMessage;
137

138
function ph(def: LabeledExpression<string | number>): string;
139
```
140

141
[Macro Functions](./macros.md)
142

143
### Formatting Utilities
144

145
Standalone formatting functions for dates, times, numbers, and plurals. These utilities provide direct access to Intl API-based formatting with locale support and memoization.
146

147
```typescript { .api }
148
declare const formats: {
149
  date(locales: Locales, value: string | Date, format?: Intl.DateTimeFormatOptions | DateTimeFormatSize): string;
150
  time(locales: Locales, value: string | Date, format?: Intl.DateTimeFormatOptions | DateTimeFormatSize): string;
151
  number(locales: Locales, value: number, format?: Intl.NumberFormatOptions): string;
152
  plural(locales: Locales, ordinal: boolean, value: number, options: PluralOptions): string;
153
  defaultLocale: string;
154
};
155

156
type DateTimeFormatSize = "short" | "default" | "long" | "full";
157
```
158

159
[Formatting Utilities](./formatting.md)
160

161
## Types
162

163
Core types exported from the main @lingui/core package:
164

165
```typescript { .api }
166
type Locale = string;
167
type Locales = Locale | Locale[];
168

169
interface MessageDescriptor {
170
  id: string;
171
  comment?: string;
172
  message?: string;
173
  values?: Record<string, unknown>;
174
}
175

176
interface MessageOptions {
177
  message?: string;
178
  formats?: Formats;
179
  comment?: string;
180
}
181

182
type Messages = Record<string, UncompiledMessage | CompiledMessage>;
183
type AllMessages = Record<Locale, Messages>;
184

185
/** @deprecated Plurals automatically used from Intl.PluralRules */
186
interface LocaleData {
187
  plurals?: (n: number, ordinal?: boolean) => ReturnType<Intl.PluralRules["select"]>;
188
}
189

190
/** @deprecated Plurals automatically used from Intl.PluralRules */
191
type AllLocaleData = Record<Locale, LocaleData>;
192

193
type Values = Record<string, unknown>;
194
type Formats = Record<string, Intl.DateTimeFormatOptions | Intl.NumberFormatOptions>;
195

196
type UncompiledMessage = string;
197
type CompiledMessage = any; // From @lingui/message-utils
198

199
interface MissingMessageEvent {
200
  locale: Locale;
201
  id: string;
202
}
203

204
type MessageCompiler = (message: string) => CompiledMessage;
205
```