locale — Сервисы интернационализации

Исходный код: Lib/locale.py

Модуль locale открывает доступ к базе данных и функциональным возможностям локали POSIX. Механизм локали POSIX позволяет программистам решать определенные культурные проблемы в приложении, не требуя от программиста знать все особенности каждой страны, где выполняется программное обеспечение.

Модуль locale реализован поверх модуля _locale, который, в свою очередь, использует реализацию локали ANSI C, если она доступна.

Модуль locale определяет следующие исключения и функции:

exception locale.Error

Исключение, возникшее при передаче локали setlocale(), не распознается.

locale.setlocale(category, locale=None)

Если locale передан и не None, setlocale() изменяет настройку локали для category. Доступные категории перечислены в описании данных ниже. locale может быть строка или итерабелем двух строк (код языка и кодировка). Если итерирумый, то преобразуется в имя локаль, используя движок алиасинга локалей. Пустая строка определяет настройки по умолчанию пользователя. Если изменение локали не удается, возникает исключение Error. Если успешный, новая настройка локали возвращается.

Если параметр locale пропущен или None, то текущий параметр для параметра category имеет значение возвращенный.

setlocale() не является потокобезопасным для большинства систем. Приложения обычно начинаются с вызова:

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

Это задает локаль для всех категорий в соответствии с настройкой пользователя по умолчанию (обычно указанной в переменной среды LANG). Если локаль после этого не изменяется, использование многопоточности не должно вызывать проблем.

locale.localeconv()

Возвращает базу данных локальных конвенций как словарь. Этот словарь содержит следующие строки в качестве ключей:

Категория Ключ Смысл
LC_NUMERIC 'decimal_point' Десятичный знак.
  'grouping' Последовательность чисел, указывающих, какие относительные позиции ожидаются 'thousands_sep'. Если последовательность завершается на CHAR_MAX, дальнейшая группировка не выполняется. Если последовательность заканчивается 0, последний размер группы используется повторно.
  '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 Ничего не указано в этой локали.

Функция устанавливает временно LC_CTYPE локаль в место LC_NUMERIC локали или локаль LC_MONETARY, если локали отличаются, и числовые или денежные строки - не ASCII. Это временное изменение влияет на другие потоки.

Изменено в версии 3.7: Функция теперь устанавливает временно локаль LC_CTYPE в место локали LC_NUMERIC в некоторых случаях.

locale.nl_langinfo(option)

Возвращает некоторую языковую информацию в качестве строка. Эта функция доступна не для всех систем, и набор возможных опций может также различаться для разных платформ. Возможным аргументом значения являются числа, для которых в модуле локали доступны символьные константы.

Функция nl_langinfo() принимает одну из следующих ключей. Большинство описаний взяты из соответствующего описания в библиотеке GNU C.

locale.CODESET

Получение строка с именем символ кодировка используемый в выбранном языковом формате.

locale.D_T_FMT

Получить строка, который может быть используемый как форматная строка для time.strftime(), чтобы представлять дату и время в особенной локали.

locale.D_FMT

Получить строка, который может быть используемый как форматная строка для time.strftime(), чтобы представлять дату в особенном методе локали.

locale.T_FMT

Получить строка, который может быть используемый как форматная строка для time.strftime(), чтобы представлять время в особенном методе локали.

locale.T_FMT_AMPM

Получить форматную строку для time.strftime(), чтобы представлять время am/pm формата.

DAY_1 ... DAY_7

Получить имя n-го дня недели.

Примечание

Это следует американской конвенции DAY_1, являющегося воскресеньем, не, международная конвенция (ISO 8601) в тот понедельник является первым днем недели.

ABDAY_1 ... ABDAY_7

Получить сокращенное название n-го дня недели.

MON_1 ... MON_12

Получить имя n-го месяца.

ABMON_1 ... ABMON_12

Получить сокращенное название n-го месяца.

locale.RADIXCHAR

Получить символ радиуса (десятичная точка, десятичная запятая и т.д.).

locale.THOUSEP

Получить разделительный символ для тысяч (группы из трех цифр).

locale.YESEXPR

Получить регулярное выражение, которое может быть используемый с функцией regex для распознавания положительного ответа на вопрос yes/no.

Примечание

Выражение имеет синтаксис, подходящий для функции regex() из библиотеки C, который может отличаться от синтаксиса используемый в re.

locale.NOEXPR

Получить регулярное выражение, которое может быть используемый с функцией regex (3), чтобы распознать отрицательный ответ на вопрос yes/no.

locale.CRNCYSTR

Получить символ валюты, которому предшествуют «-», если символ должен появиться перед значение, «+», если символ должен появиться после значение, или»». если символ должен заменить корень символ.

locale.ERA

Получение строка, представляющего эру используемый в текущем языковом стандарте.

Большинство языковых стандартов не определяют это значение. Примером локали, которое действительно определяет этот значение, является Японский. В Японии традиционное представление дат включает название эпохи, соответствующей правлению тогдашнего императора.

Как правило, нет необходимости использовать это значение напрямую. Указание модификатора E в их формате строки приводит к использованию этой информации функцией time.strftime(). Формат возвращающий строку не указывается, и поэтому не стоит предполагать знание его на разных системах.

locale.ERA_D_T_FMT

Заставьте формат строка для time.strftime() представлять дату и время определенным для локали основанным на эре способом.

locale.ERA_D_FMT

Заставьте формат строка для time.strftime() представлять дату определенным для локали основанным на эре способом.

locale.ERA_T_FMT

Заставьте формат строка для time.strftime() представлять время определенным для локали основанным на эре способом.

locale.ALT_DIGITS

Получить представление до 100 значений, используемых для представления значений от 0 до 99

locale.getdefaultlocale([envvars])

Попытки определить параметры настройки локали по умолчанию и возвращает их как кортеж формы (language code, encoding).

Согласно POSIX, программа, которая не вызывает setlocale(LC_ALL, ''), использует портабельную локаль 'C'. Запрос setlocale(LC_ALL, '') позволяет ему использовать локаль по умолчанию, как определено переменной LANG. Поскольку мы не хотим вмешиваться в текущую настройку локали, мы таким образом эмулируем поведение таким образом, как описано выше.

Для поддержания совместимости с другими платформами тестируется не только переменная LANG, но и список переменных, заданных в качестве параметра envars. Первый найденный элемент будет определен как используемый. envvars по умолчанию задает путь поиска используемый в GNU gettext; он всегда должен содержать имя переменной 'LANG'. Путь поиска GNU gettext содержит 'LC_ALL', 'LC_CTYPE', 'LANG' и 'LANGUAGE' в этом порядке.

Кроме код 'C', язык код соответствует RFC 1766. language code и encoding могут быть None, если их значения не могут быть определены.

locale.getlocale(category=LC_CTYPE)

Возвращает текущую настройку для данной категории локали как последовательность, содержащую language code, encoding. category может быть одним из LC_* значения, кроме LC_ALL. По умолчанию используется значение LC_CTYPE.

Кроме код 'C', язык код соответствует RFC 1766. language code и encoding могут быть None, если их значения не могут быть определены.

locale.getpreferredencoding(do_setlocale=True)

Возвращает кодировку используемую для текстовых данных в соответствии с предпочтениями пользователя. Пользовательские предпочтения выражаются по-разному в разных системах и могут быть недоступны программно в некоторых системах, поэтому эта функция только возвращает угадывание.

На некоторых системах необходимо призвать setlocale(), чтобы получить пользовательские предпочтения, таким образом, эта функция не поток-безопасна. Если призыв setlocale не необходим или не желаем, do_setlocale должен быть установлен в False.

На Android или в режиме UTF-8 (параметр -X utf8) всегда возвращает 'UTF-8', локаль и аргумент do_setlocale игнорируются.

Изменено в версии 3.7: Функция теперь всегда возвращает UTF-8 на Android или если режим UTF-8 включен.

locale.normalize(localename)

Возвращает код нормализованной локали для данной локали. Возвращенный код локали отформатировано для использования с setlocale(). Если нормализация терпит неудачу, настоящее имя возвращенный неизменный.

Если данный кодировка не известен, дефолты функции к дефолту кодировка для локали код точно так же, как setlocale().

locale.resetlocale(category=LC_ALL)

Устанавливает локаль для category в значение по умолчанию.

Установка по умолчанию определяется вызовом метода getdefaultlocale(). category по умолчанию принимает значение LC_ALL.

locale.strcoll(string1, string2)

Сравнение двух строки в соответствии с текущей настройкой LC_COLLATE. Как и любая другая функция сравнения, возвращает отрицательный, или положительный значение, или 0, в зависимости от того, сопоставляется ли string1 до или после string2 или равен ему.

locale.strxfrm(string)

Преобразовывает строка к тому, который может быть используемый в осведомленных о месте действия сравнениях. Например, strxfrm(s1) < strxfrm(s2) эквивалентен strcoll(s1, s2) < 0. Эта функция может быть используемый при многократном сравнении одного и того же строка, например, при сопоставлении последовательности строки.

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

Форматирует число val в соответствии с текущей настройкой LC_NUMERIC. Формат соответствует правилам оператора %. Для значения с плавающей запятой десятичная точка изменяется при необходимости. Если grouping верен, также принимает группировку во внимание.

Если monetary верен, преобразование использует денежные тысячи сепаратора и группирующий строки.

Обрабатывает спецификаторы форматирования как в format % val, но учитывает текущие параметры локали.

Изменено в версии 3.7: Добавлен параметр monetary ключевой.

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

Обратите внимание, что эта функция работает как format_string(), но будет работать только для одного спецификатора %char. Например, '%f' и '%.0f' являются допустимыми спецификаторами, но '%f KiB' - нет.

Для полного формата строки используйте format_string().

Не рекомендуется, начиная с версии 3.7: Используйте format_string() вместо этого.

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

Форматирует число val в соответствии с текущими настройками LC_MONETARY.

Возвращенная строка включает символ валюты, если symbol верен, который является по умолчанию. Если grouping имеет значение true (которое не является значением по умолчанию), группирование выполняется с помощью значение. Если international верен (который не является дефолтом), международный символ валюты - используемый.

Обратите внимание, что эта функция не будет работать с местом действия „C“, таким образом, вы должны будете установить локаль через setlocale() сначала.

locale.str(float)

Форматирует число с плавающей запятой, используя тот же формат, что и встроенная функция str(float), но учитывает десятичную точку.

locale.delocalize(string)

Преобразует строка в нормированное число строка, следуя настройкам LC_NUMERIC.

Добавлено в версии 3.5.

locale.atof(string)

Преобразование строка в число с плавающей запятой в соответствии с настройками LC_NUMERIC.

locale.atoi(string)

Преобразует строка в целое число, следуя условным обозначениям LC_NUMERIC.

locale.LC_CTYPE

ККатегория локали для функций типа символов. В зависимости от параметров настройки этой категории функций модуля string, имеющие дело со случаем, изменяют свое поведение.

locale.LC_COLLATE

Категория локали для сортировки строки. Затрагиваются функции strcoll() и strxfrm() модуля locale.

locale.LC_TIME

Категория локали для форматирования времени. Функция time.strftime() соответствует этим соглашениям.

locale.LC_MONETARY

Категория локали для форматирования денежных значения. Доступные опции доступны в функции localeconv().

locale.LC_MESSAGES

Категория локали для отображения сообщений. В настоящее время Python не поддерживает сообщения, учитывающие языковые стандарты конкретных приложений. Сообщения, показанные операционной системой, как те возвращенный os.strerror(), могли бы быть затронуты этой категорией.

locale.LC_NUMERIC

Категория локали для форматирования чисел. На функции format(), atoi(), atof() и str() модуля locale влияет эта категория. Все остальные операции числового форматирования не затрагиваются.

locale.LC_ALL

Комбинация всех параметров локали. Если этот флаг - используемый, когда локаль изменено, устанавливание локали для всех категорий предпринято. Если это не удается для какой-либо категории, категория не изменяется вообще. Когда локаль восстановлено, используя этот флаг, строка, указывающий, что настройка для всех категорий - возвращенный. Этот строка может быть позже используемый, чтобы восстановить параметры настройки.

locale.CHAR_MAX

Это символическая константа используемый для разных значения возвращенный по localeconv().

Пример:

>>> import locale
>>> loc = locale.getlocale()  # получить текущую локаль
# использовать Немецкую локаль; название может отличаться в зависимости от платформы
>>> locale.setlocale(locale.LC_ALL, 'de_DE')
>>> locale.strcoll('f\xe4n', 'foo')  # сравнить строку, содержащую умлаут
>>> locale.setlocale(locale.LC_ALL, '')   # использовать предпочтительную пользовательскую локаль
>>> locale.setlocale(locale.LC_ALL, 'C')  # использовать локаль по умолчанию (C)
>>> locale.setlocale(locale.LC_ALL, loc)  # восстановить сохраненную локаль

Предыстория, детали, подсказки, советы и оговорки

Стандарт C определяет локаль как свойство для всей программы, которое может быть относительно дорого изменено. Кроме того, некоторые реализации нарушаются таким образом, что частые изменения локали могут привести к сбросам ядра. Это делает локаль несколько болезненным для правильного использования.

Первоначально при запуске программы локаль является языковым стандартом C, независимо от предпочтительного локали пользователя. Есть одно исключение: категория LC_CTYPE изменена при запуске, чтобы установить текущую кодировку локали в предпочтительную локаль кодировку пользователя. Программа должна явно сказать, что она хочет, чтобы предпочитаемые пользователем языковые настройки для других категорий вызывали setlocale(LC_ALL, '').

Вообще плохо вызывать setlocale() в какой-то библиотечной рутине, так как как побочный эффект это влияет на всю программу. Сохранение и восстановление почти так же плохо: это дорого и влияет на другие потоки, которые запускаются до восстановления настроек.

Если при кодировании модуля для общего использования требуется независимая от локали версия операции, на которую влияет локаль (например, определенные форматы, используемый с time.strftime()), необходимо найти способ сделать это без использования стандартной процедуры библиотеки. Еще лучше убедить себя, что использование языковых настроек нормально. Только в крайнем случае необходимо задокументировать, что модуль несовместим с параметрами локали, отличными отC.

Единственным способом выполнения числовых операций по языковому стандарту является использование специальных функций, определенных этим модулем: atof(), atoi(), format(), str().

Невозможно выполнить преобразования вариантов и классификации символ в соответствии с языковым стандартом. Для текста (Юникод) строки они сделаны согласно символ значение только, в то время как для байта строки, преобразования и классификации сделаны согласно ASCII значение байта, и байты, высокий бит которых установлен (т.е. байты неASCII) никогда не преобразовываются или продуманная часть класса символ, такого как письмо или пробел.

Для устройств записи расширений и программ, встраивающих Python

Внутренние модули не должны вызывать setlocale(), кроме как для определения текущей локали. Но так как возвращает значение может только быть используемый портативно, чтобы восстановить его, который не очень полезен (кроме, возможно, чтобы узнать, является ли локаль C).

Когда Python код использует модуль locale для изменения локали, это также влияет на приложение встраивания. Если приложение встраивания не хочет, чтобы это произошло, оно должно удалить модуль расширения _locale (который выполняет всю работу) из таблицы встроенных модулей в файле config.c и убедиться, что модуль _locale недоступен как общая библиотека.

Доступ к каталогам сообщений

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

Модуль локали предоставляет интерфейс gettext библиотеки C в системах, предоставляющих этот интерфейс. Он состоит из функций gettext(), dgettext(), dcgettext(), textdomain(), bindtextdomain() и bind_textdomain_codeset(). Они аналогичны тем же функциям в модуле gettext, но используют двоичный формат библиотеки C для каталогов сообщений и алгоритмы поиска библиотеки C для поиска каталогов сообщений.

Python приложения, как правило, не должны обнаруживать необходимости в вызове этих функций и вместо этого должны использовать gettext. Известным исключением из этого правила являются приложения, связанные с дополнительными библиотеками C, которые внутренне вызывают gettext() или dcgettext(). Для этих приложений может потребоваться привязка текстового домена, чтобы библиотеки могли правильно найти свои каталоги сообщений.