https://github.com/prantlf/plural-rules
Evaluates plural rules, so that localization libraries can choose the right plural form.
https://github.com/prantlf/plural-rules
localization localize plural plural-form plural-forms plural-rules pluralize plurals
Last synced: 6 months ago
JSON representation
Evaluates plural rules, so that localization libraries can choose the right plural form.
- Host: GitHub
- URL: https://github.com/prantlf/plural-rules
- Owner: prantlf
- License: mit
- Created: 2018-10-20T19:51:42.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2022-12-21T16:36:09.000Z (over 2 years ago)
- Last Synced: 2024-11-11T20:56:20.689Z (6 months ago)
- Topics: localization, localize, plural, plural-form, plural-forms, plural-rules, pluralize, plurals
- Language: JavaScript
- Size: 432 KB
- Stars: 7
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Plural Rules
[
](https://www.npmjs.com/package/plural-rules)
[](https://codecov.io/gh/prantlf/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.
* Tiny code base - 2.52 kB, 1.57 KB minified, 0.67 KB gzipped. Do not pack unnecessary weight in your application. (Bundled code for the web browser is 11 kB, 4.77 kB minified, 1.79 kB gzipped.)
* Packed data - 18.2 kB, 16 kB minified, 3 kB gzipped. A quarter of the size of the original CLDR data. (This size adds to the code size.)
* Generated from the official [CLDR plural rules] version 36.0. Cardinals for [almost 200 languages](./docs/languages.md#supported-languages) are supported.
* Minimal interface for finding out the right [plural form](./docs/design.md#plural-forms) by evaluating [plural rules](./docs/design.md#plural-rules) for a specific [locale](./docs/design.md#locales). Looking up and formatting localizable strings is a task for internationalization libraries.
If you are looking for a smaller and [faster](https://github.com/prantlf/fast-plural-rules/blob/master/docs/speed.md#plural-form-lookup-speed) library using [Mozilla plural rules], see [fast-plural-rules].
### Table of Contents
- [Synopsis](#synopsis)
- [Installation and Getting Started](#installation-and-getting-started)
- [Usage Scenarios](./docs/usage.md#usage-scenarios)
- [Design Concepts](./docs/design.md#design-concepts)
- [Supported Languages](./docs/languages.md#supported-languages)
- [API Reference](./docs/API.md#api-reference)
- [Contributing](#contributing)
- [License](#license)
## Synopsis
```js
import { getPluralFormForCardinal } from 'plural-rules'
// Returns index of the plural form for the specified locale and cardinal.
getPluralFormForCardinal('en', 1) // Returns "one"; "1 file"
getPluralFormForCardinal('en', 2) // Returns "other"; "2 files"
getPluralFormForCardinal('en', 5) // Returns "other"; "5 files"
getPluralFormForCardinal('cs', 1) // Returns "one"; "1 soubor"
getPluralFormForCardinal('cs', 2) // Returns "few"; "2 soubory"
getPluralFormForCardinal('cs', 5) // Returns "other"; "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 = getPluralFormForCardinal(locale, cardinal)
const messageFormat = messages[locale][messageKey][pluralForm]
return messageFormat.replace('{0}', cardinal)
}
// 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.
```sh
$ npm i plural-rules --save
```
```sh
$ yarn add plural-rules
```
Functions are exposed as named exports, for example:
```js
import { getPluralFormForCardinal } from 'plural-rules'
```
You can read more about the [module loading](./docs/API.md#loading) in other environments, like with ESM or in web browsers. [Usage scenarios](./docs/usage.md#usage-scenarios) demonstrate applications of this library in typical real-world situations. [Design concepts](./docs/design.md#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](./docs/languages.md#supported-languages) to be able to write the right plural forms to language packs. [Data genrator](#./API.md#data-generator) enables customizing the the amount of recognized languages and thus shrink the library size. Finally, the [API reference](./docs/API.md#api-reference) lists all functions with a description of their functionality.
## 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
Copyright (c) 2018-2022 Ferdinand Prantl
Licensed under the MIT license.
[Node.js]: http://nodejs.org/
[NPM]: https://www.npmjs.com/
[Yarn]: https://yarnpkg.com/
[CLDR plural rules]: http://cldr.unicode.org/index/cldr-spec/plural-rules
[Mozilla plural rules]: https://developer.mozilla.org/en-US/docs/Mozilla/Localization/Localization_and_Plurals#List_of_Plural_Rules
[fast-plural-rules]: https://github.com/prantlf/fast-plural-rules