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.

property character_order

The text direction for the language.

>>> Locale('de', 'DE').character_order
'left-to-right'
>>> Locale('ar', 'SA').character_order
'right-to-left'

property 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'

property 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)'>

property currency_symbols

Mapping of currency codes to symbols.

>>> Locale('en', 'US').currency_symbols['USD']
u'$'
>>> Locale('es', 'CO').currency_symbols['USD']
u'US$'

property 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'>

property 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}'

property 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'">

property day_period_rules

Day period rules for the locale. Used by get_period_id.

property 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.

property days

Locale display names for weekdays.

>>> Locale('de', 'DE').days['format']['wide'][3]
u'Donnerstag'

property 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={'ar': 'ar_SY', 'bg': 'bg_BG', 'bs': 'bs_BA', 'ca': 'ca_ES', 'cs': 'cs_CZ', 'da': 'da_DK', 'de': 'de_DE', 'el': 'el_GR', 'en': 'en_US', 'es': 'es_ES', 'et': 'et_EE', 'fa': 'fa_IR', 'fi': 'fi_FI', 'fr': 'fr_FR', 'gl': 'gl_ES', 'he': 'he_IL', 'hu': 'hu_HU', 'id': 'id_ID', 'is': 'is_IS', 'it': 'it_IT', 'ja': 'ja_JP', 'km': 'km_KH', 'ko': 'ko_KR', 'lt': 'lt_LT', 'lv': 'lv_LV', 'mk': 'mk_MK', 'nl': 'nl_NL', 'nn': 'nn_NO', 'no': 'nb_NO', 'pl': 'pl_PL', 'pt': 'pt_PT', 'ro': 'ro_RO', 'ru': 'ru_RU', 'sk': 'sk_SK', 'sl': 'sl_SI', 'sv': 'sv_SE', 'th': 'th_TH', 'tr': 'tr_TR', 'uk': 'uk_UA'})

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

property 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

property 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

property 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'

property 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.

property 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. – ', 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

the language code

property language_name

The localized language name of the locale.

>>> Locale('en', 'US').language_name
u'English'

property languages

Mapping of language codes to translated language names.

>>> Locale('de', 'DE').languages['ja']
u'Japanisch'

See ISO 639 for more information.

property list_patterns

Patterns for generating lists

Note

The format of the value returned may change between Babel versions.

>>> Locale('en').list_patterns['standard']['start']
u'{0}, {1}'
>>> Locale('en').list_patterns['standard']['end']
u'{0}, and {1}'
>>> Locale('en_GB').list_patterns['standard']['end']
u'{0} and {1}'

property 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'

property 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.

property 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

property months

Locale display names for months.

>>> Locale('de', 'DE').months['format']['wide'][10]
u'Oktober'

classmethod negotiate(preferred, available, sep='_', aliases={'ar': 'ar_SY', 'bg': 'bg_BG', 'bs': 'bs_BA', 'ca': 'ca_ES', 'cs': 'cs_CZ', 'da': 'da_DK', 'de': 'de_DE', 'el': 'el_GR', 'en': 'en_US', 'es': 'es_ES', 'et': 'et_EE', 'fa': 'fa_IR', 'fi': 'fi_FI', 'fr': 'fr_FR', 'gl': 'gl_ES', 'he': 'he_IL', 'hu': 'hu_HU', 'id': 'id_ID', 'is': 'is_IS', 'it': 'it_IT', 'ja': 'ja_JP', 'km': 'km_KH', 'ko': 'ko_KR', 'lt': 'lt_LT', 'lv': 'lv_LV', 'mk': 'mk_MK', 'nl': 'nl_NL', 'nn': 'nn_NO', 'no': 'nb_NO', 'pl': 'pl_PL', 'pt': 'pt_PT', 'ro': 'ro_RO', 'ru': 'ru_RU', 'sk': 'sk_SK', 'sl': 'sl_SI', 'sv': 'sv_SE', 'th': 'th_TH', 'tr': 'tr_TR', 'uk': 'uk_UA'})

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

property 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','

property 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 of zh_hant_TW. Note that this expansion is only taking place if no locale exists otherwise. For instance there is a locale en 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

property 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%'>

property periods

Locale display names for day periods (AM/PM).

>>> Locale('en', 'US').periods['am']
u'AM'

property 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'

property quarters

Locale display names for quarters.

>>> Locale('de', 'DE').quarters['format']['wide'][1]
u'1. Quartal'

property 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

the script code

property script_name

The localized script name of the locale if available.

>>> Locale('sr', 'ME', script='Latn').script_name
u'latinica'

property scripts

Mapping of script codes to translated script names.

>>> Locale('en', 'US').scripts['Hira']
u'Hiragana'

See ISO 15924 for more information.

property territories

Mapping of script codes to translated script names.

>>> Locale('es', 'CO').territories['DE']
u'Alemania'

See ISO 3166 for more information.

territory

the territory (country or region) code

property territory_name

The localized territory name of the locale if available.

>>> Locale('de', 'DE').territory_name
u'Deutschland'

property 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'

property 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'>

property 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’s'

property 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

the variant code

property variants

Mapping of script codes to translated script names.

>>> Locale('de', 'DE').variants['1901']
u'Alte deutsche Rechtschreibung'

property weekend_end

The day the weekend ends, with 0 being Monday.

>>> Locale('de', 'DE').weekend_end
6

property weekend_start

The day the weekend starts, with 0 being Monday.

>>> Locale('de', 'DE').weekend_start
5

property 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={'ar': 'ar_SY', 'bg': 'bg_BG', 'bs': 'bs_BA', 'ca': 'ca_ES', 'cs': 'cs_CZ', 'da': 'da_DK', 'de': 'de_DE', 'el': 'el_GR', 'en': 'en_US', 'es': 'es_ES', 'et': 'et_EE', 'fa': 'fa_IR', 'fi': 'fi_FI', 'fr': 'fr_FR', 'gl': 'gl_ES', 'he': 'he_IL', 'hu': 'hu_HU', 'id': 'id_ID', 'is': 'is_IS', 'it': 'it_IT', 'ja': 'ja_JP', 'km': 'km_KH', 'ko': 'ko_KR', 'lt': 'lt_LT', 'lv': 'lv_LV', 'mk': 'mk_MK', 'nl': 'nl_NL', 'nn': 'nn_NO', 'no': 'nb_NO', 'pl': 'pl_PL', 'pt': 'pt_PT', 'ro': 'ro_RO', 'ru': 'ru_RU', 'sk': 'sk_SK', 'sl': 'sl_SI', 'sv': 'sv_SE', 'th': 'th_TH', 'tr': 'tr_TR', 'uk': 'uk_UA'})

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={'ar': 'ar_SY', 'bg': 'bg_BG', 'bs': 'bs_BA', 'ca': 'ca_ES', 'cs': 'cs_CZ', 'da': 'da_DK', 'de': 'de_DE', 'el': 'el_GR', 'en': 'en_US', 'es': 'es_ES', 'et': 'et_EE', 'fa': 'fa_IR', 'fi': 'fi_FI', 'fr': 'fr_FR', 'gl': 'gl_ES', 'he': 'he_IL', 'hu': 'hu_HU', 'id': 'id_ID', 'is': 'is_IS', 'it': 'it_IT', 'ja': 'ja_JP', 'km': 'km_KH', 'ko': 'ko_KR', 'lt': 'lt_LT', 'lv': 'lv_LV', 'mk': 'mk_MK', 'nl': 'nl_NL', 'nn': 'nn_NO', 'no': 'nb_NO', 'pl': 'pl_PL', 'pt': 'pt_PT', 'ro': 'ro_RO', 'ru': 'ru_RU', 'sk': 'sk_SK', 'sl': 'sl_SI', 'sv': 'sv_SE', 'th': 'th_TH', 'tr': 'tr_TR', 'uk': 'uk_UA'})

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 language-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

exception babel.core.UnknownLocaleError(identifier)

Exception thrown when a locale is requested for which no locale data is available.

identifier

The identifier of the locale that could not be found.

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/UTC'
>>> 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)
>>> parse_locale('ca_es_valencia')
('ca', 'ES', None, 'VALENCIA')
>>> parse_locale('en_150')
('en', '150', None, None)
>>> parse_locale('en_us_posix')
('en', 'US', None, 'POSIX')

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 to None and trailing Nones 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.