0
# Formatting Utilities
1

2
The formatting utilities module provides standalone functions for date, time, number, and plural formatting. These functions offer direct access to Intl API-based formatting with locale support, performance optimizations through memoization, and consistent behavior across different environments.
3

4
## Capabilities
5

6
### Date Formatting
7

8
Format dates and times with locale-aware formatting and predefined size options.
9

10
```typescript { .api }
11
/**
12
 * Format a date using specified locales and options
13
 * @param locales - Locale(s) to use for formatting
14
 * @param value - Date to format (string or Date object)
15
 * @param format - Format options or predefined size
16
 * @returns Formatted date string
17
 */
18
function date(
19
  locales: Locales,
20
  value: string | Date,
21
  format?: Intl.DateTimeFormatOptions | DateTimeFormatSize
22
): string;
23

24
/**
25
 * Format a time using specified locales and options
26
 * @param locales - Locale(s) to use for formatting
27
 * @param value - Date/time to format (string or Date object)
28
 * @param format - Format options or predefined size
29
 * @returns Formatted time string
30
 */
31
function time(
32
  locales: Locales,
33
  value: string | Date,
34
  format?: Intl.DateTimeFormatOptions | DateTimeFormatSize
35
): string;
36

37
type DateTimeFormatSize = "short" | "default" | "long" | "full";
38
type Locales = string | string[];
39
```
40

41
**Usage Examples:**
42

43
```typescript
44
import { formats } from "@lingui/core";
45

46
const now = new Date();
47
const dateString = "2023-12-25T10:30:00Z";
48

49
// Basic date formatting
50
const shortDate = formats.date("en-US", now, "short");
51
// "12/25/23"
52

53
const longDate = formats.date("fr-FR", now, "long"); 
54
// "25 décembre 2023"
55

56
// Custom date formatting
57
const customDate = formats.date("de-DE", now, {
58
  weekday: "long",
59
  year: "numeric", 
60
  month: "long",
61
  day: "numeric"
62
});
63
// "Montag, 25. Dezember 2023"
64

65
// Time formatting
66
const shortTime = formats.time("en-US", now, "short");
67
// "10:30 AM"
68

69
const fullTime = formats.time("ja-JP", now, "full");
70
// "10時30分00秒 GMT"
71

72
// Multiple locale fallback
73
const multiLocale = formats.date(["pt-BR", "pt", "en"], now, "default");
74
```
75

76
### Number Formatting
77

78
Format numbers with locale-aware formatting including currency, percentages, and custom options.
79

80
```typescript { .api }
81
/**
82
 * Format a number using specified locales and options
83
 * @param locales - Locale(s) to use for formatting
84
 * @param value - Number to format
85
 * @param format - Intl.NumberFormat options
86
 * @returns Formatted number string
87
 */
88
function number(
89
  locales: Locales,
90
  value: number,
91
  format?: Intl.NumberFormatOptions
92
): string;
93
```
94

95
**Usage Examples:**
96

97
```typescript
98
import { formats } from "@lingui/core";
99

100
const price = 1234.56;
101
const percentage = 0.75;
102

103
// Basic number formatting
104
const basic = formats.number("en-US", price);
105
// "1,234.56"
106

107
const german = formats.number("de-DE", price);
108
// "1.234,56"
109

110
// Currency formatting
111
const usd = formats.number("en-US", price, {
112
  style: "currency",
113
  currency: "USD"
114
});
115
// "$1,234.56"
116

117
const euro = formats.number("fr-FR", price, {
118
  style: "currency", 
119
  currency: "EUR"
120
});
121
// "1 234,56 €"
122

123
// Percentage formatting
124
const percent = formats.number("en-US", percentage, {
125
  style: "percent"
126
});
127
// "75%"
128

129
// Scientific notation
130
const scientific = formats.number("en-US", 123456789, {
131
  notation: "scientific"
132
});
133
// "1.235E8"
134

135
// Custom precision
136
const precise = formats.number("en-US", price, {
137
  minimumFractionDigits: 3,
138
  maximumFractionDigits: 3
139
});
140
// "1,234.560"
141
```
142

143
### Plural Formatting
144

145
Handle pluralization using ICU plural rules with support for both cardinal and ordinal forms.
146

147
```typescript { .api }
148
/**
149
 * Format plurals using locale-specific plural rules
150
 * @param locales - Locale(s) to determine plural rules
151
 * @param ordinal - Whether to use ordinal (1st, 2nd) or cardinal (1, 2) rules
152
 * @param value - Numeric value to determine plural form
153
 * @param options - Plural form options with offset and rules
154
 * @returns Selected plural form string
155
 */
156
function plural(
157
  locales: Locales,
158
  ordinal: boolean,
159
  value: number,
160
  options: PluralOptions
161
): string;
162

163
interface PluralOptions {
164
  /** Offset for plural calculation (default: 0) */
165
  offset: number;
166
  /** Default/fallback form (required) */
167
  other: string;
168
  /** Specific LDML plural rules */
169
  [key: string]: Intl.LDMLPluralRule;
170
}
171
```
172

173
**Usage Examples:**
174

175
```typescript
176
import { formats } from "@lingui/core";
177

178
// Cardinal plurals (1, 2, 3...)
179
const cardinalEn = formats.plural("en", false, 1, {
180
  one: "1 item",
181
  other: "# items"
182
});
183
// "1 item"
184

185
const cardinalPl = formats.plural("pl", false, 2, {
186
  one: "1 przedmiot",
187
  few: "# przedmioty", 
188
  many: "# przedmiotów",
189
  other: "# przedmiotów"
190
});
191
// "2 przedmioty"
192

193
// Ordinal plurals (1st, 2nd, 3rd...)  
194
const ordinalEn = formats.plural("en", true, 21, {
195
  one: "#st",
196
  two: "#nd", 
197
  few: "#rd",
198
  other: "#th"
199
});
200
// "21st"
201

202
// With offset (useful for "Alice and 3 others")
203
const withOffset = formats.plural("en", false, 4, {
204
  offset: 1,
205
  "0": "Nobody else",
206
  "1": "Alice only",
207
  one: "Alice and 1 other",
208
  other: "Alice and # others"
209
});
210
// "Alice and 3 others"
211

212
// Exact matches override plural rules
213
const exactMatch = formats.plural("en", false, 0, {
214
  "0": "No items",
215
  one: "1 item",
216
  other: "# items"
217
});
218
// "No items"
219
```
220

221
### Default Locale
222

223
The default locale used as a fallback when locale arrays are provided.
224

225
```typescript { .api }
226
/**
227
 * Default locale constant used as fallback
228
 */
229
const defaultLocale: "en";
230
```
231

232
**Usage Examples:**
233

234
```typescript
235
import { formats } from "@lingui/core";
236

237
console.log(formats.defaultLocale); // "en"
238

239
// Default locale is automatically added to locale arrays
240
const result = formats.date(["fr-CA", "fr"], new Date());
241
// Equivalent to: formats.date(["fr-CA", "fr", "en"], new Date())
242
```
243

244
## Performance Optimizations
245

246
All formatting functions use memoization to cache Intl formatters for improved performance:
247

248
```typescript
249
// Internal caching mechanism (not exposed)
250
// Multiple calls with same parameters reuse cached formatters
251
const formatter1 = formats.number("en-US", 123, { style: "currency", currency: "USD" });
252
const formatter2 = formats.number("en-US", 456, { style: "currency", currency: "USD" });
253
// Second call reuses the cached Intl.NumberFormat instance
254
```
255

256
## Integration with I18n Class
257

258
The I18n class uses these formatting utilities internally but provides simpler interfaces:
259

260
```typescript
261
import { setupI18n } from "@lingui/core";
262

263
const i18n = setupI18n({ locale: "en-US" });
264

265
// I18n method (uses current locale automatically)
266
const price1 = i18n.number(1234.56, { style: "currency", currency: "USD" });
267

268
// Direct formatting utility (explicit locale)
269
const price2 = formats.number("en-US", 1234.56, { style: "currency", currency: "USD" });
270

271
// Both produce the same result: "$1,234.56"
272
```
273

274
## Locale Support
275

276
All formatting functions support:
277

278
- **Single locales**: `"en-US"`, `"fr-FR"`, `"ja-JP"`
279
- **Locale arrays**: `["pt-BR", "pt", "en"]` with automatic fallback
280
- **BCP 47 language tags**: Full Unicode locale identifier support
281
- **Automatic fallback**: Invalid locales fall back to `"en"`
282

283
The formatting utilities provide the foundation for all locale-aware formatting in @lingui/core, ensuring consistent behavior and optimal performance across all internationalization operations.