tiny alternative to intl-messageformat
npm install intl-messageformat-tiny> tiny alternative to intl-messageformat
This project aims to provide a formatter with small bundle-size with similar
functionality as [intl-messageformat][] provides.
Bundle-size minified is ~3kB compared to ~47kB
šš½ Credits go to all contributors of [intl-messageformat][].
Table of Contents
* format
* Simple Argument
* Formatted Argument
* type number
* type plural
* type select
* type selectordinal
* type date
* type time
* nested types
* License
Format is a function with 2-3 arguments in the form of format(message, values, locale).
- message is the message with brackets {} which is being formatted
- values is the object of values used for the later formatting
- locale is the optional locale being used to correctly internationalize the
message. This defaults to en.
The message syntax follows [icu-syntax][] with exceptions.
Offers a cached version to increase performance.
``js
import { cached } from 'intl-messageformat-tiny'
const format = cached()
// 1st parses format
format('Hello {who}!', {who: 'everyone'})
// 2nd use parsed format from cache
format('Hello {who}!', {who: 'world'})
`
You can use a {key} argument for placing a value into the message. The key is
looked up in the input data, and the string is interpolated with its value.
`js
import { format } from 'intl-messageformat-tiny'
format('Hello!', {})
// Hello!
format('Hello {who}!', {})
// Hello {who}!
format('Hello {who}!', {who: 'everyone'})
// Hello everyone!
format('Hello {who}, who {emotion} this!', {who: 'everyone', emotion: 'likes'})
// Hello everyone, who likes this!
format('Hello {0}, who {1} this!', {0: 'everyone', 1: 'likes'})
// Hello everyone, who likes this!
`
You use a {key, type, format} argument to format messages according to their
type.
The elements of the argument are:
- key is where in the input data to find the datatype
- is how to interpret the value (see below)format
- is optional, and is a further refinement on how to display that type of data
format:
- percent shows value as percentageinteger
- shows value as integercurrency
- shows value as currency[option]/value
- all options from Intl.NumberFormat()
`js
format('I have {numCats, number} cats.', {numCats: 5})
// I have 5 cats.
format('Almost {pctBlack, number, percent} of them are black.', {pctBlack: 0.415})
// Almost 42% of them are black.
format('{black, number, integer} of them are black.', {black: 2.0749})
// 2 of them are black.
format('The price of this bagel is {num, number, signDisplay/always currency currency/GBP}',
{ num: 5.12 }, 'en-UK)
// The price of this bagel is +Ā£5.12
`
The {key, plural, matches} is used to choose output based on the pluralization
rules of the current locale.
The match is a literal value and is matched to one of these plural categories.
Not all languages use all plural categories.
- zero : This category is used for languages that have grammar specializedone
specifically for zero number of items. (Examples are Arabic and Latvian.)
- : This category is used for languages that have grammar specializedtwo
specifically for one item. Many languages, but not all, use this plural
category. (Many popular Asian languages, such as Chinese and Japanese, do not
use this category.)
- : This category is used for languages that have grammar specializedfew
specifically for two items. (Examples are Arabic and Welsh.)
- : This category is used for languages that have grammar specializedmany
specifically for a small number of items. For some languages this is used for
2-4 items, for some 3-10 items, and other languages have even more complex
rules.
- : This category is used for languages that have grammar specializedother
specifically for a larger number of items. (Examples are Arabic, Polish, and
Russian.)
- : This category is used if the value doesn't match one of the other=value
plural categories. Note that this is used for "plural" for languages (such as
English) that have a simple "singular" versus "plural" dichotomy.
- : This is used to match a specific value regardless of the plural
categories of the current locale.
> [!warning]
> other is required and shall be at the last matching position.
> [!note]
> You may also want to set the correct locale!
`js
const message =
'You have {itemCount, plural, ' +
'=0 {no items} ' +
'one {one item} ' +
'other {{itemCount} items}' +
'}.
format(message, {itemCount: 0}, 'en')
// You have no items.
format(message, {itemCount: 1}, 'en')
// You have one item.
format(message, {itemCount: 12}, 'en')
// You have 12 items.
`
with offset (needs #):
`js
const message =
'You have {itemCount, plural, offset:2' +
'=0 {no items} ' +
'one {one item} ' +
'other {# items}' +
'}.
format(message, {itemCount: 12}, 'en')
// You have 10 items.
`
The {key, select, matches} is used to choose output by matching a value to onekey
of many choices. (It is similar to the switch statement) The is looked up
in the input data.
> [!warning]
> other is required and shall be at the last matching position.
> [!note]
> You may also want to set the correct locale!
`js
const message =
'{gender, select, male {He} female {She} other {They}} will respond shortly.'
format(message, { gender: 'female' }, 'en')
// She will respond shortly.
format(message, { gender: 'foobar' }, 'en')
// They will respond shortly.
`
The {key, selectordinal, matches} is used to choose output based on the{plural}
ordinal pluralization rules (1st, 2nd, 3rd, etc.) of the required locale. It is
very similar to the format above except that the value is mapped to an
ordinal plural category.
> [!warning]
> other is required and shall be at the last matching position.
> [!note]
> You may also want to set the correct locale!
`js
const message =
"It's my cat's {year, selectordinal, one {#st} two {#nd} few {#rd} other {#th}} birthday!"
format(message, {year: 1}, 'en')
// It's my cat's 1st birthday!
format(message, {year: 2}, 'en')
// It's my cat's 2nd birthday!
format(message, {year: 2}, 'en')
// It's my cat's 2nd birthday!
format(message, {year: 3}, 'en')
// It's my cat's 3rd birthday!
format(message, {year: 7}, 'en')
// It's my cat's 7th birthday!
`
This type is used to format dates in a way that is sensitive to the locale. It
understands the following values for the optional format element of the
argument:
- short is used to format dates in the shortest possible waymedium
- is used to format dates with short textual representation of the monthlong
- is used to format dates with long textual representation of the monthfull
- is used to format dates with the most detail[option]/value
- all options from Intl.DateTimeFormat()
> [!note]
> Don't forget to set the locale!
`js
const start = new Date('2022-01-02T12:34:56Z')
format('Sale begins {start, date}', { start }, 'en-UK'))
// Sale begins 02/01/2022
format('Sale begins {start, date, short}', { start }, 'en-UK')
// Sale begins 02/01/22
format('Sale begins {start, date, medium}', { start }, 'en-UK')
// Sale begins 2 Jan 2022
format('Sale begins {start, date, long}', { start }, 'en-UK')
// Sale begins 2 January 2022
format('Sale begins {start, date, full}', { start }, 'en-UK')
// Sale begins Sunday, 2 January 2022
format('Sale begins {start, date, full}', { start }, 'en-US')
// Sale begins Sunday, January 2, 2022
format('Sale begins {start, date, dateStyle/short timeStyle/short}', { start }, 'en-US)
// Sale begins 1/2/22, 1:34 PM
`
This type is used to format times in a way that is sensitive to the locale. It understands the following values for the optional format element of the argument:
- short is used to format times with hours and minutesmedium
- is used to format times with hours, minutes, and secondslong
- is used to format times with hours, minutes, seconds, and timezonefull
- is the same as long[option]/value
- all options from Intl.DateTimeFormat()
> [!note]
> Don't forget to set the locale!
`js
const start = new Date('2022-01-02T12:34:56Z')
format('Coupon expires at {expires, time}', { expires }, 'en-UK')
// Coupon expires at 13:34:56
format('Coupon expires at {expires, time, short}', { expires }, 'en-UK')
// Coupon expires at 13:34
format('Coupon expires at {expires, time, medium}', { expires }, 'en-UK')
// Coupon expires at 13:34:56
format('Coupon expires at {expires, time, long}', { expires }, 'en-UK')
// Coupon expires at 13:34:56 CET
format('Coupon expires at {expires, time, full}', { expires }, 'en-UK')
// Coupon expires at 13:34:56 CET
`
The formatted types plural and select can be nested with other types.
`js
const message = '{taxableArea, select, ' +
'yes {An additional {taxRate, number, percent} tax will be collected.} ' +
'other {No taxes apply.} ' +
'}'
format(message, { taxableArea: 'yes', taxRate: 0.2 })
// An additional 20% tax will be collected.
format(message, { taxableArea: 'no' }))
// No taxes apply.
``
[intl-messageformat]: https://github.com/formatjs/formatjs/tree/main/packages/intl-messageformat
[icu-syntax]: https://formatjs.io/docs/core-concepts/icu-syntax