0
# Ordinal Pluralization
1

2
Ordinal-only pluralization functions for languages that have specific ordinal rules. Only 103 of the 217 supported languages have distinct ordinal pluralization rules.
3

4
## Capabilities
5

6
### Ordinal Functions
7

8
Languages with ordinal rules provide functions for determining ordinal plural categories (1st, 2nd, 3rd, etc.).
9

10
```typescript { .api }
11
/**
12
 * Determines the ordinal plural category for a number
13
 * @param n - The number to pluralize (number or string)
14
 * @returns The appropriate ordinal plural category
15
 */
16
(n: number | string) => PluralCategory;
17

18
type PluralCategory = "zero" | "one" | "two" | "few" | "many" | "other";
19
```
20

21
### Import Pattern
22

23
```javascript { .api }
24
import { en, cy, az } from "make-plural/ordinals";
25
```
26

27
### Language Coverage
28

29
**103 languages with ordinal rules include:**
30

31
**Major Languages with Ordinal Rules:**
32
- `en` - English: Returns `"one" | "two" | "few" | "other"`
33
- `fr` - French: Returns `"one" | "other"`
34
- `es` - Spanish: Returns `"other"`
35
- `de` - German: Returns `"other"`
36
- `it` - Italian: Returns `"many" | "other"`
37

38
**Complex Ordinal Systems:**
39
- `cy` - Welsh: Returns `"zero" | "one" | "two" | "few" | "many" | "other"`
40
- `gv` - Manx: Returns `"one" | "two" | "few" | "many" | "other"`
41
- `kw` - Cornish: Returns `"one" | "many" | "other"`
42

43
**Languages with Simple Ordinal Rules:**
44
- `az` - Azerbaijani: Returns `"one" | "few" | "many" | "other"`
45
- `ka` - Georgian: Returns `"one" | "other"`
46
- `sq` - Albanian: Returns `"one" | "many" | "other"`
47

48
### Usage Examples
49

50
**English Ordinals:**
51
```javascript
52
import { en } from "make-plural/ordinals";
53

54
// English ordinal patterns
55
en(1);   // 'one'   (1st, 21st, 31st, 41st, 51st, 61st, 71st, 81st, 91st)
56
en(2);   // 'two'   (2nd, 22nd, 32nd, 42nd, 52nd, 62nd, 72nd, 82nd, 92nd)
57
en(3);   // 'few'   (3rd, 23rd, 33rd, 43rd, 53rd, 63rd, 73rd, 83rd, 93rd)
58
en(4);   // 'other' (4th, 5th, 6th, 7th, 8th, 9th, 10th, 11th, 12th, 13th...)
59

60
// Special cases
61
en(11);  // 'other' (11th - not 'one' despite ending in 1)
62
en(12);  // 'other' (12th - not 'two' despite ending in 2)  
63
en(13);  // 'other' (13th - not 'few' despite ending in 3)
64
en(21);  // 'one'   (21st - back to pattern)
65
```
66

67
**Welsh Complex Ordinals:**
68
```javascript
69
import { cy } from "make-plural/ordinals";
70

71
// Welsh has 6 ordinal categories
72
cy(0);   // 'zero'  (0th)
73
cy(1);   // 'one'   (1st)
74
cy(2);   // 'two'   (2nd)
75
cy(3);   // 'few'   (3rd, 4th)
76
cy(5);   // 'many'  (5th, 6th)
77
cy(7);   // 'other' (7th+)
78
```
79

80
**French Ordinals:**
81
```javascript
82
import { fr } from "make-plural/ordinals";
83

84
// French has simple ordinal rules
85
fr(1);   // 'one'   (1er - premier)
86
fr(2);   // 'other' (2e, 2ème)
87
fr(3);   // 'other' (3e, 3ème)
88
fr(100); // 'other'
89
```
90

91
**Italian Ordinals:**
92
```javascript
93
import { it } from "make-plural/ordinals";
94

95
// Italian ordinal system
96
it(1);   // 'many'  (1º)
97
it(8);   // 'many'  (8º)  
98
it(11);  // 'many'  (11º)
99
it(80);  // 'many'  (80º)
100
it(800); // 'many'  (800º)
101
it(1000);// 'other' (1000º)
102
```
103

104
### Language-Specific Ordinal Rules
105

106
**English (`en`) Ordinal Rules:**
107
- `one`: n % 10 = 1 && n % 100 ≠ 11 (1st, 21st, 31st, but not 11th)
108
- `two`: n % 10 = 2 && n % 100 ≠ 12 (2nd, 22nd, 32nd, but not 12th)
109
- `few`: n % 10 = 3 && n % 100 ≠ 13 (3rd, 23rd, 33rd, but not 13th)
110
- `other`: everything else (4th-20th, 24th-30th, etc.)
111

112
**Welsh (`cy`) Ordinal Rules:**
113
- `zero`: n = 0
114
- `one`: n = 1
115
- `two`: n = 2
116
- `few`: n = 3,4
117
- `many`: n = 5,6
118
- `other`: everything else
119

120
**Azerbaijani (`az`) Ordinal Rules:**
121
- `one`: n % 10 in 1,2,5,7,8 || n % 100 in 20,50,70,80
122
- `few`: n % 10 in 3,4 || n % 1000 in 100,200,300,400,500,600,700,800,900
123
- `many`: n = 0 || n % 10 = 6 || n % 100 in 40,60,90
124
- `other`: everything else
125

126
### String Input Support
127

128
```javascript
129
import { en, cy } from "make-plural/ordinals";
130

131
// String representation support
132
en("1");    // 'one'
133
en("21");   // 'one'
134
en("12");   // 'other'
135

136
// Decimal handling (usually 'other')
137
en("1.0");  // 'one'
138
en("1.5");  // 'other'
139
cy("2.0");  // 'two'
140
cy("2.5");  // 'other'
141
```
142

143
### Fallback Behavior
144

145
Languages without specific ordinal rules are not included in this module. For comprehensive coverage that falls back to cardinal rules when ordinal rules don't exist, use the main plurals module:
146

147
```javascript
148
// Use this for comprehensive coverage
149
import { zh, ja, ko } from "make-plural";
150

151
zh(1, true);  // 'other' (fallback to cardinal)
152
ja(1, true);  // 'other' (fallback to cardinal)
153
ko(1, true);  // 'other' (fallback to cardinal)
154

155
// These languages are NOT in make-plural/ordinals
156
// import { zh, ja, ko } from "make-plural/ordinals"; // ERROR
157
```
158

159
### When to Use Ordinals
160

161
Use ordinal-only functions when:
162

163
1. **Ordinal-specific**: Your application only deals with ordinal numbers
164
2. **Memory efficiency**: Need minimal bundle size for ordinal-only use
165
3. **Performance**: Maximum performance for ordinal pluralization
166
4. **Explicit intent**: Clear separation between cardinal and ordinal logic
167

168
Use main plurals module when:
169

170
1. **Mixed usage**: Need both cardinal and ordinal
171
2. **Language coverage**: Need fallback for languages without ordinal rules
172
3. **Simplicity**: Prefer single import pattern
173
4. **Future flexibility**: Might need other features later