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.6.5: Функция теперь временно устанавливает локаль 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

Возвращает представление значений от 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 — true, учитывается также группировка.

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

Обратите внимание, что эта функция будет работать только для одного спецификатора %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

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

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

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

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

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

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

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

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

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

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

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