0
# Intl MessageFormat
1

2
Intl MessageFormat is a TypeScript library that formats ICU Message strings with support for number, date, plural, and select placeholders to create localized messages. It provides comprehensive internationalization capabilities for JavaScript applications, supporting complex message patterns with built-in formatters and extensible configuration.
3

4
## Package Information
5

6
- **Package Name**: intl-messageformat
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install intl-messageformat`
10

11
## Core Imports
12

13
```typescript
14
import IntlMessageFormat from "intl-messageformat";
15
```
16

17
For named imports:
18

19
```typescript
20
import { IntlMessageFormat, FormatError, ErrorCode } from "intl-messageformat";
21
```
22

23
CommonJS:
24

25
```javascript
26
const IntlMessageFormat = require("intl-messageformat");
27
```
28

29
## Basic Usage
30

31
```typescript
32
import IntlMessageFormat from "intl-messageformat";
33

34
// Simple message formatting
35
const msg = new IntlMessageFormat('Hello {name}!', 'en-US');
36
console.log(msg.format({ name: 'John' })); // "Hello John!"
37

38
// Complex message with pluralization
39
const pluralMsg = new IntlMessageFormat(
40
  'You have {count, plural, =0 {no messages} one {# message} other {# messages}}.',
41
  'en-US'
42
);
43
console.log(pluralMsg.format({ count: 0 })); // "You have no messages."
44
console.log(pluralMsg.format({ count: 1 })); // "You have 1 message."
45
console.log(pluralMsg.format({ count: 5 })); // "You have 5 messages."
46

47
// Date and number formatting
48
const complexMsg = new IntlMessageFormat(
49
  'On {date, date, short} at {time, time, short}, you spent {amount, number, currency}.',
50
  'en-US',
51
  { number: { currency: { style: 'currency', currency: 'USD' } } }
52
);
53
const date = new Date();
54
console.log(complexMsg.format({ 
55
  date: date, 
56
  time: date, 
57
  amount: 42.50 
58
}));
59
```
60

61
## Architecture
62

63
Intl MessageFormat is built around several key components:
64

65
- **IntlMessageFormat Class**: Main formatter class that parses and formats ICU messages with locale support
66
- **AST Processing**: Parses ICU message strings into Abstract Syntax Trees for efficient formatting
67
- **Formatter Integration**: Built-in integration with Intl.NumberFormat, Intl.DateTimeFormat, and Intl.PluralRules
68
- **Error System**: Comprehensive error handling with specific error types for different failure modes
69
- **Extensible Formatters**: Customizable formatter functions and format configurations
70
- **Memoization**: Performance optimization through caching of formatters and parsed messages
71

72
## Capabilities
73

74
### Message Formatting
75

76
Core message formatting functionality that processes ICU message strings with variable substitution, pluralization, date/time formatting, and number formatting.
77

78
```typescript { .api }
79
class IntlMessageFormat {
80
  constructor(
81
    message: string | MessageFormatElement[],
82
    locales?: string | string[],
83
    overrideFormats?: Partial<Formats>,
84
    opts?: Options
85
  );
86
  
87
  format<T = void>(
88
    values?: Record<string, PrimitiveType | T | FormatXMLElementFn<T>>
89
  ): string | T | (string | T)[];
90
  
91
  formatToParts<T>(
92
    values?: Record<string, PrimitiveType | T | FormatXMLElementFn<T>>
93
  ): MessageFormatPart<T>[];
94
}
95
```
96

97
[Message Formatting](./message-formatting.md)
98

99
### Error Handling
100

101
Comprehensive error system for handling various formatting failures including missing values, invalid types, and missing Intl APIs.
102

103
```typescript { .api }
104
enum ErrorCode {
105
  MISSING_VALUE = 'MISSING_VALUE';
106
  INVALID_VALUE = 'INVALID_VALUE';
107
  MISSING_INTL_API = 'MISSING_INTL_API';
108
}
109

110
class FormatError extends Error {
111
  readonly code: ErrorCode;
112
  readonly originalMessage: string | undefined;
113
  constructor(msg: string, code: ErrorCode, originalMessage?: string);
114
}
115
```
116

117
[Error Handling](./error-handling.md)
118

119
### Formatters and Types
120

121
Formatting utilities and type definitions for number, date, time, and custom formatters with extensible configuration.
122

123
```typescript { .api }
124
interface Formatters {
125
  getNumberFormat(
126
    locals?: string | string[],
127
    opts?: NumberFormatOptions
128
  ): Intl.NumberFormat;
129
  getDateTimeFormat(
130
    ...args: ConstructorParameters<typeof Intl.DateTimeFormat>
131
  ): Intl.DateTimeFormat;
132
  getPluralRules(
133
    ...args: ConstructorParameters<typeof Intl.PluralRules>
134
  ): Intl.PluralRules;
135
}
136

137
interface Formats {
138
  number: Record<string, NumberFormatOptions>;
139
  date: Record<string, Intl.DateTimeFormatOptions>;
140
  time: Record<string, Intl.DateTimeFormatOptions>;
141
}
142
```
143

144
[Formatters and Types](./formatters-types.md)
145

146
## Types
147

148
```typescript { .api }
149
interface Options extends Omit<ParserOptions, 'locale'> {
150
  formatters?: Formatters;
151
}
152

153
interface MessageFormatPart<T> {
154
  type: PART_TYPE;
155
  value: string | T;
156
}
157

158
enum PART_TYPE {
159
  literal,
160
  object
161
}
162

163
type PrimitiveType = string | number | boolean | null | undefined | Date;
164

165
type FormatXMLElementFn<T, R = string | T | (string | T)[]> = (
166
  parts: Array<string | T>
167
) => R;
168

169
// From @formatjs/icu-messageformat-parser
170
interface ParserOptions {
171
  /** Whether to treat HTML/XML tags as string literal instead of parsing them as tag token */
172
  ignoreTag?: boolean;
173
  /** Should select, selectordinal, and plural arguments always include the other case clause */
174
  requiresOtherClause?: boolean;
175
  /** Whether to parse number/datetime skeleton into Intl format options */
176
  shouldParseSkeletons?: boolean;
177
  /** Capture location info in AST (default: false) */
178
  captureLocation?: boolean;
179
  /** Instance of Intl.Locale to resolve locale-dependent skeleton */
180
  locale?: Intl.Locale;
181
}
182
```