make-plural

What is make-plural?

The make-plural npm package is a utility for handling pluralization rules in various languages. It allows developers to determine the correct plural form of a word based on a given number, which is particularly useful for internationalization (i18n) and localization (l10n) tasks.

What are make-plural's main functionalities?

Determine Plural Form

This feature allows you to determine the plural form of a word in a specified language based on a given number. In this example, the plural form for English ('en') is determined for the numbers 1 and 2.

const makePlural = require('make-plural');
const plural = makePlural('en');
console.log(plural(1)); // 'one'
console.log(plural(2)); // 'other'

Support for Multiple Languages

This feature demonstrates the package's support for multiple languages. It shows how to determine the plural form for both English and French.

const makePlural = require('make-plural');
const pluralEn = makePlural('en');
const pluralFr = makePlural('fr');
console.log(pluralEn(1)); // 'one'
console.log(pluralEn(2)); // 'other'
console.log(pluralFr(1)); // 'one'
console.log(pluralFr(2)); // 'other'

Custom Plural Rules

This feature allows you to define custom pluralization rules. In this example, custom rules are provided to determine the plural form.

const makePlural = require('make-plural');
const customRules = {
  one: 'n == 1',
  other: 'true'
};
const pluralCustom = makePlural(customRules);
console.log(pluralCustom(1)); // 'one'
console.log(pluralCustom(2)); // 'other'

Other packages similar to make-plural

pluralize

The pluralize package provides simple pluralization and singularization of English words. It is less comprehensive than make-plural as it primarily focuses on English and does not support custom rules or multiple languages.

i18next

i18next is a powerful internationalization framework that supports pluralization among many other features. It is more comprehensive than make-plural, offering a full suite of i18n tools, but it may be overkill if you only need pluralization.

messageformat

The messageformat package provides support for handling complex message formatting, including pluralization, gender, and other language-specific rules. It is more feature-rich compared to make-plural, but also more complex to use.

README

make-plural

Make-plural is a JavaScript module that translates Unicode CLDR pluralization rules to JavaScript functions. It includes both a live parser as well as the generated output for the latest edition of the CLDR; the latter is just over 2kB in size when minified & gzipped and covers 199 languages, so it's probably what you want unless you really know what you're doing.

Make-plural is written in ECMAScript 6 and transpiled using Babel and Browserify to CommonJS and AMD and ES6 module formats, as well as being suitable for use in browser environments.

Installation

npm install make-plural

or

bower install make-plural

or

git clone https://github.com/eemeli/make-plural.git
cd make-plural
npm install
make all

or download the latest release from here

Precompiled plurals

umd/plurals.js contains an UMD module that can be included with node's require or AMD's define. In a browser environment, it will populate a global object plurals. Said module contains 199 functions (one per language), each taking as a first parameter the value to be classified (either a number or a string), and as an optional second parameter, a boolean that if true, applies ordinal rather than cardinal rules.

umd/pluralCategories.js has a similar structure to umd/plurals.js, but contains an array of the pluralization categories the cardinal and ordinal rules each language's pluralization function may output.

es6/plurals.js and es6/pluralCategories.js are the ES6 module equivalents of the above.

If your language isn't directly included in either of the above, try removing any trailing parts that are separated from the stem by - or _. Note also that the capitalization of locale codes is lowercase for the language, but uppercase for the country, so for example the code for Portugese as spoken in Portugal is pt-PT.

Precompiled use: Node

var plurals = require('make-plural')
// { af: [Function],
//   ak: [Function],
//   am: [Function],
// snip 193 lines...
//   yo: [Function],
//   zh: [Function],
//   zu: [Function] }

plurals.en(1)  // 1st param is the value
// 'one'

plurals.en(2)
// 'other'

plurals.en(2, true)  // 2nd param, if true-ish, is for ordinal rules
// 'two'

console.log(plurals.en.toString())
// function (n, ord) {
//   var s = String(n).split('.'), v0 = !s[1], t0 = Number(s[0]) == n,
//       n10 = t0 && s[0].slice(-1), n100 = t0 && s[0].slice(-2);
//   if (ord) return (n10 == 1 && n100 != 11) ? 'one'
//       : (n10 == 2 && n100 != 12) ? 'two'
//       : (n10 == 3 && n100 != 13) ? 'few'
//       : 'other';
//   return (n == 1 && v0) ? 'one' : 'other';
// }

var pluralCategories = require('make-plural/umd/pluralCategories')
// { af: { cardinal: [ 'one', 'other' ], ordinal: [ 'other' ] },
//   ak: { cardinal: [ 'one', 'other' ], ordinal: [ 'other' ] },
//   am: { cardinal: [ 'one', 'other' ], ordinal: [ 'other' ] },
//   ar:
//    { cardinal: [ 'zero', 'one', 'two', 'few', 'many', 'other' ],
//      ordinal: [ 'other' ] },
// snip 255 lines...
//   zh: { cardinal: [ 'other' ], ordinal: [ 'other' ] },
//   zu: { cardinal: [ 'one', 'other' ], ordinal: [ 'other' ] } }

Precompiled use: Web

<script src="path/to/make-plural/umd/plurals.js"></script>
<script>
  var ru = plurals.ru
  console.log('1: ' + plurals.ru(1) + ', 3.0: ' + plurals.ru(3.0) +
              ', "1.0": ' + plurals.ru('1.0') + ', "0": ' + plurals.ru('0'));
  console.log(plurals.ru.toString());
</script>

With outputs:

1: one, 3.0: few, "1.0": other, "0": many

function(n, ord) {
  var s = String(n).split('.'), i = s[0], v0 = !s[1], i10 = i.slice(-1),
      i100 = i.slice(-2);
  if (ord) return 'other';
  return (v0 && i10 == 1 && i100 != 11) ? 'one'
      : (v0 && (i10 >= 2 && i10 <= 4) && (i100 < 12
          || i100 > 14)) ? 'few'
      : (v0 && i10 == 0 || v0 && (i10 >= 5 && i10 <= 9)
          || v0 && (i100 >= 11 && i100 <= 14)) ? 'many'
      : 'other';
}

Note that with umd/plurals.min.js, the stringified function would be rendered as:

function (e,t){var r=String(e).split("."),n=r[0],o=!r[1],c=n.slice(-1),
i=n.slice(-2);return t?"other":o&&1==c&&11!=i?"one":o&&c>=2&&4>=c&&(12>i||i>14)?
"few":o&&0==c||o&&c>=5&&9>=c||o&&i>=11&&14>=i?"many":"other"}

Live compiler: make-plural.js

MakePlural.load(cldr, ...)

Loads CLDR rules from one or more cldr variables, each of which must be an object formatted like this.

No plural data is included by default, so you'll need to call this at least once, or otherwise fill the MakePlural.rules object.

The default CLDR rules are included in make-plural, and may be loaded as seen in the examples below.

new MakePlural(lc, { cardinals, ordinals })

Returns a function that takes an argument n and returns its plural category for the given locale lc. If no direct match for lc is found, it is compared case-insensitively to known locales.

The returned function has an overloaded toString(name) method that may be used to generate a clean string representation of the function, with an optional name name.

The optional second parameter may contain the following boolean members:

• cardinals — if true, rules for cardinal values (1 day, 2 days, etc.) are included
• ordinals — if true, rules for ordinal values (1st, 2nd, etc.) are included

If both cardinals and ordinals are true, the returned function takes a second parameter ord. Then, if ord is true, the function will return the ordinal rather than cardinal category applicable to n in locale lc.

If the second parameter is undefined, the values are taken from MakePlural.cardinals (default true) and MakePlural.ordinals (default false).

Live use: Node

var MakePlural = require('make-plural/make-plural').load(
    require('make-plural/data/plurals.json'),
    require('make-plural/data/ordinals.json'))
// { [Function: MakePlural]
//   cardinals: true,
//   ordinals: false,
//   rules:
//    { cardinal:
//       { af: [Object],
//         ak: [Object],
//         am: [Object],
// snip 193 lines...
//         yo: [Object],
//         zh: [Object],
//         zu: [Object] },
//      ordinal:
//       { af: [Object],
//         am: [Object],
//         ar: [Object],
// snip 78 lines...
//         vi: [Object],
//         zh: [Object],
//         zu: [Object] } } }

var sk = new MakePlural('sk')  // Note: not including ordinals by default
// { [Function]
//   _obj:
//    { lc: 'sk',
//      cardinals: true,
//      ordinals: false,
//      categories: { cardinal: [Object], ordinal: [] },
//      parser: { v0: 1, i: 1 },
//      tests: { obj: [Circular], ordinal: {}, cardinal: [Object] },
//      fn: [Circular] },
//   categories: { cardinal: [ 'one', 'few', 'many', 'other' ], ordinal: [] },
//   test: [Function],
//   toString: [Function] }

sk(1)
// 'one'

sk(3.0)
// 'few'

sk('1.0')
// 'many'

sk('0')
// 'other'

console.log(sk.toString())
// function(n) {
//   var s = String(n).split('.'), i = s[0], v0 = !s[1];
//   return (i == 1 && v0 ) ? 'one'
//       : ((i >= 2 && i <= 4) && v0 ) ? 'few'
//       : (!v0   ) ? 'many'
//       : 'other';
// }

make-plural may also be used in browser environments; see test/index.html for an example of its use.

CLI Usage

$ ./bin/make-plural > plurals.js

$ ./bin/make-plural fr
function fr(n, ord) {
  if (ord) return (n == 1) ? 'one' : 'other';
  return (n >= 0 && n < 2) ? 'one' : 'other';
}

$ ./bin/make-plural --locale fr --value 1.5
one

$ ./bin/make-plural 1.5 -l fr --ordinal
other

Please see the source of src/index.js for more details.

Dependencies

Make-plural has no required runtime dependencies. CLDR plural rule data is included in JSON format; make-plural supports the LDML Language Plural Rules as used in CLDR release 24 and later.

The CLI binary bin/make-plural does use minimist as an argument parser, but that is not required for any other use.

Using MakePlural.load(), you may make use of external sources of CLDR data. For example, the following works when using together with cldr-data:

var cldr = require('cldr-data');
var MakePlural = require('make-plural/make-plural').load(
  cldr('supplemental/plurals'),
  cldr('supplemental/ordinals')
);
var en = new MakePlural('en');
en(3, true);
// 'few'