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)

Возвращает информацию о текущем языке как строку. Эта функция доступна не на всех системах, и набор возможных опций может также различаться в зависимости от платформы. Возможные значения аргументов — числа, для которых в модуле 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 содержит '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.

На 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 равно true, также учитывается группировка.

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

Обрабатывает спецификаторы форматирования, как в 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 равно 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

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

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

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

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

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

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

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

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

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

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

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

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