{"id":22423297,"url":"https://github.com/prantlf/fast-plural-rules","last_synced_at":"2025-08-01T07:32:09.253Z","repository":{"id":44729065,"uuid":"154933107","full_name":"prantlf/fast-plural-rules","owner":"prantlf","description":"Evaluates plural rules for cardinal numbers, so that localization libraries can choose the right plural form.","archived":false,"fork":false,"pushed_at":"2022-12-21T16:28:26.000Z","size":597,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-12-01T03:46:02.172Z","etag":null,"topics":["localization","localize","plural","plural-form","plural-forms","plural-rules","pluralize","plurals"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/prantlf.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-10-27T06:22:15.000Z","updated_at":"2022-01-28T10:46:02.000Z","dependencies_parsed_at":"2023-01-30T04:16:19.433Z","dependency_job_id":null,"html_url":"https://github.com/prantlf/fast-plural-rules","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Ffast-plural-rules","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Ffast-plural-rules/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Ffast-plural-rules/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Ffast-plural-rules/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/prantlf","download_url":"https://codeload.github.com/prantlf/fast-plural-rules/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228348371,"owners_count":17905899,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["localization","localize","plural","plural-form","plural-forms","plural-rules","pluralize","plurals"],"created_at":"2024-12-05T18:09:55.453Z","updated_at":"2024-12-05T18:09:56.156Z","avatar_url":"https://github.com/prantlf.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Fast Plural Rules\n\n[![Latest version](https://img.shields.io/npm/v/fast-plural-rules)\n ![Dependency status](https://img.shields.io/librariesio/release/npm/fast-plural-rules)\n](https://www.npmjs.com/package/fast-plural-rules)\n[![Coverage](https://codecov.io/gh/prantlf/fast-plural-rules/branch/master/graph/badge.svg)](https://codecov.io/gh/prantlf/fast-plural-rules)\n\nEvaluates 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.\n\n* Focused and complete - [nothing but the rule evaluation](./src/index.d.ts) is included, but still [supporting almost 150 languages](./docs/languages.md#supported-languages).\n* Tiny and [fast](./docs/speed.md#plural-form-lookup-speed) - 7.27 kB, 4.8 kB minified, 1.32 kB, gzipped. Using [plain hand-coded functions](./src/cardinals.js) as [plural rules](./docs/design.md#plural-rules) to pick [plural forms](./docs/design.md#plural-forms) using [language locales](./docs/design.md#locales).\n* Standard and documented - written using the [Translate Project documentation] and the [Mozilla documentation].\n* Reliable and correct - contains the [full test suite] [comparing the actual results with the Mozilla specification], run in both Node.js and the browser.\n* 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].\n\nIf 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.\n\n### Table of Contents\n\n- [Synopsis](#synopsis)\n- [Installation and Getting Started](#installation-and-getting-started)\n- [Usage Scenarios](./docs/usage.md#usage-scenarios)\n- [Design Concepts](./docs/design.md#design-concepts)\n- [Supported Languages](./docs/languages.md#supported-languages)\n- [API Reference](./docs/API.md#api-reference)\n- [Library Integrations](#library-integrations)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Synopsis\n\n```js\nimport { getPluralFormForCardinalByLocale } from 'fast-plural-rules'\n\n// Returns index of the plural form for the specified locale and cardinal.\ngetPluralFormForCardinalByLocale('en', 1) // Returns 0; \"1 file\"\ngetPluralFormForCardinalByLocale('en', 2) // Returns 1; \"2 files\"\ngetPluralFormForCardinalByLocale('en', 5) // Returns 1; \"5 files\"\ngetPluralFormForCardinalByLocale('cs', 1) // Returns 0; \"1 soubor\"\ngetPluralFormForCardinalByLocale('cs', 2) // Returns 1; \"2 soubory\"\ngetPluralFormForCardinalByLocale('cs', 5) // Returns 2; \"5 souborů\"\n\n// Returns a localized message for the specified locale and cardinal.\nlocalizeMessage('en', 'fileCount', 3) // Returns \"3 files\"\nlocalizeMessage('cs', 'fileCount', 3) // Returns \"3 soubory\"\n\n// Returns a localized message for the specified locale and cardinal.\nfunction localizeMessage (locale, messageKey, cardinal) {\n  const pluralForm = getPluralFormForCardinalByLocale(locale, cardinal)\n  const messageFormat = messages[locale][messageKey][pluralForm]\n  return messageFormat.replace('{0}', cardinal)\n}\n\n// A language pack with a testing message.\nconst messages = {\n  en: {\n    fileCount: [\n      \"{0} file\", // 0 - singular\n      \"{0} files\" // 1 - plural\n    ],\n  }\n  cs: {\n    fileCount: [\n      \"{0} soubor\",  // 0 - singular\n      \"{0} soubory\", // 1 - plural for 2-4 items\n      \"{0} souborů\"  // 2 - plural for 5+ items\n    ]\n  }\n}\n```\n\nThere is another [full example using plural form names](./docs/design.md#using-form-names) instead of numeric indexes like this:\n\n```js\n// Localized messages organized by locales and message keys.\nconst messages = {\n  en: {\n    fileCount: {\n      one:   '{0} file', // singular\n      other: '{0} files' // plural\n    }\n  },\n  cs: {\n    fileCount: {\n      one:   '{0} soubor',  // singular\n      few:   '{0} soubory', // plural for 2-4 items\n      other: '{0} souborů'  // plural for 5 and more items\n    }\n  }\n}\n```\n\n## Installation and Getting Started\n\nThis module can be installed in your project using [NPM] or [Yarn]. Make sure, that you use [Node.js] version 6 or newer.\n\n```sh\n$ npm i fast-plural-rules --save\n```\n\n```sh\n$ yarn add fast-plural-rules\n```\n\nFunctions are exposed as named exports, for example:\n\n```js\nimport { getPluralFormForCardinalByLocale } from 'fast-plural-rules'\n```\n\nYou 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. Finally, the [API reference](./docs/API.md#api-reference) lists all functions with a description of their functionality.\n\n## Library Integrations\n\n* [Extended Day.js] - [relativeTime plugin] formats time durations to the past and to the future.\n\n## Contributing\n\nIn 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.\n\n## License\n\nCopyright (c) 2018-2022 Ferdinand Prantl\n\nLicensed under the MIT license.\n\n[Node.js]: http://nodejs.org/\n[NPM]: https://www.npmjs.com/\n[Yarn]: https://yarnpkg.com/\n[TypeScript]: https://www.typescriptlang.org/\n[full test suite]: https://travis-ci.org/prantlf/fast-plural-rules\n[comparing the actual results with the Mozilla specification]: https://github.com/prantlf/fast-plural-rules/blob/master/test/rules.test.js\n[Translate Project documentation]: http://docs.translatehouse.org/projects/localization-guide/en/latest/l10n/pluralforms.html#pluralforms-list\n[Mozilla documentation]: https://developer.mozilla.org/en-US/docs/Mozilla/Localization/Localization_and_Plurals#List_of_Plural_Rules\n[Extended Day.js]: https://github.com/prantlf/dayjs\n[relativeTime plugin]: https://github.com/prantlf/dayjs/blob/combined/docs/en/Plugin.md#relativetime\n[CLDR plural rules]: http://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html\n[plural-rules]: https://github.com/prantlf/plural-rules\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprantlf%2Ffast-plural-rules","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprantlf%2Ffast-plural-rules","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprantlf%2Ffast-plural-rules/lists"}