icu-message

Parse an ICU MessageFormat string into an AST.


Package	`@vizejs/composable/icu-message`
Own the source	`vize lib pull composable:icu-message`
Runtime exports	`parseMessage`, `createMessageFormatter`, `formatMessage`
Gzip budget	3840 B

Usage

import { parseMessage, createMessageFormatter, formatMessage } from "@vizejs/composable/icu-message";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`parseMessage`	i18n	experimental	safe	stable	none	web, server, worker, native, desktop, terminal	—	—
`createMessageFormatter`	i18n	experimental	safe	stable	none	web, server, worker, native, desktop, terminal	`Intl`	`parseMessage`
`formatMessage`	i18n	experimental	safe	stable	none	web, server, worker, native, desktop, terminal	`Intl`	`createMessageFormatter`

API

`parseMessage`

Parse an ICU MessageFormat string into an AST. Supports simple arguments, number/date/time with an optional style, plural and selectordinal (with offset: and =N cases), select, nesting, # inside plural cases, and apostrophe quoting ('' is a literal apostrophe; '{…}' is literal text). Pure and deterministic.

function parseMessage(message: string): MessageNode[]

parseMessage("{n, plural, one {# item} other {# items}}");

`createMessageFormatter`

Create a caching formatter for one locale. Parsed messages and Intl formatters are cached inside the returned object only (no module state), so one formatter per request or per i18n instance keeps server rendering isolated.

function createMessageFormatter( locale: string, options: FormatMessageOptions = {}, ): MessageFormatter

const formatter = createMessageFormatter("en");
formatter.format("{n, plural, one {# file} other {# files}}", { n: 3 }); // "3 files"

`formatMessage`

Format one ICU message with typed parameters. Parameters are checked against the message literal at compile time via MessageParams. For repeated formatting prefer createMessageFormatter, which caches parsing and Intl objects. Deterministic: date/time arguments use timeZone (UTC by default).

function formatMessage<const Message extends string>( locale: string, message: Message, params: MessageParams<Message>, options: FormatMessageOptions = {}, ): string

formatMessage("en", "Hello {name}!", { name: "Ada" }); // "Hello Ada!"

Types

`MessageSyntaxError`

Thrown by parseMessage for malformed ICU messages.

Member	Type	Description
`code`	`MessageSyntaxErrorCode`	Stable machine-readable code.
`offset`	`number`	Character offset of the problem.

`FormatMessageOptions`

Options for formatMessage and createMessageFormatter.

Member	Type	Description
`timeZone`?	`string`	IANA time zone for `date` and `time` arguments. Fixed by default so server and client render identically.
`numberFormats`?	`Readonly<Record<string, Intl.NumberFormatOptions>>`	Named `number` styles usable as `{n, number, name}`.
`dateTimeFormats`?	`Readonly<Record<string, Intl.DateTimeFormatOptions>>`	Named `date`/`time` styles usable as `{d, date, name}`.

`MessageFormatter`

Formats parsed messages for one locale, caching Intl objects.

Member	Type	Description
`locale`	`string`	Locale the formatter renders in.
`format`	`( message: string \| readonly MessageNode[], params?: Readonly<Record<string, unknown>>, ) => string`	Render a message source or pre-parsed nodes.