0
# make-plural
1

2
make-plural provides pre-compiled JavaScript functions for determining pluralization categories according to Unicode CLDR rules for approximately 200 languages. It supports both cardinal plurals (e.g., "one book", "two books") and ordinal plurals (e.g., "1st book", "2nd book") with no runtime dependencies and tree shaking support for optimal bundle sizes.
3

4
## Package Information
5

6
- **Package Name**: make-plural
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install make-plural`
10

11
## Core Imports
12

13
```javascript
14
import { en, fr, ar } from "make-plural";
15
```
16

17
For specific modules:
18

19
```javascript
20
import { en, fr } from "make-plural/cardinals";
21
import { en } from "make-plural/ordinals";
22
import * as Categories from "make-plural/pluralCategories";
23
import * as Examples from "make-plural/examples";
24
import { en, ro } from "make-plural/ranges";
25
```
26

27
CommonJS:
28

29
```javascript
30
const { en, fr, ar } = require("make-plural");
31
```
32

33
## Basic Usage
34

35
```javascript
36
import { en, fr, ar } from "make-plural";
37

38
// Cardinal pluralization
39
en(1);        // 'one'
40
en(2);        // 'other'
41
fr(0);        // 'one' (French treats 0 as singular)
42
fr(2);        // 'many'
43

44
// Ordinal pluralization 
45
en(1, true);  // 'one' (1st)
46
en(2, true);  // 'two' (2nd)
47
en(3, true);  // 'few' (3rd)
48
en(4, true);  // 'other' (4th)
49

50
// Complex pluralization (Arabic has 6 categories)
51
ar(0);        // 'zero'
52
ar(1);        // 'one' 
53
ar(2);        // 'two'
54
ar(3);        // 'few'
55
ar(11);       // 'many'
56
ar(100);      // 'other'
57
```
58

59
## Architecture
60

61
make-plural is organized around several key modules:
62

63
- **Plurals Module**: Main entry point with combined cardinal and ordinal functions (217 languages)
64
- **Cardinals Module**: Cardinal-only functions for memory efficiency (217 languages)
65
- **Ordinals Module**: Ordinal-only functions for languages with ordinal rules (103 languages)  
66
- **Categories Module**: Metadata showing available plural categories per language
67
- **Examples Module**: Sample numeric values demonstrating each category
68
- **Ranges Module**: Functions for pluralizing numerical ranges (91 languages)
69

70
All functions are pre-compiled for maximum performance with no runtime dependencies.
71

72
## Capabilities
73

74
### Core Pluralization
75

76
Primary pluralization functions that determine plural categories for cardinal and ordinal numbers across 217 languages.
77

78
```typescript { .api }
79
type PluralCategory = "zero" | "one" | "two" | "few" | "many" | "other";
80

81
// Main pluralization function signature (all language functions)
82
(n: number | string, ord?: boolean) => PluralCategory;
83
```
84

85
[Core Pluralization](./core-pluralization.md)
86

87
### Cardinal Pluralization
88

89
Cardinal-only pluralization functions optimized for when ordinal pluralization is not needed.
90

91
```typescript { .api }
92
// Cardinal-only function signature
93
(n: number | string) => PluralCategory;
94
```
95

96
[Cardinal Pluralization](./cardinal-pluralization.md)
97

98
### Ordinal Pluralization
99

100
Ordinal-only pluralization functions for languages that have specific ordinal rules.
101

102
```typescript { .api }
103
// Ordinal-only function signature
104
(n: number | string) => PluralCategory;
105
```
106

107
[Ordinal Pluralization](./ordinal-pluralization.md)
108

109
### Plural Categories
110

111
Metadata about available plural categories for each language, including both cardinal and ordinal categories.
112

113
```typescript { .api }
114
interface LanguageCategories {
115
  cardinal: PluralCategory[];
116
  ordinal: PluralCategory[];
117
}
118
```
119

120
[Plural Categories](./plural-categories.md)
121

122
### Example Values
123

124
Sample numeric values that demonstrate each plural category for every supported language.
125

126
```typescript { .api }
127
interface LanguageExamples {
128
  cardinal: Record<PluralCategory, string[]>;
129
  ordinal: Record<PluralCategory, string[]>;
130
}
131
```
132

133
[Example Values](./example-values.md)
134

135
### Range Pluralization
136

137
Functions for determining the pluralization of numerical ranges (e.g., "1-5 items").
138

139
```typescript { .api }
140
// Range function signature
141
(start: PluralCategory, end: PluralCategory) => PluralCategory;
142
```
143

144
[Range Pluralization](./range-pluralization.md)
145

146
## Types
147

148
```typescript { .api }
149
/** All possible CLDR plural categories */
150
type PluralCategory = "zero" | "one" | "two" | "few" | "many" | "other";
151

152
/** Language category metadata */
153
interface LanguageCategories {
154
  cardinal: PluralCategory[];
155
  ordinal: PluralCategory[];
156
}
157

158
/** Language example values */
159
interface LanguageExamples {
160
  cardinal: Record<PluralCategory, string[]>;
161
  ordinal: Record<PluralCategory, string[]>;
162
}
163
```