CLDR Plural Rules and Ordinals

Selects the correct CLDR plural category for a locale and number, for cardinals, ordinals and ranges.

THE SILENT FAILURE. Nearly every codebase writes n === 1 ? 'item' : 'items'. That is right for English and wrong for most of the world. Russian and Polish have distinct forms for 1, for 2-4 and for 5+, with exceptions in the teens. Arabic has SIX categories including zero, one and two. Japanese has one form, so pluralising at all is wrong. Nothing throws: the string renders, the layout holds, and native speakers read text that is subtly broken in a way that reads as machine-translated and cheap. English-speaking teams cannot see it, which is why it survives for years.

ORDINALS follow a DIFFERENT rule set from cardinals in the same locale, so code reusing the cardinal rule produces wrong ordinals in English itself -- 1st, 2nd, 3rd, 4th.

It uses the platform's own Intl.PluralRules rather than a hand-maintained table, because a hand-maintained table silently goes stale as CLDR is revised. A message missing a category the locale requires is REFUSED, naming which forms are absent -- falling back to the 'other' form is exactly the silent breakage this exists to remove, so it is an explicit opt-in with the fallback reported. A lint function takes a whole catalogue and reports every locale and key whose forms are incomplete, which is the point: finding these before release.

A REAL DEFECT FOUND BEFORE RELEASE: the README told buyers to reproduce its numbers with a script that did not exist, and cited a section that did not exist either. Both now real, with every quoted output byte-identical to what the script prints.

VERIFIED: 80 tests. Every mutation was observed FAILING before the source was restored -- a test never seen to fail is a decoration. Independently reviewed by a verifier whose job was to find what is wrong, not to agree.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function checkPluralForms( locale: string, type: RuleType, forms: Partial<Record<CldrCategory, string>>, options?: NumberShapeOptions, ): PluralFormsCheck;
  export function lintCatalogue(catalogue: MessageCatalogue): LintFinding[];
  export function resolvePlural( locale: string, n: number, forms: Partial<Record<CldrCategory, string>>, options: ResolvePluralOptions = {}, ): ResolvePluralResult;
  export function resolveCardinal( locale: string, n: number, forms: Partial<Record<CldrCategory, string>>, options: Omit<ResolvePluralOptions, "type"> = {}, ): ResolvePluralResult;
  export function resolveOrdinal( locale: string, n: number, forms: Partial<Record<CldrCategory, string>>, options: Omit<ResolvePluralOptions, "type"> = {}, ): ResolvePluralResult;
  export function getRequiredCategories( locale: string, type: RuleType = "cardinal", options?: NumberShapeOptions, ): CldrCategory[];
  export function select( locale: string, n: number, type: RuleType = "cardinal", options?: NumberShapeOptions, ): CldrCategory;
  export function selectCardinal( locale: string, n: number, options?: NumberShapeOptions, ): CldrCategory;
  export function selectOrdinal( locale: string, n: number, options?: NumberShapeOptions, ): CldrCategory;
  export function selectRange( locale: string, start: number, end: number, type: RuleType = "cardinal", options?: NumberShapeOptions, ): CldrCategory;
  export function explainZero( locale: string, n: number, type: RuleType = "cardinal", options?: NumberShapeOptions, ):;

  export type MessageCatalogue = Record<string, Record<string, PluralMessageSpec>>;
  export type CldrCategory = "zero" | "one" | "two" | "few" | "many" | "other";
  export type RuleType = "cardinal" | "ordinal";
  export type NumberShapeOptions = Omit<Intl.PluralRulesOptions, "type">;