Templural NPM | npm.io

templural 🍤

Template function for plural-sensitive formatting.

Usage

Install

yarn add templural

npm install templural

Import

import { templural } from 'templural'

const { templural } = require('templural')

Choose a locale

templural uses Intl.PluralRules to know which plural rule to apply for a given number, and plural rules vary depending on the language.

This means you have to set the locale used by templural in order to format correct sentences.

Either set the default locale:

templural.setLocales('fr_BE') // French (Belgium)

or create a new template function for a specific locale:

import { forLocales } from 'templural'

const templuralDeCH = forLocales('de_CH') // German (Switzerland)

For more information about the values accepted by templural.setLocales() and forLocales() see locales argument.

The following examples are specific to the English language, see Internationalization for information about other languages.

Match a word to a preceding number

templural`Yoann and Valentin had ${numberOfIdeas} interesting idea{s}`

// numberOfIdeas = 1 ➔ "Yoann and Valentin had 1 interesting idea"
// numberOfIdeas = 2 ➔ "Yoann and Valentin had 2 interesting ideas"
// numberOfIdeas = 42 ➔ "Yoann and Valentin had 42 interesting ideas"
// numberOfIdeas = 0 ➔ "Yoann and Valentin had 0 interesting ideas"

Insert any other values in the text

templural`${userName} has ${nbPoints} point{s}`

// userName = "Joe", nbPoints = 1 ➔ "Joe has 1 point"
// userName = "Mario", nbPoints = 1000 ➔ "Mario has 1000 points"

Match several words to the same preceding number

templural`I just had ${nbPints} bear{s} darling{s}, I swear{s}`

// nbPints = 1 ➔ "I just had 1 bear darling, I swear"
// nbPints = 2 ➔ "I just had 2 bears darlings, I swears"
// nbPints = 6 ➔ "I just had 6 bears darlings, I swears"

Match several words each to a different preceding number

templural`I bought ${nbCarrots} carrot{s} and ${nbPotatoes} potato{es}`

// nbCarrots = 1, nbPotatoes = 1 ➔ "I bought 1 carrot and 1 potato"
// nbCarrots = 1, nbPotatoes = 3 ➔ "I bought 1 carrot and 3 potatoes"
// nbCarrots = 2, nbPotatoes = 1 ➔ "I bought 2 carrots and 1 potato"
// nbCarrots = 2, nbPotatoes = 3 ➔ "I bought 2 carrots and 3 potatoes"

Words with a different form in the singular and plural

templural`${nbConnected} {person;people} {is;are} connected`

// nbConnected = 1 ➔ "1 person is connected"
// nbConnected = 2 ➔ "2 people are connected"
// nbConnected = 666 ➔ "666 people are connected"

Mix all the previous examples

templural`${nbDogs} dog{s} bark{s;} and ${nbCats} cat{s} meow{s;}`

// nbDogs = 1, nbCats = 1 ➔ "1 dog barks and 1 cat meows"
// nbDogs = 2, nbCats = 1 ➔ "2 dogs bark and 1 cat meows"
// nbDogs = 1, nbCats = 2 ➔ "1 dog barks and 2 cats meow"
// nbDogs = 2, nbCats = 2 ➔ "2 dogs bark and 2 cats meow"

Match a word to a non preceding number

templural`There {$1;is;are} ${nbWhales} flying whale{s}`

// nbWhales = 1 ➔ "There is 1 flying whale"
// nbWhales = 2 ➔ "There are 2 flying whales"

$1 references the first interpolated expression.

Use $2, $3 or $n to reference the second, the third or the nth interpolated expression.

🗣️ Internationalization

templural is built on top of Intl.PluralRules and may be used to format sentences in any language.

Plural rules

Each language has different plural rules.

For example English has two plural categories, "one" for singular, and "other" for plural:

templural.setLocales('en')

templural`${n} is in the {one;other} category`

// n = 1 ➔ "1 is in the one category"
// n = 2 ➔ "2 is in the other category"
// n = 1000000 ➔ "1000000 is in the other category"
// n = 0 ➔ "0 is in the other category"

French is a little different from English, it has a third category "many" for some large numbers, and 0 is singular:

templural.setLocales('fr')

templural`${n} is in the {one;other;many} category`

// n = 1 ➔ "1 is in the one category"
// n = 2 ➔ "2 is in the other category"
// n = 1000000 ➔ "1000000 is in the many category"
// n = 0 ➔ "0 is in the one category"

See Language Plural Rules for information about plural rules in any language.

FIXME category order

FIXME category priority

FIXME category fallbacks