locale – Интернационализация¶locale – Internationalization services

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

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

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

exception locale.Error¶

Исключение, возникающее при сбое setlocale().

locale.setlocale(category[, locale])¶

Если указан locale, он может быть строкой, кортежем вида (код языка , кодировка) или None. Если это кортеж, он преобразуется в строку с помощью механизма псевдонимов локали. Если locale указан и не равен None, setlocale() изменяет настройку локали для category. Доступные категории перечислены в описании данных ниже. Значение – это имя локали. Пустая строка задаёт настройки пользователя по умолчанию. Если изменение локали завершается с ошибкой, вызывается исключение 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 определены символические константы.

locale.getdefaultlocale([envvars])¶

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

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

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

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

locale.getlocale([category])¶

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

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

locale.getpreferredencoding([do_setlocale])¶

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

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

locale.normalize(localename)¶

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

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

locale.resetlocale([category])¶

Устанавливает локаль для 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[, monetary]])¶

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

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

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

locale.format_string(format, val[, grouping])¶

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

locale.currency(val[, symbol[, grouping[, international]]])¶

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

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

Обратите внимание, что эта функция не работает с локалью 'C', поэтому необходимо сначала установить локаль через setlocale().

locale.str(float)¶

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

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().

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

locale.CODESET¶

Возвращает строку с названием кодировки символов, используемой в выбранной локали.

locale.D_T_FMT¶

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

locale.D_FMT¶

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

locale.T_FMT¶

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

locale.T_FMT_AMPM¶

Возвращаемое значение можно использовать как форматную строку для '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 для распознавания положительного ответа на вопрос «да/нет».

Предупреждение

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

locale.NOEXPR¶

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

locale.CRNCYSTR¶

Возвращает символ валюты с префиксом «-», если символ должен стоять перед значением, «+» – если после значения, или «.», если символ заменяет десятичный разделитель.

locale.ERA¶

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

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

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

locale.ERA_YEAR¶

Возвращаемое значение указывает год в соответствующей эре локали.

locale.ERA_D_T_FMT¶

Это возвращаемое значение можно использовать в качестве строки формата для strftime() для представления дат и времени в локале-зависимом формате на основе эры.

locale.ERA_D_FMT¶

Это возвращаемое значение можно использовать в качестве строки формата для strftime() для представления времени в локале-зависимом формате на основе эры.

locale.ALT_DIGITS¶

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

Пример:

>>> 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) # восстановить сохранённую локаль