0
# num2words
1

2
A comprehensive Python library that converts numbers to words in 50+ languages. The library supports multiple output formats including cardinal numbers (forty-two), ordinal numbers (forty-second), years, and currency representations with proper localization for each language.
3

4
## Package Information
5

6
- **Package Name**: num2words
7
- **Language**: Python
8
- **Installation**: `pip install num2words`
9

10
## Core Imports
11

12
```python
13
from num2words import num2words
14
```
15

16
Access to available languages and conversion types:
17

18
```python
19
from num2words import CONVERTER_CLASSES, CONVERTES_TYPES
20
```
21

22
## Basic Usage
23

24
```python
25
from num2words import num2words
26

27
# Basic cardinal number conversion (default English)
28
result = num2words(42)
29
print(result)  # "forty-two"
30

31
# Convert to ordinal form
32
result = num2words(42, to='ordinal')
33
print(result)  # "forty-second"
34

35
# Convert in different language
36
result = num2words(42, lang='fr')
37
print(result)  # "quarante-deux"
38

39
# Convert to currency format
40
result = num2words(42.50, to='currency', lang='en')
41
print(result)  # "forty-two euros, fifty cents"
42

43
# Year format
44
result = num2words(1984, to='year')
45
print(result)  # "nineteen eighty-four"
46
```
47

48
## Architecture
49

50
The num2words library uses a pluggable architecture where each language is implemented as a separate converter class inheriting from a base class:
51

52
- **Num2Word_Base**: Foundation class providing core conversion logic and currency handling
53
- **Language Converters**: 50+ language-specific classes implementing localized number conversion rules
54
- **CONVERTER_CLASSES**: Registry mapping language codes to converter instances
55
- **Conversion Types**: Support for cardinal, ordinal, year, and currency formats
56

57
This design makes the library easily extensible for new languages and locales while maintaining consistent behavior across all supported languages.
58

59
## Capabilities
60

61
### Number Conversion
62

63
Core functionality for converting numbers to word representations in multiple languages and formats.
64

65
```python { .api }
66
def num2words(number, ordinal=False, lang='en', to='cardinal', **kwargs):
67
    """
68
    Convert numbers to words in specified language and format.
69
    
70
    Parameters:
71
    - number: int/float/str - Number to convert
72
    - ordinal: bool - Backward compatibility for ordinal conversion
73
    - lang: str - Language code (default: 'en')
74
    - to: str - Conversion type ('cardinal', 'ordinal', 'ordinal_num', 'year', 'currency')
75
    - **kwargs: Additional language-specific arguments
76
    
77
    Returns:
78
    str - Number converted to words
79
    
80
    Raises:
81
    NotImplementedError - For unsupported languages or conversion types
82
    """
83
```
84

85
[Number Conversion](./number-conversion.md)
86

87
### Language Support
88

89
Access to 50+ supported languages and their specific conversion capabilities.
90

91
```python { .api }
92
CONVERTER_CLASSES: dict  # Maps language codes to converter instances
93
CONVERTES_TYPES: list    # Available conversion types
94
```
95

96
[Language Support](./language-support.md)
97

98
### Base Converter Architecture
99

100
Foundation classes and methods for implementing custom language converters.
101

102
```python { .api }
103
class Num2Word_Base:
104
    def to_cardinal(self, value): ...
105
    def to_ordinal(self, value): ...
106
    def to_currency(self, val, currency='EUR', **kwargs): ...
107
    def to_year(self, value, **kwargs): ...
108
```
109

110
[Base Converter Architecture](./base-converter.md)
111

112
### Currency Conversion
113

114
Specialized functionality for converting numbers to currency representations with proper localization.
115

116
```python { .api }
117
def to_currency(val, currency='EUR', cents=True, separator=',', adjective=False):
118
    """
119
    Convert number to currency format.
120
    
121
    Parameters:
122
    - val: Numeric value
123
    - currency: str - Currency code (default: 'EUR')
124
    - cents: bool - Verbose cents representation
125
    - separator: str - Cent separator character
126
    - adjective: bool - Include currency adjective prefix
127
    
128
    Returns:
129
    str - Formatted currency string
130
    """
131
```
132

133
[Currency Conversion](./currency-conversion.md)
134

135
### Utility Functions
136

137
Helper functions for number parsing, currency processing, and compatibility support.
138

139
```python { .api }
140
def parse_currency_parts(value, is_int_with_cents=True): ...
141
def splitbyx(n, x, format_int=True): ...
142
def get_digits(n): ...
143
```
144

145
[Utility Functions](./utility-functions.md)
146

147
### CLI Functions
148

149
Utility functions for discovering available languages and conversion types, primarily used by the command-line interface.
150

151
```python { .api }
152
def get_languages():
153
    """
154
    Get sorted list of available language codes.
155
    
156
    Returns:
157
        list: Sorted list of supported language codes
158
    """
159

160
def get_converters():
161
    """
162
    Get sorted list of available conversion types.
163
    
164
    Returns:
165
        list: Sorted list of supported conversion types
166
    """
167
```
168

169
## Types
170

171
```python { .api }
172
# Main conversion function type
173
NumericInput = Union[int, float, str, Decimal]
174

175
# Language codes (examples - see language-support.md for complete list)
176
LanguageCode = Literal[
177
    'en', 'fr', 'es', 'de', 'it', 'pt', 'ru', 'ja', 'ko', 'zh',
178
    'ar', 'hi', 'bn', 'th', 'vi', 'tr', 'pl', 'nl', 'sv', 'no',
179
    'da', 'fi', 'cs', 'sk', 'hu', 'ro', 'bg', 'hr', 'sl', 'sr',
180
    'uk', 'be', 'lt', 'lv', 'et', 'is', 'mt', 'cy', 'ga', 'gd',
181
    'eu', 'ca', 'gl', 'ast', 'oc', 'co', 'rm', 'fur', 'lij', 'pms',
182
    # ... and regional variants like 'en_IN', 'en_NG', 'fr_BE', etc.
183
]
184

185
# Conversion types
186
ConversionType = Literal['cardinal', 'ordinal', 'ordinal_num', 'year', 'currency']
187

188
# Currency codes (examples - see currency-conversion.md for complete list)
189
CurrencyCode = str  # Various currency codes supported by individual language converters
190
```