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	В этой локали ничего не указано.

locale.nl_langinfo(option)

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

Функция 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

Возвращает имя дня недели.

Примечание

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

ABDAY_1 ... ABDAY_7

Возвращает сокращенное имя дня недели.

MON_1 ... MON_12

Возвращает имя месяца.

ABMON_1 ... ABMON_12

Возвращает сокращенное имя месяца.

locale.RADIXCHAR

Возвращает символ разделителя целой и дробной части (десятичная точка, десятичная запятая и т.д.).

locale.THOUSEP

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

locale.YESEXPR

Возвращает регулярное выражение, которое можно использовать с функцией regex для распознавания положительного ответа на вопрос «да/нет».

Примечание

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

locale.NOEXPR

Возвращает регулярное выражение, которое можно использовать с функцией regex(3) для распознавания отрицательного ответа на вопрос «да/нет».

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, но и список переменных, переданных в параметре envvars. Первая найденная переменная будет использована. envvars по умолчанию использует путь поиска, используемый в GNU gettext; он всегда должен содержать имя переменной 'LANG'. Путь поиска GNU gettext содержит 'LC_ALL', 'LC_CTYPE', 'LANG' и 'LANGUAGE', в указанном порядке.

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

locale.getlocale(category=LC_CTYPE)

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

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

locale.getpreferredencoding(do_setlocale=True)

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

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

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(format, val, grouping=False, monetary=False)

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

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

Обратите внимание, что эта функция будет работать только для ровно одного спецификатора %char. Для целых строк формата используйте format_string().

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

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

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

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

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

Обратите внимание, что эта функция не будет работать с локалью «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()  # 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

1. Общие сведения, подробности, подсказки, рекомендации и замечания

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

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

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

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

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

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

2. Для разработчиков расширений и программ, которые включают Python

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

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

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

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

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