or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

error-handling.mdformatters-types.mdindex.mdmessage-formatting.md
tile.json

tessl/npm-intl-messageformat

Formats ICU Message strings with number, date, plural, and select placeholders to create localized messages.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/intl-messageformat@10.7.x

To install, run

npx @tessl/cli install tessl/npm-intl-messageformat@10.7.0

index.mddocs/

Intl MessageFormat

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.

Package Information

  • Package Name: intl-messageformat
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install intl-messageformat

Core Imports

import IntlMessageFormat from "intl-messageformat";

For named imports:

import { IntlMessageFormat, FormatError, ErrorCode } from "intl-messageformat";

CommonJS:

const IntlMessageFormat = require("intl-messageformat");

Basic Usage

import IntlMessageFormat from "intl-messageformat";

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

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

// Date and number formatting
const complexMsg = new IntlMessageFormat(
  'On {date, date, short} at {time, time, short}, you spent {amount, number, currency}.',
  'en-US',
  { number: { currency: { style: 'currency', currency: 'USD' } } }
);
const date = new Date();
console.log(complexMsg.format({ 
  date: date, 
  time: date, 
  amount: 42.50 
}));

Architecture

Intl MessageFormat is built around several key components:

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

Capabilities

Message Formatting

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

class IntlMessageFormat {
  constructor(
    message: string | MessageFormatElement[],
    locales?: string | string[],
    overrideFormats?: Partial<Formats>,
    opts?: Options
  );
  
  format<T = void>(
    values?: Record<string, PrimitiveType | T | FormatXMLElementFn<T>>
  ): string | T | (string | T)[];
  
  formatToParts<T>(
    values?: Record<string, PrimitiveType | T | FormatXMLElementFn<T>>
  ): MessageFormatPart<T>[];
}

Message Formatting

Error Handling

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

enum ErrorCode {
  MISSING_VALUE = 'MISSING_VALUE';
  INVALID_VALUE = 'INVALID_VALUE';
  MISSING_INTL_API = 'MISSING_INTL_API';
}

class FormatError extends Error {
  readonly code: ErrorCode;
  readonly originalMessage: string | undefined;
  constructor(msg: string, code: ErrorCode, originalMessage?: string);
}

Error Handling

Formatters and Types

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

interface Formatters {
  getNumberFormat(
    locals?: string | string[],
    opts?: NumberFormatOptions
  ): Intl.NumberFormat;
  getDateTimeFormat(
    ...args: ConstructorParameters<typeof Intl.DateTimeFormat>
  ): Intl.DateTimeFormat;
  getPluralRules(
    ...args: ConstructorParameters<typeof Intl.PluralRules>
  ): Intl.PluralRules;
}

interface Formats {
  number: Record<string, NumberFormatOptions>;
  date: Record<string, Intl.DateTimeFormatOptions>;
  time: Record<string, Intl.DateTimeFormatOptions>;
}

Formatters and Types

Types

interface Options extends Omit<ParserOptions, 'locale'> {
  formatters?: Formatters;
}

interface MessageFormatPart<T> {
  type: PART_TYPE;
  value: string | T;
}

enum PART_TYPE {
  literal,
  object
}

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

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

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