simplur@4 has no API changes from version 3. The only change is it is now ESM-only. (I.e. CommonJS is no longer supported.) ESM Module FAQ.
Installation
npm i simplur
import simplur from 'simplur';
Usage
simplur is an ES6 template tag that formats pluralization tokens based on the quantities injected into the string.
[!IMPORTANT]
Quantities must either be numbers (simple case) or Arrays. Other types will be ignored.
Simple case
Pluralization tokens have the form "[singular|plural]" and are resolved
using the first expression found to the left of each token or, if no
left-expression is available, the first expression to the right.
simplur`I have ${1} kitt[en|ies]`; // ⇨ 'I have 1 kitten'simplur`I have ${3} kitt[en|ies]`; // ⇨ 'I have 3 kitties'simplur`There [is|are] ${1} m[an|en]`; // ⇨ 'There is 1 man'simplur`There [is|are] ${5} m[an|en]`; // ⇨ 'There are 5 men'
Multiple tokens
Multiple tokens and quantities are allowed. These follow the same rules as above.
simplur`There [is|are] ${1} fox[|es] and ${4} octop[us|i]`; // ⇨ 'There is 1 fox and 4 octopi'simplur`There [is|are] ${4} fox[|es] and ${1} octop[us|i]`; // ⇨ 'There are 4 foxes and 1 octopus'
Tokens as expressions
simplur inlines all string template values prior to processing, allowing you
to pass pluralization tokens as values.
const pets = ['dog[|s]', 'lazy cat[|s]', 'wily fox[|es]'];simplur`I love my ${3} ${pets[1]}`; // ⇨ 'I love my 3 lazy cats'
Custom quantities
Quantity values may be customized using value of the form, [quantity, format function]. For example:
Quantities may be hidden by omitting the format function (i.e. just pass the
value in an Array), or by returning null or undefined from the quantity
function.
Note:Whitespace immediately following a hidden quantity will be removed.
simplur`${[1]} gen[us|era]`; // ⇨ 'genus'simplur`${[2]} gen[us|era]`; // ⇨ 'genera'function hideSingular(qty) { return qty == 1 ? null : qty;}simplur`Delete the ${[1, hideSingular]} cact[us|i]?`; // ⇨ 'Delete the cactus?'simplur`Delete the ${[2, hideSingular]} cact[us|i]?`; // ⇨ 'Delete the 2 cacti?'