@messageformat/core

What is @messageformat/core?

@messageformat/core is a JavaScript library that provides tools for handling message formatting in applications. It supports ICU MessageFormat syntax, which allows for complex message formatting including pluralization, gender, and other locale-specific variations.

What are @messageformat/core's main functionalities?

Basic Message Formatting

This feature allows you to format basic messages with variable interpolation. The example shows how to create a message template and compile it with a variable.

const { MessageFormat } = require('@messageformat/core');
const mf = new MessageFormat('en');
const message = mf.compile('Hello, {name}!');
console.log(message({ name: 'Alice' })); // Output: Hello, Alice!

Pluralization

This feature supports pluralization based on the count of items. The example demonstrates how to handle singular and plural forms of a word based on the count.

const { MessageFormat } = require('@messageformat/core');
const mf = new MessageFormat('en');
const message = mf.compile('{count, plural, one {# item} other {# items}}');
console.log(message({ count: 1 })); // Output: 1 item
console.log(message({ count: 5 })); // Output: 5 items

Gender Formatting

This feature allows for gender-based message formatting. The example shows how to format messages differently based on the gender of the subject.

const { MessageFormat } = require('@messageformat/core');
const mf = new MessageFormat('en');
const message = mf.compile('{gender, select, male {He} female {She} other {They}} will respond soon.');
console.log(message({ gender: 'male' })); // Output: He will respond soon.
console.log(message({ gender: 'female' })); // Output: She will respond soon.

Custom Formatting

This feature allows you to define custom formatting functions. The example demonstrates how to add a custom formatter that converts text to uppercase.

const { MessageFormat } = require('@messageformat/core');
const mf = new MessageFormat('en');
mf.addFormat('uppercase', (v) => v.toUpperCase());
const message = mf.compile('This is {value, uppercase}');
console.log(message({ value: 'custom' })); // Output: This is CUSTOM

Other packages similar to @messageformat/core

intl-messageformat

intl-messageformat is a library for formatting messages based on the ICU MessageFormat standard. It provides similar functionality to @messageformat/core, including support for pluralization, gender, and other locale-specific variations. However, it is part of the larger FormatJS suite, which includes additional tools for internationalization.

i18next

i18next is a comprehensive internationalization framework for JavaScript. It supports message formatting, including pluralization and interpolation, but also offers features like language detection, translation management, and integration with various frameworks. It is more feature-rich compared to @messageformat/core, which focuses specifically on message formatting.

react-intl

react-intl is a library for internationalizing React applications. It provides components and APIs for formatting dates, numbers, and messages, including support for ICU MessageFormat. While it offers similar message formatting capabilities as @messageformat/core, it is specifically designed for use with React.

README

messageformat

The experience and subtlety of your program's text can be important. Messageformat is a mechanism for handling both pluralization and gender in your applications. It can also lead to much better translations, as it's designed to support all the languages included in the Unicode CLDR.

The ICU has an official guide for the format. Messageformat supports and extends all parts of the standard, with the exception of the deprecated ChoiceFormat.

There is a good slide-deck on Plural and Gender in Translated Messages by Markus Scherer and Mark Davis. But, again, remember that many of these problems apply even if you're only outputting english.

What problems does it solve?

Using messageformat, you can separate your code from your text formatting, while enabling much more humane expressions. In other words, you won't need to see this anymore in your output:

There are 1 results.
There are 2 result(s).
Number of results: 3.

On a more fundamental level, messageformat and its associated tools can help you 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.

What does it look like?

With this message:

const msgSrc = `{GENDER, select,
  male {He}
  female {She}
  other {They}
} found {RES, plural,
  =0 {no results}
  one {1 result}
  other {# results}
}.`;

You'll get these results:

const MessageFormat = require('@messageformat/core');
const mf = new MessageFormat('en');
const msg = mf.compile(msgSrc);

msg({ GENDER: 'male', RES: 1 }); // 'He found 1 result.'
msg({ GENDER: 'female', RES: 1 }); // 'She found 1 result.'
msg({ GENDER: 'male', RES: 0 }); // 'He found no results.'
msg({ RES: 2 }); // 'They found 2 results.'

Getting Started

npm install --save-dev @messageformat/core
npm install --save @messageformat/runtime

This includes the MessageFormat compiler and a runtime accessor class that provides a slightly nicer API for working with larger numbers of messages. Our Format Guide will help with the ICU MessageFormat Syntax, and the Usage Guide provides some options for integrating messageformat to be a part of your workflow around UI texts and translations.

---

Messageformat is an OpenJS Foundation project, and we follow its Code of Conduct.

Browser testing provided by: