messageformat

The experience and subtlety of your program’s text is important. The messageformat project provides a complete set of tools for handling all the messages of your application, for both front-end and back-end environments; for both runtime and build-time use. It’s built around the ICU MessageFormat standard and supports all the languages included in the Unicode CLDR, but it can be just as useful if you’re dealing with only one of them.

ICU MessageFormat is a mechanism for handling both pluralization and gender in your applications. This JavaScript project supports and extends all parts of the official Java/C++ implementation, with the exception of the deprecated ChoiceFormat. In addition to compiling messages into JavaScript functions, it also provides tooling for making their use easy during both the build and runtime of your site or application.

Note: This is the documentation for messageformat v3. Documentation for messageformat v2 is available separately.

What problems does it solve?

Using messageformat, you can separate your code from your text formatting, while enabling much more humane expressions. You can build an effective workflow for UI texts and translations, keeping message sources in human-friendly formats, compiling them into JavaScript during your build phase, and making them easy to use from your application code.

Messageformat provides the tools for both starting a new project, as well as using the messages and workflows you already have set up. As a developer, it gives you an easy-to-use API that’s future-proof and won’t lock you in, while letting you avoid the limitations that a hand-rolled system will inevitably bring. As a translator, it’ll conform to your existing workflows without reinventing the wheel.

What does it look like?

Most messages are simply text, and so in MessageFormat will also appear as just that. At the top level, the only special characters are {}, which surround variables that are to be replaced, along with case selectors and formatter function calls.

To include the value of a variable in a message, surround it with braces:

Hello, {username}!

This will require the parameter username to be defined when the message is being formatted.

The greatest benefit of MessageFormat comes from its selector support, both for numerical values

{count, plural, =0{Found no results} one{Found one result} other{Found # results} }

as well as generic selectors

{gender, select, male{He said} female{She said} other{They said} }

along with formatter functions

The task was {done, number, percent} complete at {t, time}.

For more information on the available selectors, formatters, and other details, please see our Format Guide.

Why it’s the right choice for you

Fundamentally, this project is built around @messageformat/core, a compiler that turns ICU MessageFormat input into JavaScript. The core feature that makes ours different from others is that it can do its work during your application build, by compiling a set of source messages into the string representation of an ES module.

By doing this work during the build, supporting more complex features such as date and number skeletons does not increase the runtime size or complexity of the messages. This also means that we can support a large variety of source file formats (including JSON, YAML, Java properties, and gettext .po files) at no additional cost, optionally even converting other formats to MessageFormat before processing them.

For library developers, all of the various API levels from message parsing to React tooling are separately available, with clear and minimal dependencies. In particular, our parser is already either used by or has inspired the implementations of a number of other message formatting libraries’ parsers.

It’s also good to note that messageformat is a project of the OpenJS Foundation, and has no commercial entity behind it. This means that all parts of the project are open source, and that we have no interest in creating any lock-in for you – except for what’s achieved by the quality of our code.

Our long-term goal is to make significant parts of this project obsolete by working with the Unicode MessageFormat Working Group and ECMA-402 to define the next evolution of the standard, and to eventually bring that to JavaScript and its Intl object.

Getting Started

See the Usage Guide for the tools that you’ll want to integrate with your build and runtime code, and the Format Guide to get you started with ICU MessageFormat and our extensions to it. On GitHub, you’ll find us at messageformat/messageformat and on npm as @messageformat.