Fast Plural Rules

Evaluates locale-specific plural rules to identify the right plural form for a cardinal number, which represents an item count. Internationalization libraries can utilize it to choose the right localized string.

Focused and complete - nothing but the rule evaluation is included, but still supporting almost 150 languages.
Tiny and fast - 7.27 kB, 4.8 kB minified, 1.32 kB, gzipped. Using plain hand-coded functions as plural rules to pick plural forms using language locales.
Standard and documented - written using the Translate Project documentation and the Mozilla documentation.
Reliable and correct - contains the full test suite comparing the actual results with the Mozilla specification, run in both Node.js and the browser.
Universal and modern - supports both plural form index (0-5) and plural form rules (zero, one, two, few, many and other) and includes declarations for TypeScript.

If you are looking for a library compiling and executing the declarative CLDR plural rules, see plural-rules. Generated programmatically for better reliability, but bigger and slower.

Synopsis

import { getPluralFormForCardinalByLocale } from 'fast-plural-rules'

// Returns index of the plural form for the specified locale and cardinal.
getPluralFormForCardinalByLocale('en', 1) // Returns 0; "1 file"
getPluralFormForCardinalByLocale('en', 2) // Returns 1; "2 files"
getPluralFormForCardinalByLocale('en', 5) // Returns 1; "5 files"
getPluralFormForCardinalByLocale('cs', 1) // Returns 0; "1 soubor"
getPluralFormForCardinalByLocale('cs', 2) // Returns 1; "2 soubory"
getPluralFormForCardinalByLocale('cs', 5) // Returns 2; "5 souborů"

// Returns a localized message for the specified locale and cardinal.
localizeMessage('en', 'fileCount', 3) // Returns "3 files"
localizeMessage('cs', 'fileCount', 3) // Returns "3 soubory"

// Returns a localized message for the specified locale and cardinal.
function localizeMessage (locale, messageKey, cardinal) {
  const pluralForm = getPluralFormForCardinalByLocale(locale, cardinal)
  const messageFormat = messages[locale][messageKey][pluralForm]
  return messageFormat.replace('{0}', cardinal)
}

// A language pack with a testing message.
const messages = {
  en: {
    fileCount: [
      "{0} file", // 0 - singular
      "{0} files" // 1 - plural
    ],
  }
  cs: {
    fileCount: [
      "{0} soubor",  // 0 - singular
      "{0} soubory", // 1 - plural for 2-4 items
      "{0} souborů"  // 2 - plural for 5+ items
    ]
  }
}

There is another full example using plural form names instead of numeric indexes like this:

// Localized messages organized by locales and message keys.
const messages = {
  en: {
    fileCount: {
      one:   '{0} file', // singular
      other: '{0} files' // plural
    }
  },
  cs: {
    fileCount: {
      one:   '{0} soubor',  // singular
      few:   '{0} soubory', // plural for 2-4 items
      other: '{0} souborů'  // plural for 5 and more items
    }
  }
}

Installation and Getting Started

This module can be installed in your project using NPM or Yarn. Make sure, that you use Node.js version 6 or newer.

$ npm i fast-plural-rules --save

$ yarn add fast-plural-rules

Functions are exposed as named exports, for example:

import { getPluralFormForCardinalByLocale } from 'fast-plural-rules'

You can read more about the module loading in other environments, like with ESM or in web browsers. Usage scenarios demonstrate applications of this library in typical real-world situations. Design concepts explain the approach to the correct internationalization of messages with cardinals taken by this library. Translators will read about plural rules for supported languages to be able to write the right plural forms to language packs. Finally, the API reference lists all functions with a description of their functionality.

Library Integrations

Extended Day.js - relativeTime plugin formats time durations to the past and to the future.

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

License

Licensed under the MIT license.

The automated release is failing 🚨

🚨 The automated release from the `master` branch failed. 🚨

I recommend you give this issue a high priority, so other packages depending on you can benefit from your bug fixes and new features again.

You can find below the list of errors reported by semantic-release. Each one of them has to be resolved in order to automatically publish your package. I’m sure you can fix this 💪.

Errors are usually caused by a misconfiguration or an authentication problem. With each error reported below you will find explanation and guidance to help you to resolve it.

Once all the errors are resolved, semantic-release will release your package the next time you push a commit to the master branch. You can also manually restart the failed CI job that runs semantic-release.

If you are not sure how to resolve this, here are some links that can help you:

If those don’t help, or if this issue is reporting something you think isn’t right, you can always ask the humans behind semantic-release.

Invalid npm token.

The npm token configured in the NPM_TOKEN environment variable must be a valid token allowing to publish to the registry https://registry.npmjs.org/.

If you are using Two Factor Authentication for your account, set its level to "Authorization only" in your account settings. semantic-release cannot publish with the default "
Authorization and writes" level.

Please make sure to set the NPM_TOKEN environment variable in your CI with the exact value of the npm token.

Good luck with your project ✨

Your semantic-release bot 📦🚀

prantlf / fast-plural-rules Goto Github PK