0
# Core Locale Management
1
2
Fundamental locale operations for working with locale identifiers, creating locale objects, and accessing locale-specific information. The Locale class serves as the central interface to CLDR data and locale-aware functionality throughout Babel.
3
4
## Capabilities
5
6
### Locale Class
7
8
The primary class for representing locales and accessing locale-specific data from the CLDR.
9
10
```python { .api }
11
class Locale:
12
"""
13
Represents a locale with access to CLDR data.
14
15
Attributes:
16
language (str): Language code (e.g. 'en')
17
territory (str): Territory code (e.g. 'US')
18
script (str): Script code (e.g. 'Latn')
19
variant (str): Variant code
20
modifier (str): Modifier
21
"""
22
def __init__(self, language, territory=None, script=None, variant=None, modifier=None):
23
"""
24
Initialize a locale.
25
26
Args:
27
language (str): Language code
28
territory (str, optional): Territory/country code
29
script (str, optional): Script code
30
variant (str, optional): Variant code
31
modifier (str, optional): Modifier
32
"""
33
34
@classmethod
35
def parse(cls, identifier, sep='_', resolve_likely_subtags=True):
36
"""
37
Parse a locale identifier string into a Locale object.
38
39
Args:
40
identifier (str): Locale identifier (e.g. 'en_US', 'fr-FR')
41
sep (str): Separator character ('_' or '-')
42
resolve_likely_subtags (bool): Whether to resolve likely subtags
43
44
Returns:
45
Locale: Parsed locale object
46
"""
47
48
def get_display_name(self, locale=None):
49
"""
50
Get the display name of this locale.
51
52
Args:
53
locale (Locale, optional): Locale for display names
54
55
Returns:
56
str: Display name (e.g. "English (United States)")
57
"""
58
59
def get_language_name(self, locale=None):
60
"""
61
Get the language display name.
62
63
Args:
64
locale (Locale, optional): Locale for display names
65
66
Returns:
67
str: Language name (e.g. "English")
68
"""
69
70
def get_script_name(self, locale=None):
71
"""
72
Get the script display name.
73
74
Args:
75
locale (Locale, optional): Locale for display names
76
77
Returns:
78
str: Script name (e.g. "Latin")
79
"""
80
81
def get_territory_name(self, locale=None):
82
"""
83
Get the territory display name.
84
85
Args:
86
locale (Locale, optional): Locale for display names
87
88
Returns:
89
str: Territory name (e.g. "United States")
90
"""
91
92
def plural_form(self, n):
93
"""
94
Get the plural form for a number in this locale.
95
96
Args:
97
n (int|float): Number
98
99
Returns:
100
str: Plural form ('zero', 'one', 'two', 'few', 'many', 'other')
101
"""
102
103
# Properties providing access to locale data
104
@property
105
def english_name(self):
106
"""str: English name of the locale"""
107
108
@property
109
def display_name(self):
110
"""str: Display name in the locale's own language"""
111
112
@property
113
def text_direction(self):
114
"""str: Text direction ('ltr' or 'rtl')"""
115
116
@property
117
def languages(self):
118
"""dict: Language code to display name mapping"""
119
120
@property
121
def territories(self):
122
"""dict: Territory code to display name mapping"""
123
124
@property
125
def scripts(self):
126
"""dict: Script code to display name mapping"""
127
128
@property
129
def currencies(self):
130
"""dict: Currency code to display name mapping"""
131
132
@property
133
def currency_symbols(self):
134
"""dict: Currency code to symbol mapping"""
135
136
@property
137
def number_symbols(self):
138
"""dict: Number formatting symbols (decimal, group, etc.)"""
139
140
@property
141
def decimal_formats(self):
142
"""dict: Decimal number format patterns"""
143
144
@property
145
def currency_formats(self):
146
"""dict: Currency format patterns"""
147
148
@property
149
def percent_formats(self):
150
"""dict: Percentage format patterns"""
151
152
@property
153
def scientific_formats(self):
154
"""dict: Scientific notation format patterns"""
155
156
@property
157
def datetime_formats(self):
158
"""dict: Datetime format patterns"""
159
160
@property
161
def date_formats(self):
162
"""dict: Date format patterns"""
163
164
@property
165
def time_formats(self):
166
"""dict: Time format patterns"""
167
168
@property
169
def days(self):
170
"""dict: Weekday names in various formats"""
171
172
@property
173
def months(self):
174
"""dict: Month names in various formats"""
175
176
@property
177
def quarters(self):
178
"""dict: Quarter names in various formats"""
179
180
@property
181
def eras(self):
182
"""dict: Era names (BC/AD, etc.)"""
183
184
@property
185
def time_zones(self):
186
"""dict: Time zone display names"""
187
188
@property
189
def first_week_day(self):
190
"""int: First day of week (0=Monday, 6=Sunday)"""
191
192
@property
193
def weekend_start(self):
194
"""int: Weekend start day (0=Monday, 6=Sunday)"""
195
196
@property
197
def weekend_end(self):
198
"""int: Weekend end day (0=Monday, 6=Sunday)"""
199
200
@property
201
def character_order(self):
202
"""str: Text direction ('left-to-right' or 'right-to-left')"""
203
204
@property
205
def list_patterns(self):
206
"""dict: Patterns for formatting lists"""
207
208
@property
209
def unit_display_names(self):
210
"""dict: Display names for units of measurement"""
211
212
@property
213
def default_numbering_system(self):
214
"""str: Default numbering system for this locale"""
215
216
@property
217
def other_numbering_systems(self):
218
"""dict: Other available numbering systems"""
219
```
220
221
Usage example:
222
223
```python
224
from babel import Locale
225
226
# Create locale objects
227
us_locale = Locale('en', 'US')
228
french_locale = Locale.parse('fr_FR')
229
230
# Access display information
231
print(us_locale.get_display_name()) # "English (United States)"
232
print(french_locale.get_language_name()) # "French"
233
print(us_locale.text_direction) # "ltr"
234
235
# Access formatting data
236
print(us_locale.number_symbols['decimal']) # "."
237
print(french_locale.number_symbols['decimal']) # ","
238
```
239
240
### Locale Parsing and Identification
241
242
Functions for working with locale identifier strings and building locale identifiers from components.
243
244
```python { .api }
245
def parse_locale(identifier, sep='_'):
246
"""
247
Parse a locale identifier into its components.
248
249
Args:
250
identifier (str): Locale identifier string
251
sep (str): Separator character
252
253
Returns:
254
tuple: (language, territory, script, variant) components
255
"""
256
257
def get_locale_identifier(tup, sep='_'):
258
"""
259
Build a locale identifier from components.
260
261
Args:
262
tup (tuple): (language, territory, script, variant) tuple
263
sep (str): Separator character
264
265
Returns:
266
str: Locale identifier string
267
"""
268
```
269
270
Usage example:
271
272
```python
273
from babel.core import parse_locale, get_locale_identifier
274
275
# Parse locale identifiers
276
components = parse_locale('en_US') # ('en', 'US', None, None)
277
components = parse_locale('zh-Hans-CN', sep='-') # ('zh', 'CN', 'Hans', None)
278
279
# Build locale identifiers
280
identifier = get_locale_identifier(('fr', 'CA', None, None)) # 'fr_CA'
281
```
282
283
### Default Locale Detection
284
285
Get the system's default locale with fallback handling.
286
287
```python { .api }
288
def default_locale(category=None, aliases=None):
289
"""
290
Get the system default locale.
291
292
Args:
293
category (str, optional): Locale category (LC_ALL, LC_CTYPE, etc.)
294
aliases (dict, optional): Locale aliases mapping
295
296
Returns:
297
str: Default locale identifier with fallback to 'en_US_POSIX'
298
"""
299
```
300
301
Usage example:
302
303
```python
304
from babel.core import default_locale
305
306
system_locale = default_locale() # e.g. 'en_US'
307
```
308
309
### Locale Negotiation
310
311
Negotiate the best matching locale from a list of preferred and available locales.
312
313
```python { .api }
314
def negotiate_locale(preferred, available, sep='_', aliases=None):
315
"""
316
Negotiate the best matching locale from preferences.
317
318
Args:
319
preferred (iterable): Preferred locale identifiers in priority order
320
available (iterable): Available locale identifiers
321
sep (str): Separator character
322
aliases (dict, optional): Locale aliases mapping
323
324
Returns:
325
str|None: Best matching locale identifier or None if no match
326
"""
327
```
328
329
Usage example:
330
331
```python
332
from babel.core import negotiate_locale
333
334
preferred = ['de_DE', 'de', 'en_US', 'en']
335
available = ['en', 'fr', 'de_AT']
336
best_match = negotiate_locale(preferred, available) # 'de_AT'
337
```
338
339
### CLDR Data Access
340
341
Access global CLDR data by key.
342
343
```python { .api }
344
def get_global(key):
345
"""
346
Access global CLDR data by key.
347
348
Args:
349
key (str): CLDR data key
350
351
Returns:
352
Mapping: CLDR data for the specified key
353
"""
354
```
355
356
## Exception Classes
357
358
```python { .api }
359
class UnknownLocaleError(Exception):
360
"""Raised when an unknown or invalid locale identifier is used."""
361
```