Core Functionality¶
The core API provides the basic core functionality. Primarily it provides
the Locale
object and ways to create it. This object
encapsulates a locale and exposes all the data it contains.
All the core functionality is also directly importable from the babel module for convenience.
Basic Interface¶
-
class
babel.core.
Locale
(language, territory=None, script=None, variant=None)¶ Representation of a specific locale.
>>> locale = Locale('en', 'US') >>> repr(locale) "Locale('en', territory='US')" >>> locale.display_name u'English (United States)'
A Locale object can also be instantiated from a raw locale string:
>>> locale = Locale.parse('en-US', sep='-') >>> repr(locale) "Locale('en', territory='US')"
Locale objects provide access to a collection of locale data, such as territory and language names, number and date format patterns, and more:
>>> locale.number_symbols['decimal'] u'.'
If a locale is requested for which no locale data is available, an UnknownLocaleError is raised:
>>> Locale.parse('en_XX') Traceback (most recent call last): ... UnknownLocaleError: unknown locale 'en_XX'
For more information see RFC 3066.
-
character_order
¶ The text direction for the language.
>>> Locale('de', 'DE').character_order 'left-to-right' >>> Locale('ar', 'SA').character_order 'right-to-left'
-
currencies
¶ Mapping of currency codes to translated currency names. This only returns the generic form of the currency name, not the count specific one. If an actual number is requested use the
babel.numbers.get_currency_name()
function.>>> Locale('en').currencies['COP'] u'Colombian Peso' >>> Locale('de', 'DE').currencies['COP'] u'Kolumbianischer Peso'
-
currency_formats
¶ Locale patterns for currency number formatting.
Note
The format of the value returned may change between Babel versions.
>>> Locale('en', 'US').currency_formats['standard'] <NumberPattern u'\xa4#,##0.00'> >>> Locale('en', 'US').currency_formats['accounting'] <NumberPattern u'\xa4#,##0.00;(\xa4#,##0.00)'>
-
currency_symbols
¶ Mapping of currency codes to symbols.
>>> Locale('en', 'US').currency_symbols['USD'] u'$' >>> Locale('es', 'CO').currency_symbols['USD'] u'US$'
-
date_formats
¶ Locale patterns for date formatting.
Note
The format of the value returned may change between Babel versions.
>>> Locale('en', 'US').date_formats['short'] <DateTimePattern u'M/d/yy'> >>> Locale('fr', 'FR').date_formats['long'] <DateTimePattern u'd MMMM y'>
-
datetime_formats
¶ Locale patterns for datetime formatting.
Note
The format of the value returned may change between Babel versions.
>>> Locale('en').datetime_formats['full'] u"{1} 'at' {0}" >>> Locale('th').datetime_formats['medium'] u'{1} {0}'
-
datetime_skeletons
¶ Locale patterns for formatting parts of a datetime.
>>> Locale('en').datetime_skeletons['MEd'] <DateTimePattern u'E, M/d'> >>> Locale('fr').datetime_skeletons['MEd'] <DateTimePattern u'E dd/MM'> >>> Locale('fr').datetime_skeletons['H'] <DateTimePattern u"HH 'h'">
-
day_period_rules
¶ Day period rules for the locale. Used by get_period_id.
-
day_periods
¶ Locale display names for various day periods (not necessarily only AM/PM).
These are not meant to be used without the relevant day_period_rules.
-
days
¶ Locale display names for weekdays.
>>> Locale('de', 'DE').days['format']['wide'][3] u'Donnerstag'
-
decimal_formats
¶ Locale patterns for decimal number formatting.
Note
The format of the value returned may change between Babel versions.
>>> Locale('en', 'US').decimal_formats[None] <NumberPattern u'#,##0.###'>
-
classmethod
default
(category=None, aliases={'el': 'el_GR', 'fi': 'fi_FI', 'bg': 'bg_BG', 'uk': 'uk_UA', 'tr': 'tr_TR', 'ca': 'ca_ES', 'de': 'de_DE', 'fr': 'fr_FR', 'da': 'da_DK', 'fa': 'fa_IR', 'ar': 'ar_SY', 'mk': 'mk_MK', 'bs': 'bs_BA', 'cs': 'cs_CZ', 'et': 'et_EE', 'gl': 'gl_ES', 'id': 'id_ID', 'es': 'es_ES', 'he': 'he_IL', 'ru': 'ru_RU', 'nl': 'nl_NL', 'pt': 'pt_PT', 'nn': 'nn_NO', 'no': 'nb_NO', 'ko': 'ko_KR', 'sv': 'sv_SE', 'km': 'km_KH', 'ja': 'ja_JP', 'lv': 'lv_LV', 'lt': 'lt_LT', 'en': 'en_US', 'sk': 'sk_SK', 'th': 'th_TH', 'sl': 'sl_SI', 'it': 'it_IT', 'hu': 'hu_HU', 'ro': 'ro_RO', 'is': 'is_IS', 'pl': 'pl_PL'})¶ Return the system default locale for the specified category.
>>> for name in ['LANGUAGE', 'LC_ALL', 'LC_CTYPE', 'LC_MESSAGES']: ... os.environ[name] = '' >>> os.environ['LANG'] = 'fr_FR.UTF-8' >>> Locale.default('LC_MESSAGES') Locale('fr', territory='FR')
The following fallbacks to the variable are always considered:
LANGUAGE
LC_ALL
LC_CTYPE
LANG
Parameters: - category – one of the
LC_XXX
environment variable names - aliases – a dictionary of aliases for locale identifiers
-
display_name
¶ The localized display name of the locale.
>>> Locale('en').display_name u'English' >>> Locale('en', 'US').display_name u'English (United States)' >>> Locale('sv').display_name u'svenska'
Type: unicode
-
english_name
¶ The english display name of the locale.
>>> Locale('de').english_name u'German' >>> Locale('de', 'DE').english_name u'German (Germany)'
Type: unicode
-
eras
¶ Locale display names for eras.
Note
The format of the value returned may change between Babel versions.
>>> Locale('en', 'US').eras['wide'][1] u'Anno Domini' >>> Locale('en', 'US').eras['abbreviated'][0] u'BC'
-
first_week_day
¶ The first day of a week, with 0 being Monday.
>>> Locale('de', 'DE').first_week_day 0 >>> Locale('en', 'US').first_week_day 6
-
get_display_name
(locale=None)¶ Return the display name of the locale using the given locale.
The display name will include the language, territory, script, and variant, if those are specified.
>>> Locale('zh', 'CN', script='Hans').get_display_name('en') u'Chinese (Simplified, China)'
Parameters: locale – the locale to use
-
get_language_name
(locale=None)¶ Return the language of this locale in the given locale.
>>> Locale('zh', 'CN', script='Hans').get_language_name('de') u'Chinesisch'
New in version 1.0.
Parameters: locale – the locale to use
-
get_script_name
(locale=None)¶ Return the script name in the given locale.
-
get_territory_name
(locale=None)¶ Return the territory name in the given locale.
-
interval_formats
¶ Locale patterns for interval formatting.
Note
The format of the value returned may change between Babel versions.
How to format date intervals in Finnish when the day is the smallest changing component:
>>> Locale('fi_FI').interval_formats['MEd']['d'] [u'E d. \u2013 ', u'E d.M.']
See also
The primary API to use this data is
babel.dates.format_interval()
.Return type: dict[str, dict[str, list[str]]]
-
language
= None¶ the language code
-
language_name
¶ The localized language name of the locale.
>>> Locale('en', 'US').language_name u'English'
-
languages
¶ Mapping of language codes to translated language names.
>>> Locale('de', 'DE').languages['ja'] u'Japanisch'
See ISO 639 for more information.
-
list_patterns
¶ Patterns for generating lists
Note
The format of the value returned may change between Babel versions.
>>> Locale('en').list_patterns['start'] u'{0}, {1}' >>> Locale('en').list_patterns['end'] u'{0}, and {1}' >>> Locale('en_GB').list_patterns['end'] u'{0} and {1}'
-
measurement_systems
¶ Localized names for various measurement systems.
>>> Locale('fr', 'FR').measurement_systems['US'] u'am\xe9ricain' >>> Locale('en', 'US').measurement_systems['US'] u'US'
-
meta_zones
¶ Locale display names for meta time zones.
Meta time zones are basically groups of different Olson time zones that have the same GMT offset and daylight savings time.
Note
The format of the value returned may change between Babel versions.
>>> Locale('en', 'US').meta_zones['Europe_Central']['long']['daylight'] u'Central European Summer Time'
New in version 0.9.
-
min_week_days
¶ The minimum number of days in a week so that the week is counted as the first week of a year or month.
>>> Locale('de', 'DE').min_week_days 4
-
months
¶ Locale display names for months.
>>> Locale('de', 'DE').months['format']['wide'][10] u'Oktober'
-
classmethod
negotiate
(preferred, available, sep='_', aliases={'el': 'el_GR', 'fi': 'fi_FI', 'bg': 'bg_BG', 'uk': 'uk_UA', 'tr': 'tr_TR', 'ca': 'ca_ES', 'de': 'de_DE', 'fr': 'fr_FR', 'da': 'da_DK', 'fa': 'fa_IR', 'ar': 'ar_SY', 'mk': 'mk_MK', 'bs': 'bs_BA', 'cs': 'cs_CZ', 'et': 'et_EE', 'gl': 'gl_ES', 'id': 'id_ID', 'es': 'es_ES', 'he': 'he_IL', 'ru': 'ru_RU', 'nl': 'nl_NL', 'pt': 'pt_PT', 'nn': 'nn_NO', 'no': 'nb_NO', 'ko': 'ko_KR', 'sv': 'sv_SE', 'km': 'km_KH', 'ja': 'ja_JP', 'lv': 'lv_LV', 'lt': 'lt_LT', 'en': 'en_US', 'sk': 'sk_SK', 'th': 'th_TH', 'sl': 'sl_SI', 'it': 'it_IT', 'hu': 'hu_HU', 'ro': 'ro_RO', 'is': 'is_IS', 'pl': 'pl_PL'})¶ Find the best match between available and requested locale strings.
>>> Locale.negotiate(['de_DE', 'en_US'], ['de_DE', 'de_AT']) Locale('de', territory='DE') >>> Locale.negotiate(['de_DE', 'en_US'], ['en', 'de']) Locale('de') >>> Locale.negotiate(['de_DE', 'de'], ['en_US'])
You can specify the character used in the locale identifiers to separate the differnet components. This separator is applied to both lists. Also, case is ignored in the comparison:
>>> Locale.negotiate(['de-DE', 'de'], ['en-us', 'de-de'], sep='-') Locale('de', territory='DE')
Parameters: - preferred – the list of locale identifers preferred by the user
- available – the list of locale identifiers available
- aliases – a dictionary of aliases for locale identifiers
-
number_symbols
¶ Symbols used in number formatting.
Note
The format of the value returned may change between Babel versions.
>>> Locale('fr', 'FR').number_symbols['decimal'] u','
-
ordinal_form
¶ Plural rules for the locale.
>>> Locale('en').ordinal_form(1) 'one' >>> Locale('en').ordinal_form(2) 'two' >>> Locale('en').ordinal_form(3) 'few' >>> Locale('fr').ordinal_form(2) 'other' >>> Locale('ru').ordinal_form(100) 'other'
-
classmethod
parse
(identifier, sep='_', resolve_likely_subtags=True)¶ Create a Locale instance for the given locale identifier.
>>> l = Locale.parse('de-DE', sep='-') >>> l.display_name u'Deutsch (Deutschland)'
If the identifier parameter is not a string, but actually a Locale object, that object is returned:
>>> Locale.parse(l) Locale('de', territory='DE')
This also can perform resolving of likely subtags which it does by default. This is for instance useful to figure out the most likely locale for a territory you can use
'und'
as the language tag:>>> Locale.parse('und_AT') Locale('de', territory='AT')
Parameters: - identifier – the locale identifier string
- sep – optional component separator
- resolve_likely_subtags – if this is specified then a locale will
have its likely subtag resolved if the
locale otherwise does not exist. For
instance
zh_TW
by itself is not a locale that exists but Babel can automatically expand it to the full form ofzh_hant_TW
. Note that this expansion is only taking place if no locale exists otherwise. For instance there is a localeen
that can exist by itself.
Raises: - ValueError – if the string does not appear to be a valid locale identifier
- UnknownLocaleError – if no locale data is available for the requested locale
-
percent_formats
¶ Locale patterns for percent number formatting.
Note
The format of the value returned may change between Babel versions.
>>> Locale('en', 'US').percent_formats[None] <NumberPattern u'#,##0%'>
-
periods
¶ Locale display names for day periods (AM/PM).
>>> Locale('en', 'US').periods['am'] u'AM'
-
plural_form
¶ Plural rules for the locale.
>>> Locale('en').plural_form(1) 'one' >>> Locale('en').plural_form(0) 'other' >>> Locale('fr').plural_form(0) 'one' >>> Locale('ru').plural_form(100) 'many'
-
quarters
¶ Locale display names for quarters.
>>> Locale('de', 'DE').quarters['format']['wide'][1] u'1. Quartal'
-
scientific_formats
¶ Locale patterns for scientific number formatting.
Note
The format of the value returned may change between Babel versions.
>>> Locale('en', 'US').scientific_formats[None] <NumberPattern u'#E0'>
-
script
= None¶ the script code
-
script_name
¶ The localized script name of the locale if available.
>>> Locale('sr', 'ME', script='Latn').script_name u'latinica'
-
scripts
¶ Mapping of script codes to translated script names.
>>> Locale('en', 'US').scripts['Hira'] u'Hiragana'
See ISO 15924 for more information.
-
territories
¶ Mapping of script codes to translated script names.
>>> Locale('es', 'CO').territories['DE'] u'Alemania'
See ISO 3166 for more information.
-
territory
= None¶ the territory (country or region) code
-
territory_name
¶ The localized territory name of the locale if available.
>>> Locale('de', 'DE').territory_name u'Deutschland'
-
text_direction
¶ The text direction for the language in CSS short-hand form.
>>> Locale('de', 'DE').text_direction 'ltr' >>> Locale('ar', 'SA').text_direction 'rtl'
-
time_formats
¶ Locale patterns for time formatting.
Note
The format of the value returned may change between Babel versions.
>>> Locale('en', 'US').time_formats['short'] <DateTimePattern u'h:mm a'> >>> Locale('fr', 'FR').time_formats['long'] <DateTimePattern u'HH:mm:ss z'>
-
time_zones
¶ Locale display names for time zones.
Note
The format of the value returned may change between Babel versions.
>>> Locale('en', 'US').time_zones['Europe/London']['long']['daylight'] u'British Summer Time' >>> Locale('en', 'US').time_zones['America/St_Johns']['city'] u'St. John\u2019s'
-
unit_display_names
¶ Display names for units of measurement.
See also
You may want to use
babel.units.get_unit_name()
instead.Note
The format of the value returned may change between Babel versions.
-
variant
= None¶ the variant code
-
variants
¶ Mapping of script codes to translated script names.
>>> Locale('de', 'DE').variants['1901'] u'Alte deutsche Rechtschreibung'
-
weekend_end
¶ The day the weekend ends, with 0 being Monday.
>>> Locale('de', 'DE').weekend_end 6
-
weekend_start
¶ The day the weekend starts, with 0 being Monday.
>>> Locale('de', 'DE').weekend_start 5
-
zone_formats
¶ Patterns related to the formatting of time zones.
Note
The format of the value returned may change between Babel versions.
>>> Locale('en', 'US').zone_formats['fallback'] u'%(1)s (%(0)s)' >>> Locale('pt', 'BR').zone_formats['region'] u'Hor\xe1rio %s'
New in version 0.9.
-
-
babel.core.
default_locale
(category=None, aliases={'el': 'el_GR', 'fi': 'fi_FI', 'bg': 'bg_BG', 'uk': 'uk_UA', 'tr': 'tr_TR', 'ca': 'ca_ES', 'de': 'de_DE', 'fr': 'fr_FR', 'da': 'da_DK', 'fa': 'fa_IR', 'ar': 'ar_SY', 'mk': 'mk_MK', 'bs': 'bs_BA', 'cs': 'cs_CZ', 'et': 'et_EE', 'gl': 'gl_ES', 'id': 'id_ID', 'es': 'es_ES', 'he': 'he_IL', 'ru': 'ru_RU', 'nl': 'nl_NL', 'pt': 'pt_PT', 'nn': 'nn_NO', 'no': 'nb_NO', 'ko': 'ko_KR', 'sv': 'sv_SE', 'km': 'km_KH', 'ja': 'ja_JP', 'lv': 'lv_LV', 'lt': 'lt_LT', 'en': 'en_US', 'sk': 'sk_SK', 'th': 'th_TH', 'sl': 'sl_SI', 'it': 'it_IT', 'hu': 'hu_HU', 'ro': 'ro_RO', 'is': 'is_IS', 'pl': 'pl_PL'})¶ Returns the system default locale for a given category, based on environment variables.
>>> for name in ['LANGUAGE', 'LC_ALL', 'LC_CTYPE']: ... os.environ[name] = '' >>> os.environ['LANG'] = 'fr_FR.UTF-8' >>> default_locale('LC_MESSAGES') 'fr_FR'
The “C” or “POSIX” pseudo-locales are treated as aliases for the “en_US_POSIX” locale:
>>> os.environ['LC_MESSAGES'] = 'POSIX' >>> default_locale('LC_MESSAGES') 'en_US_POSIX'
The following fallbacks to the variable are always considered:
LANGUAGE
LC_ALL
LC_CTYPE
LANG
Parameters: - category – one of the
LC_XXX
environment variable names - aliases – a dictionary of aliases for locale identifiers
-
babel.core.
negotiate_locale
(preferred, available, sep='_', aliases={'el': 'el_GR', 'fi': 'fi_FI', 'bg': 'bg_BG', 'uk': 'uk_UA', 'tr': 'tr_TR', 'ca': 'ca_ES', 'de': 'de_DE', 'fr': 'fr_FR', 'da': 'da_DK', 'fa': 'fa_IR', 'ar': 'ar_SY', 'mk': 'mk_MK', 'bs': 'bs_BA', 'cs': 'cs_CZ', 'et': 'et_EE', 'gl': 'gl_ES', 'id': 'id_ID', 'es': 'es_ES', 'he': 'he_IL', 'ru': 'ru_RU', 'nl': 'nl_NL', 'pt': 'pt_PT', 'nn': 'nn_NO', 'no': 'nb_NO', 'ko': 'ko_KR', 'sv': 'sv_SE', 'km': 'km_KH', 'ja': 'ja_JP', 'lv': 'lv_LV', 'lt': 'lt_LT', 'en': 'en_US', 'sk': 'sk_SK', 'th': 'th_TH', 'sl': 'sl_SI', 'it': 'it_IT', 'hu': 'hu_HU', 'ro': 'ro_RO', 'is': 'is_IS', 'pl': 'pl_PL'})¶ Find the best match between available and requested locale strings.
>>> negotiate_locale(['de_DE', 'en_US'], ['de_DE', 'de_AT']) 'de_DE' >>> negotiate_locale(['de_DE', 'en_US'], ['en', 'de']) 'de'
Case is ignored by the algorithm, the result uses the case of the preferred locale identifier:
>>> negotiate_locale(['de_DE', 'en_US'], ['de_de', 'de_at']) 'de_DE'
>>> negotiate_locale(['de_DE', 'en_US'], ['de_de', 'de_at']) 'de_DE'
By default, some web browsers unfortunately do not include the territory in the locale identifier for many locales, and some don’t even allow the user to easily add the territory. So while you may prefer using qualified locale identifiers in your web-application, they would not normally match the language-only locale sent by such browsers. To workaround that, this function uses a default mapping of commonly used langauge-only locale identifiers to identifiers including the territory:
>>> negotiate_locale(['ja', 'en_US'], ['ja_JP', 'en_US']) 'ja_JP'
Some browsers even use an incorrect or outdated language code, such as “no” for Norwegian, where the correct locale identifier would actually be “nb_NO” (Bokmål) or “nn_NO” (Nynorsk). The aliases are intended to take care of such cases, too:
>>> negotiate_locale(['no', 'sv'], ['nb_NO', 'sv_SE']) 'nb_NO'
You can override this default mapping by passing a different aliases dictionary to this function, or you can bypass the behavior althogher by setting the aliases parameter to None.
Parameters: - preferred – the list of locale strings preferred by the user
- available – the list of locale strings available
- sep – character that separates the different parts of the locale strings
- aliases – a dictionary of aliases for locale identifiers
Exceptions¶
Utility Functions¶
-
babel.core.
get_global
(key)¶ Return the dictionary for the given key in the global data.
The global data is stored in the
babel/global.dat
file and contains information independent of individual locales.>>> get_global('zone_aliases')['UTC'] u'Etc/GMT' >>> get_global('zone_territories')['Europe/Berlin'] u'DE'
The keys available are:
all_currencies
currency_fractions
language_aliases
likely_subtags
parent_exceptions
script_aliases
territory_aliases
territory_currencies
territory_languages
territory_zones
variant_aliases
windows_zone_mapping
zone_aliases
zone_territories
Note
The internal structure of the data may change between versions.
New in version 0.9.
Parameters: key – the data key
-
babel.core.
parse_locale
(identifier, sep='_')¶ Parse a locale identifier into a tuple of the form
(language, territory, script, variant)
.>>> parse_locale('zh_CN') ('zh', 'CN', None, None) >>> parse_locale('zh_Hans_CN') ('zh', 'CN', 'Hans', None)
The default component separator is “_”, but a different separator can be specified using the sep parameter:
>>> parse_locale('zh-CN', sep='-') ('zh', 'CN', None, None)
If the identifier cannot be parsed into a locale, a ValueError exception is raised:
>>> parse_locale('not_a_LOCALE_String') Traceback (most recent call last): ... ValueError: 'not_a_LOCALE_String' is not a valid locale identifier
Encoding information and locale modifiers are removed from the identifier:
>>> parse_locale('it_IT@euro') ('it', 'IT', None, None) >>> parse_locale('en_US.UTF-8') ('en', 'US', None, None) >>> parse_locale('de_DE.iso885915@euro') ('de', 'DE', None, None)
See RFC 4646 for more information.
Parameters: - identifier – the locale identifier string
- sep – character that separates the different components of the locale identifier
Raises: ValueError – if the string does not appear to be a valid locale identifier
-
babel.core.
get_locale_identifier
(tup, sep='_')¶ The reverse of
parse_locale()
. It creates a locale identifier out of a(language, territory, script, variant)
tuple. Items can be set toNone
and trailingNone
s can also be left out of the tuple.>>> get_locale_identifier(('de', 'DE', None, '1999')) 'de_DE_1999'
New in version 1.0.
Parameters: - tup – the tuple as returned by
parse_locale()
. - sep – the separator for the identifier.
- tup – the tuple as returned by