locale — Internationalization services¶

Source code:Lib/locale.py

Thelocale module opens access to the POSIX locale database andfunctionality. The POSIX locale mechanism allows programmers to deal withcertain cultural issues in an application, without requiring the programmer toknow all the specifics of each country where the software is executed.

Thelocale module is implemented on top of the_locale module,which in turn uses an ANSI C locale implementation if available.

Thelocale module defines the following exception and functions:

exceptionlocale.Error¶

Exception raised when the locale passed tosetlocale() is notrecognized.

locale.setlocale(category,locale=None)¶

Iflocale is given and notNone,setlocale() modifies the localesetting for thecategory. The available categories are listed in the datadescription below.locale may be a string, or an iterable of two strings(language code and encoding). If it’s an iterable, it’s converted to a localename using the locale aliasing engine. An empty string specifies the user’sdefault settings. If the modification of the locale fails, the exceptionError is raised. If successful, the new locale setting is returned.

Iflocale is omitted orNone, the current setting forcategory isreturned.

setlocale() is not thread-safe on most systems. Applications typicallystart with a call of

importlocalelocale.setlocale(locale.LC_ALL,'')

This sets the locale for all categories to the user’s default setting (typicallyspecified in theLANG environment variable). If the locale is notchanged thereafter, using multithreading should not cause problems.

locale.localeconv()¶

Returns the database of the local conventions as a dictionary. This dictionaryhas the following strings as keys:

Category	Key	Meaning
LC_NUMERIC	'decimal_point'	Decimal point character.
	'grouping'	Sequence of numbers specifyingwhich relative positions the'thousands_sep' isexpected. If the sequence isterminated withCHAR_MAX, no furthergrouping is performed. If thesequence terminates with a0, the last group size isrepeatedly used.
	'thousands_sep'	Character used between groups.
LC_MONETARY	'int_curr_symbol'	International currency symbol.
	'currency_symbol'	Local currency symbol.
	'p_cs_precedes/n_cs_precedes'	Whether the currency symbolprecedes the value (forpositive resp. negativevalues).
	'p_sep_by_space/n_sep_by_space'	Whether the currency symbol isseparated from the value by aspace (for positive resp.negative values).
	'mon_decimal_point'	Decimal point used formonetary values.
	'frac_digits'	Number of fractional digitsused in local formatting ofmonetary values.
	'int_frac_digits'	Number of fractional digitsused in internationalformatting of monetary values.
	'mon_thousands_sep'	Group separator used formonetary values.
	'mon_grouping'	Equivalent to'grouping',used for monetary values.
	'positive_sign'	Symbol used to annotate apositive monetary value.
	'negative_sign'	Symbol used to annotate anegative monetary value.
	'p_sign_posn/n_sign_posn'	The position of the sign (forpositive resp. negativevalues), see below.

All numeric values can be set toCHAR_MAX to indicate that there is novalue specified in this locale.

The possible values for'p_sign_posn' and'n_sign_posn' are given below.

Value	Explanation
0	Currency and value are surrounded byparentheses.
1	The sign should precede the value andcurrency symbol.
2	The sign should follow the value andcurrency symbol.
3	The sign should immediately precede thevalue.
4	The sign should immediately follow thevalue.
CHAR_MAX	Nothing is specified in this locale.

The function sets temporarily theLC_CTYPE locale to theLC_NUMERIClocale or theLC_MONETARY locale if locales are different and numeric ormonetary strings are non-ASCII. This temporary change affects other threads.

Changed in version 3.7:The function now sets temporarily theLC_CTYPE locale to theLC_NUMERIC locale in some cases.

locale.nl_langinfo(option)¶

Return some locale-specific information as a string. This function is notavailable on all systems, and the set of possible options might also varyacross platforms. The possible argument values are numbers, for whichsymbolic constants are available in the locale module.

Thenl_langinfo() function accepts one of the following keys. Mostdescriptions are taken from the corresponding description in the GNU Clibrary.

locale.CODESET¶

Get a string with the name of the character encoding used in theselected locale.

locale.D_T_FMT¶

Get a string that can be used as a format string fortime.strftime() torepresent date and time in a locale-specific way.

locale.D_FMT¶

Get a string that can be used as a format string fortime.strftime() torepresent a date in a locale-specific way.

locale.T_FMT¶

Get a string that can be used as a format string fortime.strftime() torepresent a time in a locale-specific way.

locale.T_FMT_AMPM¶

Get a format string fortime.strftime() to represent time in the am/pmformat.

DAY_1 ... DAY_7

Get the name of the n-th day of the week.

Note

This follows the US convention ofDAY_1 being Sunday, not theinternational convention (ISO 8601) that Monday is the first day of theweek.

ABDAY_1 ... ABDAY_7

Get the abbreviated name of the n-th day of the week.

MON_1 ... MON_12

Get the name of the n-th month.

ABMON_1 ... ABMON_12

Get the abbreviated name of the n-th month.

locale.RADIXCHAR¶

Get the radix character (decimal dot, decimal comma, etc.).

locale.THOUSEP¶

Get the separator character for thousands (groups of three digits).

locale.YESEXPR¶

Get a regular expression that can be used with the regex function torecognize a positive response to a yes/no question.

Note

The expression is in the syntax suitable for theregex() functionfrom the C library, which might differ from the syntax used inre.

locale.NOEXPR¶

Get a regular expression that can be used with the regex(3) function torecognize a negative response to a yes/no question.

locale.CRNCYSTR¶

Get the currency symbol, preceded by “-” if the symbol should appear beforethe value, “+” if the symbol should appear after the value, or “.” if thesymbol should replace the radix character.

locale.ERA¶

Get a string that represents the era used in the current locale.

Most locales do not define this value. An example of a locale which doesdefine this value is the Japanese one. In Japan, the traditionalrepresentation of dates includes the name of the era corresponding to thethen-emperor’s reign.

Normally it should not be necessary to use this value directly. SpecifyingtheE modifier in their format strings causes thetime.strftime()function to use this information. The format of the returned string is notspecified, and therefore you should not assume knowledge of it on differentsystems.

locale.ERA_D_T_FMT¶

Get a format string fortime.strftime() to represent date and time in alocale-specific era-based way.

locale.ERA_D_FMT¶

Get a format string fortime.strftime() to represent a date in alocale-specific era-based way.

locale.ERA_T_FMT¶

Get a format string fortime.strftime() to represent a time in alocale-specific era-based way.

locale.ALT_DIGITS¶

Get a representation of up to 100 values used to represent the values0 to 99.

locale.getdefaultlocale([envvars])¶

Tries to determine the default locale settings and returns them as a tuple ofthe form(languagecode,encoding).

According to POSIX, a program which has not calledsetlocale(LC_ALL,'')runs using the portable'C' locale. Callingsetlocale(LC_ALL,'') letsit use the default locale as defined by theLANG variable. Since wedo not want to interfere with the current locale setting we thus emulate thebehavior in the way described above.

To maintain compatibility with other platforms, not only theLANGvariable is tested, but a list of variables given as envvars parameter. Thefirst found to be defined will be used.envvars defaults to the searchpath used in GNU gettext; it must always contain the variable name'LANG'. The GNU gettext search path contains'LC_ALL','LC_CTYPE','LANG' and'LANGUAGE', in that order.

Except for the code'C', the language code corresponds toRFC 1766.language code andencoding may beNone if their values cannot bedetermined.

locale.getlocale(category=LC_CTYPE)¶

Returns the current setting for the given locale category as sequence containinglanguage code,encoding.category may be one of theLC_* valuesexceptLC_ALL. It defaults toLC_CTYPE.

Except for the code'C', the language code corresponds toRFC 1766.language code andencoding may beNone if their values cannot bedetermined.

locale.getpreferredencoding(do_setlocale=True)¶

Return the encoding used for text data, according to user preferences. Userpreferences are expressed differently on different systems, and might not beavailable programmatically on some systems, so this function only returns aguess.

On some systems, it is necessary to invokesetlocale() to obtain the userpreferences, so this function is not thread-safe. If invoking setlocale is notnecessary or desired,do_setlocale should be set toFalse.

On Android or in the UTF-8 mode (-Xutf8 option), alwaysreturn'UTF-8', the locale and thedo_setlocale argument are ignored.

Changed in version 3.7:The function now always returnsUTF-8 on Android or if the UTF-8 modeis enabled.

locale.normalize(localename)¶

Returns a normalized locale code for the given locale name. The returned localecode is formatted for use withsetlocale(). If normalization fails, theoriginal name is returned unchanged.

If the given encoding is not known, the function defaults to the defaultencoding for the locale code just likesetlocale().

locale.resetlocale(category=LC_ALL)¶

Sets the locale forcategory to the default setting.

The default setting is determined by callinggetdefaultlocale().category defaults toLC_ALL.

locale.strcoll(string1,string2)¶

Compares two strings according to the currentLC_COLLATE setting. Asany other compare function, returns a negative, or a positive value, or0,depending on whetherstring1 collates before or afterstring2 or is equal toit.

locale.strxfrm(string)¶

Transforms a string to one that can be used in locale-awarecomparisons. For example,strxfrm(s1)<strxfrm(s2) isequivalent tostrcoll(s1,s2)<0. This function can be usedwhen the same string is compared repeatedly, e.g. when collating asequence of strings.

locale.format_string(format,val,grouping=False,monetary=False)¶

Formats a numberval according to the currentLC_NUMERIC setting.The format follows the conventions of the% operator. For floating pointvalues, the decimal point is modified if appropriate. Ifgrouping is true,also takes the grouping into account.

Ifmonetary is true, the conversion uses monetary thousands separator andgrouping strings.

Processes formatting specifiers as informat%val, but takes the currentlocale settings into account.

Changed in version 3.7:Themonetary keyword parameter was added.

locale.format(format,val,grouping=False,monetary=False)¶

Please note that this function works likeformat_string() but willonly work for exactly one%char specifier. For example,'%f' and'%.0f' are both valid specifiers, but'%fKiB' is not.

For whole format strings, useformat_string().

Deprecated since version 3.7:Useformat_string() instead.

locale.currency(val,symbol=True,grouping=False,international=False)¶

Formats a numberval according to the currentLC_MONETARY settings.

The returned string includes the currency symbol ifsymbol is true, which isthe default. Ifgrouping is true (which is not the default), grouping is donewith the value. Ifinternational is true (which is not the default), theinternational currency symbol is used.

Note that this function will not work with the ‘C’ locale, so you have to set alocale viasetlocale() first.

locale.str(float)¶

Formats a floating point number using the same format as the built-in functionstr(float), but takes the decimal point into account.

locale.delocalize(string)¶

Converts a string into a normalized number string, following theLC_NUMERIC settings.

New in version 3.5.

locale.atof(string)¶

Converts a string to a floating point number, following theLC_NUMERICsettings.

locale.atoi(string)¶

Converts a string to an integer, following theLC_NUMERIC conventions.

locale.LC_CTYPE¶

Locale category for the character type functions. Depending on the settings ofthis category, the functions of modulestring dealing with case changetheir behaviour.

locale.LC_COLLATE¶

Locale category for sorting strings. The functionsstrcoll() andstrxfrm() of thelocale module are affected.

locale.LC_TIME¶

Locale category for the formatting of time. The functiontime.strftime()follows these conventions.

locale.LC_MONETARY¶

Locale category for formatting of monetary values. The available options areavailable from thelocaleconv() function.

locale.LC_MESSAGES¶

Locale category for message display. Python currently does not supportapplication specific locale-aware messages. Messages displayed by the operatingsystem, like those returned byos.strerror() might be affected by thiscategory.

locale.LC_NUMERIC¶

Locale category for formatting numbers. The functionsformat(),atoi(),atof() andstr() of thelocale module areaffected by that category. All other numeric formatting operations are notaffected.

locale.LC_ALL¶

Combination of all locale settings. If this flag is used when the locale ischanged, setting the locale for all categories is attempted. If that fails forany category, no category is changed at all. When the locale is retrieved usingthis flag, a string indicating the setting for all categories is returned. Thisstring can be later used to restore the settings.

locale.CHAR_MAX¶

This is a symbolic constant used for different values returned bylocaleconv().

Example:

>>>importlocale>>>loc=locale.getlocale()# get current locale# use German locale; name might vary with platform>>>locale.setlocale(locale.LC_ALL,'de_DE')>>>locale.strcoll('f\xe4n','foo')# compare a string containing an umlaut>>>locale.setlocale(locale.LC_ALL,'')# use user's preferred locale>>>locale.setlocale(locale.LC_ALL,'C')# use default (C) locale>>>locale.setlocale(locale.LC_ALL,loc)# restore saved locale