class documentation

class Locale(object):

View In Hierarchy

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.

Class Method default Return the system default locale for the specified category.
Class Method negotiate Find the best match between available and requested locale strings.
Class Method parse Create a Locale instance for the given locale identifier.
Method get​_display​_name Return the display name of the locale using the given locale.
Method get​_language​_name Return the language of this locale in the given locale.
Method get​_script​_name Return the script name in the given locale.
Method get​_territory​_name Return the territory name in the given locale.
Class Variable display​_name Undocumented
Class Variable language​_name Undocumented
Class Variable script​_name Undocumented
Class Variable territory​_name Undocumented
Instance Variable language Undocumented
Instance Variable script Undocumented
Instance Variable territory Undocumented
Instance Variable variant Undocumented
Method __eq__ Undocumented
Method __hash__ Undocumented
Method __init__ Initialize the locale object from the given identifier components.
Method __ne__ Undocumented
Method __repr__ Undocumented
Method __str__ Undocumented
Instance Variable __data Undocumented
Property ​_data Undocumented
Property character​_order The text direction for the language.
Property currencies No summary
Property currency​_formats Locale patterns for currency number formatting.
Property currency​_symbols Mapping of currency codes to symbols.
Property date​_formats Locale patterns for date formatting.
Property datetime​_formats Locale patterns for datetime formatting.
Property datetime​_skeletons Locale patterns for formatting parts of a datetime.
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).
Property days Locale display names for weekdays.
Property decimal​_formats Locale patterns for decimal number formatting.
Property english​_name The english display name of the locale.
Property eras Locale display names for eras.
Property first​_week​_day The first day of a week, with 0 being Monday.
Property interval​_formats Locale patterns for interval formatting.
Property languages Mapping of language codes to translated language names.
Property list​_patterns Patterns for generating lists
Property measurement​_systems Localized names for various measurement systems.
Property meta​_zones Locale display names for meta time zones.
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.
Property months Locale display names for months.
Property number​_symbols Symbols used in number formatting.
Property ordinal​_form Plural rules for the locale.
Property percent​_formats Locale patterns for percent number formatting.
Property periods Locale display names for day periods (AM/PM).
Property plural​_form Plural rules for the locale.
Property quarters Locale display names for quarters.
Property scientific​_formats Locale patterns for scientific number formatting.
Property scripts Mapping of script codes to translated script names.
Property territories Mapping of script codes to translated script names.
Property text​_direction The text direction for the language in CSS short-hand form.
Property time​_formats Locale patterns for time formatting.
Property time​_zones Locale display names for time zones.
Property unit​_display​_names Display names for units of measurement.
Property variants Mapping of script codes to translated script names.
Property weekend​_end The day the weekend ends, with 0 being Monday.
Property weekend​_start The day the weekend starts, with 0 being Monday.
Property zone​_formats Patterns related to the formatting of time zones.
@classmethod
def default(cls, category=None, aliases=LOCALE_ALIASES):

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
categoryone of the LC_XXX environment variable names
aliasesa dictionary of aliases for locale identifiers
@classmethod
def negotiate(cls, preferred, available, sep='_', aliases=LOCALE_ALIASES):

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
preferredthe list of locale identifers preferred by the user
availablethe list of locale identifiers available
sepUndocumented
aliasesa dictionary of aliases for locale identifiers
@classmethod
def parse(cls, 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
identifierthe locale identifier string
sepoptional component separator
resolve​_likely​_subtagsif 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
ValueErrorif the string does not appear to be a valid locale identifier
UnknownLocaleErrorif no locale data is available for the requested locale
def get_display_name(self, 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
localethe locale to use
def get_language_name(self, 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
localethe locale to use
def get_script_name(self, locale=None):
Return the script name in the given locale.
def get_territory_name(self, locale=None):
Return the territory name in the given locale.
display_name =

Undocumented

language_name =

Undocumented

script_name =

Undocumented

territory_name =

Undocumented

language =

Undocumented

script =

Undocumented

territory =

Undocumented

variant =

Undocumented

def __eq__(self, other):

Undocumented

def __hash__(self):

Undocumented

def __init__(self, language, territory=None, script=None, variant=None):

Initialize the locale object from the given identifier components.

>>> locale = Locale('en', 'US')
>>> locale.language
'en'
>>> locale.territory
'US'
Parameters
languagethe language code
territorythe territory (country or region) code
scriptthe script code
variantthe variant code
Raises
UnknownLocaleErrorif no locale data is available for the requested locale
def __ne__(self, other):

Undocumented

def __repr__(self):

Undocumented

def __str__(self):

Undocumented

__data =

Undocumented

@property
_data =

Undocumented

@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.###'>
@property
english_name =

The english display name of the locale.

>>> Locale('de').english_name
u'German'
>>> Locale('de', 'DE').english_name
u'German (Germany)'
@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
@property
interval_formats: dict[str, dict[str, list[str]]] =

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.

@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'
@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'
@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'>
@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.

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

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