locale —- 国际化服务

源代码：Lib/locale.py

The locale 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.

The locale module is implemented on top of the _locale module,which in turn uses an ANSI C locale implementation if available.

The locale module defines the following exception and functions:

  • exception locale.Error
  • Exception raised when the locale passed to setlocale() is notrecognized.
  • locale.setlocale(category, locale=None)
  • If locale is given and not None, setlocale() modifies the localesetting for the category. 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.

If locale is omitted or None, the current setting for category isreturned.

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

  1. import locale
  2. locale.setlocale(locale.LC_ALL, '')

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

  • locale.localeconv()
  • 以字典的形式返回本地约定的数据库。此字典具有以下字符串作为键：

类别

（Windows 注册表的）键

含义

LC_NUMERIC

'decimal_point'

小数点字符。

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

组之间使用的字符。

LC_MONETARY

'int_curr_symbol'

国际货币符号。

'currency_symbol'

当地货币符号。

'p_cs_precedes/n_cs_precedes'

货币符号是否在值之前（对于正值或负值）。

'p_sep_by_space/n_sep_by_space'

货币符号是否通过空格与值分隔（对于正值或负值）。

'mon_decimal_point'

用于货币金额的小数点。

'frac_digits'

货币值的本地格式中使用的小数位数。

'int_frac_digits'

货币价值的国际格式中使用的小数位数。

'mon_thousands_sep'

用于货币值的组分隔符。

'mon_grouping'

相当于 'grouping' ，用于货币价值。

'positive_sign'

用于标注正货币价值的符号。

'negative_sign'

用于注释负货币价值的符号。

'p_sign_posn/n_sign_posn'

符号的位置（对于正值或负值），见下文。

可以将所有数值设置为 CHAR_MAX ，以指示此语言环境中未指定任何值。

下面给出了 'p_sign_posn' 和 'n_sign_posn' 的可能值。

值

解释

0

被括号括起来的货币和金额。

1

该标志应位于值和货币符号之前。

2

该标志应位于值和货币符号之后。

3

标志应该紧跟在值之前。

4

标志应该紧跟值项。

CHAR_MAX

此语言环境中未指定任何内容。

The function sets temporarily the LC_CTYPE locale to the LC_NUMERIClocale or the LC_MONETARY locale if locales are different and numeric ormonetary strings are non-ASCII. This temporary change affects other threads.

在 3.7 版更改: The function now sets temporarily the LC_CTYPE locale to theLC_NUMERIC locale in some cases.

  • locale.nllanginfo(_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.

The nl_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 for time.strftime() torepresent date and time in a locale-specific way.

  • locale.D_FMT

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

  • locale.T_FMT

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

  • locale.T_FMT_AMPM

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

  • DAY_1 … DAY_7

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

注解

This follows the US convention of DAY_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.

注解

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

  • 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. Specifyingthe E modifier in their format strings causes the time.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 for time.strftime() to represent date and time in alocale-specific era-based way.

  • locale.ERA_D_FMT

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

  • locale.ERA_T_FMT

  • Get a format string for time.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 (language code, encoding).

According to POSIX, a program which has not called setlocale(LC_ALL, '')runs using the portable 'C' locale. Calling setlocale(LC_ALL, '') letsit use the default locale as defined by the LANG 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 the LANGvariable 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 to RFC 1766.language code and encoding may be None 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 the LC_* valuesexcept LC_ALL. It defaults to LC_CTYPE.

Except for the code 'C', the language code corresponds to RFC 1766.language code and encoding may be None 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 invoke setlocale() to obtain the userpreferences, so this function is not thread-safe. If invoking setlocale is notnecessary or desired, do_setlocale should be set to False.

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

在 3.7 版更改: The function now always returns UTF-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 with setlocale(). 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 like setlocale().

  • locale.resetlocale(category=LC_ALL)
  • Sets the locale for category to the default setting.

The default setting is determined by calling getdefaultlocale().category defaults to LC_ALL.

  • locale.strcoll(string1, string2)
  • Compares two strings according to the current LC_COLLATE setting. Asany other compare function, returns a negative, or a positive value, or 0,depending on whether string1 collates before or after string2 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 to strcoll(s1, s2) < 0. This function can be usedwhen the same string is compared repeatedly, e.g. when collating asequence of strings.
  • locale.formatstring(_format, val, grouping=False, monetary=False)
  • Formats a number val according to the current LC_NUMERIC setting.The format follows the conventions of the % operator. For floating pointvalues, the decimal point is modified if appropriate. If grouping is true,also takes the grouping into account.

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

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

在 3.7 版更改: The monetary keyword parameter was added.

  • locale.format(format, val, grouping=False, monetary=False)
  • Please note that this function works like format_string() but willonly work for exactly one %char specifier. For example, '%f' and'%.0f' are both valid specifiers, but '%f KiB' is not.

For whole format strings, use format_string().

3.7 版后已移除: Use format_string() instead.

  • locale.currency(val, symbol=True, grouping=False, international=False)
  • Formats a number val according to the current LC_MONETARY settings.

The returned string includes the currency symbol if symbol is true, which isthe default. If grouping is true (which is not the default), grouping is donewith the value. If international 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 via setlocale() 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.

3.5 新版功能.

  • locale.atof(string)
  • Converts a string to a floating point number, following the LC_NUMERICsettings.
  • locale.atoi(string)
  • Converts a string to an integer, following the LC_NUMERIC conventions.
  • locale.LC_CTYPE
  • Locale category for the character type functions. Depending on the settings ofthis category, the functions of module string dealing with case changetheir behaviour.
  • locale.LC_COLLATE
  • Locale category for sorting strings. The functions strcoll() andstrxfrm() of the locale module are affected.
  • locale.LC_TIME
  • Locale category for the formatting of time. The function time.strftime()follows these conventions.
  • locale.LC_MONETARY
  • Locale category for formatting of monetary values. The available options areavailable from the localeconv() 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 by os.strerror() might be affected by thiscategory.
  • locale.LC_NUMERIC
  • Locale category for formatting numbers. The functions format(),atoi(), atof() and str() of the locale 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().

示例:

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

Background, details, hints, tips and caveats

The C standard defines the locale as a program-wide property that may berelatively expensive to change. On top of that, some implementation are brokenin such a way that frequent locale changes may cause core dumps. This makes thelocale somewhat painful to use correctly.

Initially, when a program is started, the locale is the C locale, no matterwhat the user's preferred locale is. There is one exception: theLC_CTYPE category is changed at startup to set the current localeencoding to the user's preferred locale encoding. The program must explicitlysay that it wants the user's preferred locale settings for other categories bycalling setlocale(LC_ALL, '').

It is generally a bad idea to call setlocale() in some library routine,since as a side effect it affects the entire program. Saving and restoring itis almost as bad: it is expensive and affects other threads that happen to runbefore the settings have been restored.

If, when coding a module for general use, you need a locale independent versionof an operation that is affected by the locale (such ascertain formats used with time.strftime()), you will have to find a way todo it without using the standard library routine. Even better is convincingyourself that using locale settings is okay. Only as a last resort should youdocument that your module is not compatible with non-C locale settings.

The only way to perform numeric operations according to the locale is to use thespecial functions defined by this module: atof(), atoi(),format(), str().

There is no way to perform case conversions and character classificationsaccording to the locale. For (Unicode) text strings these are done accordingto the character value only, while for byte strings, the conversions andclassifications are done according to the ASCII value of the byte, and byteswhose high bit is set (i.e., non-ASCII bytes) are never converted or consideredpart of a character class such as letter or whitespace.

For extension writers and programs that embed Python

Extension modules should never call setlocale(), except to find out whatthe current locale is. But since the return value can only be used portably torestore it, that is not very useful (except perhaps to find out whether or notthe locale is C).

When Python code uses the locale module to change the locale, this alsoaffects the embedding application. If the embedding application doesn't wantthis to happen, it should remove the _locale extension module (which doesall the work) from the table of built-in modules in the config.c file,and make sure that the _locale module is not accessible as a sharedlibrary.

Access to message catalogs

  • locale.gettext(msg)
  • locale.dgettext(domain, msg)
  • locale.dcgettext(domain, msg, category)
  • locale.textdomain(domain)
  • locale.bindtextdomain(domain, dir)

The locale module exposes the C library's gettext interface on systems thatprovide this interface. It consists of the functions gettext(),dgettext(), dcgettext(), textdomain(), bindtextdomain(),and bind_textdomain_codeset(). These are similar to the same functions inthe gettext module, but use the C library's binary format for messagecatalogs, and the C library's search algorithms for locating message catalogs.

Python applications should normally find no need to invoke these functions, andshould use gettext instead. A known exception to this rule areapplications that link with additional C libraries which internally invokegettext() or dcgettext(). For these applications, it may benecessary to bind the text domain, so that the libraries can properly locatetheir message catalogs.