0
# Language Support
1

2
The num2words library provides comprehensive support for 50+ languages with both base language implementations and regional variants. Each language is implemented as a specialized converter class with culturally appropriate number formatting rules.
3

4
## Capabilities
5

6
### Available Languages
7

8
Access to all supported language codes through the global CONVERTER_CLASSES dictionary.
9

10
```python { .api }
11
CONVERTER_CLASSES: dict
12
# Dictionary mapping language codes to converter instances
13
# Keys: Language codes (str)
14
# Values: Language-specific converter instances (Num2Word_Base subclasses)
15
```
16

17
**Usage Examples:**
18

19
```python
20
from num2words import CONVERTER_CLASSES
21

22
# Get all supported languages
23
supported_languages = list(CONVERTER_CLASSES.keys())
24
print(f"Supported languages: {len(supported_languages)}")
25

26
# Check if a language is supported
27
if 'fr' in CONVERTER_CLASSES:
28
    print("French is supported")
29

30
# Access a specific converter
31
english_converter = CONVERTER_CLASSES['en']
32
result = english_converter.to_cardinal(42)
33
```
34

35
### Language Code Reference
36

37
Complete list of supported language codes with their descriptions:
38

39
```python { .api }
40
# European Languages
41
'en'     # English (base)
42
'en_IN'  # English (India)
43
'en_NG'  # English (Nigeria)
44
'fr'     # French (base)
45
'fr_BE'  # French (Belgium)
46
'fr_CH'  # French (Switzerland)
47
'fr_DZ'  # French (Algeria)
48
'es'     # Spanish (base)
49
'es_CO'  # Spanish (Colombia)
50
'es_CR'  # Spanish (Costa Rica)
51
'es_GT'  # Spanish (Guatemala)
52
'es_NI'  # Spanish (Nicaragua)
53
'es_VE'  # Spanish (Venezuela)
54
'de'     # German
55
'it'     # Italian
56
'pt'     # Portuguese (base)
57
'pt_BR'  # Portuguese (Brazil)
58
'nl'     # Dutch
59
'sv'     # Swedish
60
'no'     # Norwegian
61
'da'     # Danish
62
'fi'     # Finnish
63
'is'     # Icelandic
64

65
# Slavic Languages
66
'ru'     # Russian
67
'pl'     # Polish
68
'cs'     # Czech
69
'sk'     # Slovak
70
'sl'     # Slovene
71
'sr'     # Serbian
72
'uk'     # Ukrainian
73
'be'     # Belarusian
74
'lt'     # Lithuanian
75
'lv'     # Latvian
76

77
# Other European
78
'hu'     # Hungarian
79
'ro'     # Romanian
80
'cy'     # Welsh
81
'eo'     # Esperanto
82

83
# Middle Eastern & Central Asian
84
'ar'     # Arabic
85
'fa'     # Farsi (Persian)
86
'he'     # Hebrew
87
'tr'     # Turkish
88
'kz'     # Kazakh
89
'tg'     # Tajik
90
'am'     # Amharic
91
'az'     # Azerbaijani
92
'ce'     # Chechen
93

94
# Asian Languages
95
'ja'     # Japanese
96
'ko'     # Korean
97
'th'     # Thai
98
'vi'     # Vietnamese
99
'id'     # Indonesian
100
'bn'     # Bangladeshi
101
'kn'     # Kannada
102
'te'     # Telugu
103

104
# Other Languages
105
'ca'     # Catalonian
106
'tet'    # Tetum
107
```
108

109
### Language Detection and Fallback
110

111
Intelligent language code processing with fallback mechanisms.
112

113
```python { .api }
114
def get_converter(lang_code: str):
115
    """
116
    Get converter for language code with fallback logic.
117
    
118
    Process:
119
    1. Try full language code (e.g., 'en_US')
120
    2. Fall back to base language (e.g., 'en')
121
    3. Raise NotImplementedError if not found
122
    
123
    Parameters:
124
    - lang_code: str - Language code to lookup
125
    
126
    Returns:
127
    Num2Word_Base - Language converter instance
128
    
129
    Raises:
130
    NotImplementedError - If language not supported
131
    """
132
```
133

134
**Usage Examples:**
135

136
```python
137
from num2words import num2words
138

139
# Regional variants with fallback
140
num2words(42, lang='en_US')      # Falls back to 'en'
141
num2words(42, lang='fr_FR')      # Falls back to 'fr'
142
num2words(42, lang='es_MX')      # Falls back to 'es'
143

144
# Specific regional implementations
145
num2words(42, lang='en_IN')      # Uses Indian English formatting
146
num2words(42, lang='fr_BE')      # Uses Belgian French formatting
147
num2words(42, lang='pt_BR')      # Uses Brazilian Portuguese formatting
148

149
# Case sensitivity handling
150
num2words(42, lang='EN')         # Typically case-insensitive
151
num2words(42, lang='Fr')         # Depends on implementation
152
```
153

154
### Language-Specific Features
155

156
Different languages support different conversion types and have unique formatting rules.
157

158
**Cardinal Number Variations:**
159

160
```python
161
# English: Standard grouping with "and"
162
num2words(1234, lang='en')       # "one thousand, two hundred and thirty-four"
163

164
# French: Unique rules for 70, 80, 90
165
num2words(71, lang='fr')         # "soixante et onze"
166
num2words(80, lang='fr')         # "quatre-vingts"
167
num2words(99, lang='fr')         # "quatre-vingt-dix-neuf"
168

169
# German: Compound number formation
170
num2words(21, lang='de')         # "einundzwanzig" (one-and-twenty)
171

172
# Arabic: Right-to-left script support
173
num2words(42, lang='ar')         # Arabic script output
174

175
# Japanese: Multiple number systems
176
num2words(42, lang='ja')         # Can use different counting systems
177

178
# Vietnamese: Southeast Asian formatting
179
num2words(42, lang='vi')         # Vietnamese representation
180
```
181

182
**Ordinal Number Support:**
183

184
```python
185
# English ordinals
186
num2words(21, to='ordinal', lang='en')    # "twenty-first"
187

188
# French ordinals
189
num2words(21, to='ordinal', lang='fr')    # "vingt et unième"
190

191
# Spanish ordinals
192
num2words(21, to='ordinal', lang='es')    # "vigésimo primero"
193

194
# Note: Not all languages support all conversion types
195
try:
196
    num2words(21, to='ordinal', lang='ja')
197
except NotImplementedError:
198
    print("Ordinals not implemented for Japanese")
199
```
200

201
### Conversion Type Support
202

203
Different languages may support different conversion types.
204

205
```python { .api }
206
CONVERTES_TYPES: list
207
# Available conversion types across all languages
208
# ['cardinal', 'ordinal', 'ordinal_num', 'year', 'currency']
209

210
def get_languages():
211
    """
212
    Get sorted list of available language codes.
213
    
214
    Returns:
215
        list: Sorted list of all supported language codes
216
    """
217

218
def get_converters():
219
    """
220
    Get sorted list of available conversion types.
221
    
222
    Returns:
223
        list: Sorted list of all supported conversion types
224
    """
225
```
226

227
**Language-Specific Support Matrix:**
228

229
```python
230
from num2words import num2words, CONVERTES_TYPES
231

232
def test_language_support(lang, number=42):
233
    """Test which conversion types are supported for a language."""
234
    supported = {}
235
    for conv_type in CONVERTES_TYPES:
236
        try:
237
            result = num2words(number, lang=lang, to=conv_type)
238
            supported[conv_type] = result
239
        except NotImplementedError:
240
            supported[conv_type] = "Not supported"
241
    return supported
242

243
# Test English (typically supports all types)
244
en_support = test_language_support('en')
245

246
# Test other languages
247
fr_support = test_language_support('fr')
248
ja_support = test_language_support('ja')
249
ar_support = test_language_support('ar')
250
```
251

252
### Currency Support by Language
253

254
Different languages have different currency format implementations.
255

256
```python
257
# Euro in different languages
258
num2words(42.50, to='currency', lang='en', currency='EUR')
259
# "forty-two euros, fifty cents"
260

261
num2words(42.50, to='currency', lang='fr', currency='EUR')
262
# "quarante-deux euros, cinquante centimes"
263

264
num2words(42.50, to='currency', lang='de', currency='EUR')
265
# German currency formatting
266

267
# Different currencies
268
num2words(42.50, to='currency', lang='en', currency='USD')
269
# "forty-two dollars, fifty cents"
270

271
num2words(42.50, to='currency', lang='ja', currency='JPY')
272
# Japanese yen formatting (if supported)
273
```
274

275
### Language Converter Classes
276

277
Each language is implemented as a class inheriting from Num2Word_Base.
278

279
```python { .api }
280
# Example language converter classes
281
class Num2Word_EN(Num2Word_Base): ...    # English
282
class Num2Word_FR(Num2Word_Base): ...    # French  
283
class Num2Word_ES(Num2Word_Base): ...    # Spanish
284
class Num2Word_DE(Num2Word_Base): ...    # German
285
class Num2Word_JA(Num2Word_Base): ...    # Japanese
286
class Num2Word_AR(Num2Word_Base): ...    # Arabic
287
# ... and 44+ more language classes
288
```
289

290
### Regional Variant Classes
291

292
Some languages have specific regional implementations.
293

294
```python { .api }
295
# Regional English variants
296
class Num2Word_EN_IN(Num2Word_EN): ...   # English (India)
297
class Num2Word_EN_NG(Num2Word_EN): ...   # English (Nigeria)
298

299
# Regional French variants
300
class Num2Word_FR_BE(Num2Word_FR): ...   # French (Belgium)
301
class Num2Word_FR_CH(Num2Word_FR): ...   # French (Switzerland)
302
class Num2Word_FR_DZ(Num2Word_FR): ...   # French (Algeria)
303

304
# Regional Spanish variants
305
class Num2Word_ES_CO(Num2Word_ES): ...   # Spanish (Colombia)
306
class Num2Word_ES_CR(Num2Word_ES): ...   # Spanish (Costa Rica)
307
class Num2Word_ES_GT(Num2Word_ES): ...   # Spanish (Guatemala)
308
class Num2Word_ES_NI(Num2Word_ES): ...   # Spanish (Nicaragua)
309
class Num2Word_ES_VE(Num2Word_ES): ...   # Spanish (Venezuela)
310

311
# Regional Portuguese variants
312
class Num2Word_PT_BR(Num2Word_PT): ...   # Portuguese (Brazil)
313
```
314

315
### Adding New Languages
316

317
The architecture supports adding new languages by creating converter classes.
318

319
```python
320
# Example template for new language implementation
321
class Num2Word_NewLang(Num2Word_Base):
322
    def setup(self):
323
        # Language-specific setup
324
        self.negword = "negative "  # How to represent negative numbers
325
        self.pointword = "point"    # How to represent decimal point
326
        
327
        # Define number words
328
        self.low_numwords = ["zero", "one", "two", ...]  # 0-19
329
        self.mid_numwords = [(20, "twenty"), (30, "thirty"), ...]  # Tens
330
        self.high_numwords = ["thousand", "million", ...]  # Large numbers
331
    
332
    def pluralize(self, n, forms):
333
        # Language-specific pluralization rules
334
        pass
335
    
336
    def to_ordinal(self, value):
337
        # Language-specific ordinal conversion
338
        pass
339
```
340

341
## Error Handling
342

343
Language-related error scenarios and their handling:
344

345
```python
346
# Unsupported language
347
try:
348
    num2words(42, lang='unsupported_lang')
349
except NotImplementedError as e:
350
    print(f"Language not supported: {e}")
351

352
# Unsupported conversion type for language
353
try:
354
    num2words(42, to='unsupported_type')
355
except NotImplementedError as e:
356
    print(f"Conversion type not supported: {e}")
357

358
# Regional variant fallback
359
result = num2words(42, lang='en_NonExistent')  # Falls back to 'en'
360
```