0
# Internationalization
1

2
React Intl type definitions and locale management functions for multi-language Umi applications. Provides formatting components and utility functions for date, time, number, and message internationalization.
3

4
## Capabilities
5

6
### Message Formatting
7

8
Core message formatting functionality for internationalized text.
9

10
```typescript { .api }
11
/**
12
 * Format a message using ICU message format
13
 * @param messageDescriptor - Message descriptor with id and default message
14
 * @param values - Variable values for message interpolation
15
 * @returns Formatted message string
16
 */
17
function formatMessage(
18
  messageDescriptor: MessageDescriptor,
19
  values?: { [key: string]: MessageValue }
20
): string;
21

22
/**
23
 * Format HTML message with embedded HTML tags
24
 * @param messageDescriptor - Message descriptor with id and default message  
25
 * @param values - Variable values for message interpolation
26
 * @returns Formatted HTML message string
27
 */
28
function formatHTMLMessage(
29
  messageDescriptor: MessageDescriptor,
30
  values?: { [key: string]: MessageValue }
31
): string;
32

33
/**
34
 * Message descriptor interface for defining translatable messages
35
 */
36
interface MessageDescriptor {
37
  id: string;
38
  description?: string;
39
  defaultMessage?: string;
40
}
41

42
type MessageValue = string | number | boolean | Date | null | undefined;
43
```
44

45
**Usage Examples:**
46

47
```typescript
48
import { formatMessage, MessageDescriptor } from 'umi-types';
49

50
// Basic message formatting
51
const welcomeMessage: MessageDescriptor = {
52
  id: 'welcome.message',
53
  defaultMessage: 'Welcome to {appName}!',
54
  description: 'Welcome message shown to users',
55
};
56

57
const formattedMessage = formatMessage(welcomeMessage, {
58
  appName: 'My App',
59
});
60
// Result: "Welcome to My App!"
61

62
// Complex message with pluralization
63
const itemCountMessage: MessageDescriptor = {
64
  id: 'items.count',
65
  defaultMessage: '{count, plural, =0 {No items} one {# item} other {# items}}',
66
};
67

68
const countMessage = formatMessage(itemCountMessage, { count: 5 });
69
// Result: "5 items"
70

71
// Date and time in messages
72
const lastUpdatedMessage: MessageDescriptor = {
73
  id: 'last.updated',
74
  defaultMessage: 'Last updated on {date, date, medium} at {date, time, short}',
75
};
76

77
const updatedMessage = formatMessage(lastUpdatedMessage, {
78
  date: new Date(),
79
});
80
```
81

82
### Date and Time Formatting
83

84
Date and time formatting utilities with locale support.
85

86
```typescript { .api }
87
/**
88
 * Format a date according to locale and options
89
 * @param value - Date value to format
90
 * @param options - Date formatting options
91
 * @returns Formatted date string
92
 */
93
function formatDate(value: DateSource, options?: DateTimeFormatProps): string;
94

95
/**
96
 * Format a time according to locale and options
97
 * @param value - Date value to format as time
98
 * @param options - Time formatting options
99
 * @returns Formatted time string
100
 */
101
function formatTime(value: DateSource, options?: DateTimeFormatProps): string;
102

103
/**
104
 * Format relative time (e.g., "2 hours ago")
105
 * @param value - Date value to format relatively
106
 * @param options - Relative formatting options
107
 * @returns Formatted relative time string
108
 */
109
function formatRelative(
110
  value: DateSource,
111
  options?: FormattedRelativeProps & { now?: any }
112
): string;
113

114
type DateSource = Date | string | number;
115

116
interface DateTimeFormatProps extends Intl.DateTimeFormatOptions {
117
  format?: string;
118
}
119

120
interface FormattedRelativeProps {
121
  units?: 'second' | 'minute' | 'hour' | 'day' | 'month' | 'year';
122
  style?: 'best-fit' | 'numeric';
123
  format?: string;
124
  updateInterval?: number;
125
  initialNow?: any;
126
}
127

128
interface FormattedPluralBase {
129
  style?: 'cardinal' | 'ordinal';
130
}
131

132
interface FormattedPluralProps extends FormattedPluralBase {
133
  other?: any;
134
  zero?: any;
135
  one?: any;
136
  two?: any;
137
  few?: any;
138
  many?: any;
139
}
140
```
141

142
**Usage Examples:**
143

144
```typescript
145
import { formatDate, formatTime, formatRelative } from 'umi-types';
146

147
const now = new Date();
148
const yesterday = new Date(Date.now() - 24 * 60 * 60 * 1000);
149

150
// Date formatting
151
const shortDate = formatDate(now, { 
152
  year: 'numeric', 
153
  month: 'short', 
154
  day: 'numeric' 
155
});
156
// Result: "Sep 5, 2025"
157

158
const longDate = formatDate(now, { 
159
  weekday: 'long',
160
  year: 'numeric', 
161
  month: 'long', 
162
  day: 'numeric' 
163
});
164
// Result: "Thursday, September 5, 2025"
165

166
// Time formatting
167
const shortTime = formatTime(now, { 
168
  hour: '2-digit', 
169
  minute: '2-digit' 
170
});
171
// Result: "15:30"
172

173
const longTime = formatTime(now, { 
174
  hour: '2-digit', 
175
  minute: '2-digit', 
176
  second: '2-digit',
177
  timeZoneName: 'short'
178
});
179
// Result: "15:30:45 UTC"
180

181
// Relative time formatting
182
const relativeTime = formatRelative(yesterday);
183
// Result: "1 day ago"
184

185
const relativeHours = formatRelative(new Date(Date.now() - 2 * 60 * 60 * 1000), {
186
  units: 'hour'
187
});
188
// Result: "2 hours ago"
189
```
190

191
### Number Formatting
192

193
Number formatting utilities with locale-aware formatting.
194

195
```typescript { .api }
196
/**
197
 * Format a number according to locale and options
198
 * @param value - Number value to format
199
 * @param options - Number formatting options
200
 * @returns Formatted number string
201
 */
202
function formatNumber(value: number, options?: FormattedNumberProps): string;
203

204
/**
205
 * Format plural forms based on number value
206
 * @param value - Number value for plural determination
207
 * @param options - Plural formatting options
208
 * @returns Plural form key
209
 */
210
function formatPlural(
211
  value: number,
212
  options?: FormattedPluralBase
213
): keyof FormattedPluralProps;
214

215
interface FormattedNumberProps extends Intl.NumberFormatOptions {
216
  format?: string;
217
}
218

219
interface FormattedPluralBase {
220
  style?: 'cardinal' | 'ordinal';
221
}
222

223
interface FormattedPluralProps extends FormattedPluralBase {
224
  other?: any;
225
  zero?: any;
226
  one?: any;
227
  two?: any;
228
  few?: any;
229
  many?: any;
230
}
231
```
232

233
**Usage Examples:**
234

235
```typescript
236
import { formatNumber, formatPlural } from 'umi-types';
237

238
// Basic number formatting
239
const price = formatNumber(1234.56, {
240
  style: 'currency',
241
  currency: 'USD',
242
});
243
// Result: "$1,234.56"
244

245
const percentage = formatNumber(0.1234, {
246
  style: 'percent',
247
  minimumFractionDigits: 2,
248
});
249
// Result: "12.34%"
250

251
const largeNumber = formatNumber(1234567, {
252
  notation: 'compact',
253
  compactDisplay: 'short',
254
});
255
// Result: "1.2M"
256

257
// Plural formatting
258
const pluralForm = formatPlural(5, { style: 'cardinal' });
259
// Result: "other"
260

261
const ordinalForm = formatPlural(3, { style: 'ordinal' });
262
// Result: "few" (for "3rd")
263
```
264

265
### React Components
266

267
React components for declarative internationalization in JSX.
268

269
```typescript { .api }
270
/**
271
 * React component for formatting dates
272
 */
273
class FormattedDate extends React.Component<FormattedDateProps> {}
274

275
interface FormattedDateProps extends DateTimeFormatProps {
276
  value: DateSource;
277
  children?: (formattedDate: string) => React.ReactNode;
278
}
279

280
/**
281
 * React component for formatting times
282
 */
283
class FormattedTime extends React.Component<FormattedTimeProps> {}
284

285
interface FormattedTimeProps extends DateTimeFormatProps {
286
  value: DateSource;
287
  children?: (formattedDate: string) => React.ReactNode;
288
}
289

290
/**
291
 * React component for formatting relative times
292
 */
293
class FormattedRelative extends React.Component<
294
  FormattedRelativeProps & {
295
    value: DateSource;
296
    children?: (formattedRelative: string) => React.ReactNode;
297
  }
298
> {}
299

300
/**
301
 * React component for formatting messages
302
 */
303
class FormattedMessage extends React.Component<FormattedMessageProps> {}
304

305
interface FormattedMessageProps extends MessageDescriptor {
306
  values?: { [key: string]: MessageValue | JSX.Element };
307
  tagName?: string;
308
  children?: (...formattedMessage: Array<string | JSX.Element>) => React.ReactNode;
309
}
310

311
/**
312
 * React component for formatting HTML messages
313
 */
314
class FormattedHTMLMessage extends React.Component<FormattedMessageProps> {}
315

316
/**
317
 * React component for formatting numbers
318
 */
319
class FormattedNumber extends React.Component<
320
  FormattedNumberProps & {
321
    value: number;
322
    children?: (formattedNumber: string) => React.ReactNode;
323
  }
324
> {}
325

326
/**
327
 * React component for formatting plurals
328
 */
329
class FormattedPlural extends React.Component<
330
  FormattedPluralProps & {
331
    value: number;
332
    children?: (formattedPlural: React.ReactNode) => React.ReactNode;
333
  }
334
> {}
335
```
336

337
**Usage Examples:**
338

339
```typescript
340
import React from 'react';
341
import { 
342
  FormattedMessage, 
343
  FormattedDate, 
344
  FormattedTime, 
345
  FormattedNumber,
346
  FormattedRelative 
347
} from 'umi-types';
348

349
// Message component usage
350
const WelcomeMessage = ({ userName }: { userName: string }) => (
351
  <FormattedMessage
352
    id="welcome.user"
353
    defaultMessage="Welcome, {name}!"
354
    values={{ name: <strong>{userName}</strong> }}
355
  />
356
);
357

358
// Date and time components
359
const DateTimeDisplay = ({ date }: { date: Date }) => (
360
  <div>
361
    <p>
362
      Date: <FormattedDate value={date} year="numeric" month="long" day="numeric" />
363
    </p>
364
    <p>
365
      Time: <FormattedTime value={date} hour="2-digit" minute="2-digit" />
366
    </p>
367
    <p>
368
      Relative: <FormattedRelative value={date} />
369
    </p>
370
  </div>
371
);
372

373
// Number formatting
374
const PriceDisplay = ({ price }: { price: number }) => (
375
  <FormattedNumber
376
    value={price}
377
    style="currency"
378
    currency="USD"
379
  />
380
);
381

382
// Advanced message with render prop
383
const ItemCount = ({ count }: { count: number }) => (
384
  <FormattedMessage
385
    id="items.count"
386
    defaultMessage="{count, plural, =0 {No items} one {# item} other {# items}}"
387
    values={{ count }}
388
  >
389
    {(formattedMessage) => (
390
      <span className="item-count">{formattedMessage}</span>
391
    )}
392
  </FormattedMessage>
393
);
394

395
// HTML message component
396
const RichTextMessage = () => (
397
  <FormattedHTMLMessage
398
    id="rich.message"
399
    defaultMessage="Click <a href='#'>here</a> to <strong>continue</strong>"
400
  />
401
);
402
```
403

404
### Locale Management
405

406
Locale switching and management utilities.
407

408
```typescript { .api }
409
/**
410
 * Set the current locale and optionally reload the page
411
 * @param lang - Language/locale code (e.g., 'en-US', 'zh-CN')
412
 * @param reloadPage - Whether to reload the page after locale change
413
 */
414
function setLocale(lang: string, reloadPage?: boolean): void;
415

416
/**
417
 * Get the current locale setting
418
 * @returns Current locale code
419
 */
420
function getLocale(): string;
421

422
/**
423
 * Get current timestamp in milliseconds
424
 * @returns Current timestamp
425
 */
426
function now(): number;
427

428
/**
429
 * Handle internationalization errors
430
 * @param error - Error message
431
 */
432
function onError(error: string): void;
433
```
434

435
**Usage Examples:**
436

437
```typescript
438
import { setLocale, getLocale } from 'umi-types';
439

440
// Get current locale
441
const currentLocale = getLocale();
442
console.log('Current locale:', currentLocale); // e.g., "en-US"
443

444
// Switch locale without page reload
445
setLocale('zh-CN', false);
446

447
// Switch locale with page reload
448
setLocale('en-US', true);
449

450
// Locale switcher component
451
const LocaleSwitcher = () => {
452
  const current = getLocale();
453
  
454
  const handleLocaleChange = (locale: string) => {
455
    setLocale(locale, false);
456
  };
457
  
458
  return (
459
    <select value={current} onChange={(e) => handleLocaleChange(e.target.value)}>
460
      <option value="en-US">English</option>
461
      <option value="zh-CN">中文</option>
462
    </select>
463
  );
464
};
465

466
// Plugin locale management
467
export default (api: IApi) => {
468
  // Add locale files
469
  api.addLocales({
470
    'en-US': {
471
      'my.plugin.title': 'My Plugin',
472
      'my.plugin.description': 'This is my awesome plugin',
473
    },
474
    'zh-CN': {
475
      'my.plugin.title': '我的插件',
476
      'my.plugin.description': '这是我的超棒插件',
477
    },
478
  });
479
  
480
  // Use formatted messages
481
  api.log.info(
482
    formatMessage({
483
      id: 'my.plugin.loaded',
484
      defaultMessage: 'Plugin loaded successfully',
485
    })
486
  );
487
};
488
```
489

490
### Utility Functions
491

492
Additional utility functions for internationalization.
493

494
```typescript { .api }
495
/**
496
 * Internationalization interface with formatting methods
497
 */
498
type PickIntl = Pick<
499
  typeof intl,
500
  | 'FormattedDate'
501
  | 'FormattedTime'
502
  | 'FormattedRelative'
503
  | 'FormattedNumber'
504
  | 'FormattedPlural'
505
  | 'FormattedMessage'
506
  | 'FormattedHTMLMessage'
507
  | 'formatMessage'
508
  | 'formatHTMLMessage'
509
  | 'formatDate'
510
  | 'formatTime'
511
  | 'formatRelative'
512
  | 'formatNumber'
513
  | 'formatPlural'
514
>;
515

516
type IIntl<T = PickIntl> = { [key in keyof T]: T[key] } & typeof intl.formatMessage;
517
```
518

519
This interface provides access to all React Intl functionality through a unified API for use in Umi plugins and applications.