locale — Услуги интернационализации

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

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

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

exception locale.Error

Исключение, выбрасываемое, когда локализация, переданная в setlocale(), не распознаётся.

locale.setlocale(category[, locale])

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

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

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

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

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

Изменено в версии 2.0: Добавлена поддержка итерируемых значений параметра locale.

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

Возвращает имя 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 в строках форматирования заставляет функцию 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 содержит 'LANGUAGE', 'LC_ALL', 'LC_CTYPE', и 'LANG', в указанном порядке.

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

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

locale.getlocale([category])

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

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

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

locale.getpreferredencoding([do_setlocale])

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

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

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

locale.normalize(localename)

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

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

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

locale.resetlocale([category])

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

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

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

locale.strcoll(string1, string2)

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

locale.strxfrm(string)

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

locale.format(format, val[, grouping[, monetary]])

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

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

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

Изменено в версии 2.5: Добавлен параметр monetary.

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

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

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

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

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

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

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

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

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

Пример:

>>> 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 локаль, независимо от того, какая локаль предпочтительна у пользователя. Программа должна явно указать, что она хочет использовать настройки локали пользователя, вызвав setlocale(LC_ALL, '').

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

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

Функции изменения регистра в модуле string зависят от настроек локали. Когда вызов функции setlocale() изменяет настройки LC_CTYPE, переменные string.lowercase, string.uppercase и string.letters пересчитываются. Обратите внимание, что код, использующий эти переменные через «from … import …», например, from string import letters, не затрагивается последующими вызовами setlocale().

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

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

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

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

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

locale.gettext(msg)

locale.dgettext(domain, msg)

locale.dcgettext(domain, msg, category)

locale.textdomain(domain)

locale.bindtextdomain(domain, dir)

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

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