> **Источник:** https://python-all.ru/3.9/library/locale.html > > «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor. --- # [`locale`](https://python-all.ru/3.9/library/locale.html#module-locale) – Службы интернационализации **Исходный код:** [Lib/locale.py](https://python-all.ru/src/3.9/Lib/locale.py) --- Модуль [`locale`](https://python-all.ru/3.9/library/locale.html#module-locale) предоставляет доступ к базе данных локалей POSIX и её функциональности. Механизм локалей POSIX позволяет разработчикам решать задачи, связанные с культурными особенностями приложения, не требуя от них знания всех тонкостей каждой страны, где выполняется программа. Модуль [`locale`](https://python-all.ru/3.9/library/locale.html#module-locale) реализован поверх модуля `_locale`, который, в свою очередь, использует реализацию локали ANSI C, если она доступна. Модуль [`locale`](https://python-all.ru/3.9/library/locale.html#module-locale) определяет следующее исключение и функции: #### `exception locale.Error` Исключение возникает, когда локаль, переданная в [`setlocale()`](https://python-all.ru/3.9/library/locale.html#locale.setlocale), не распознана. #### `locale.setlocale(category, locale=None)` Если передан *locale* и он не равен `None`, то [`setlocale()`](https://python-all.ru/3.9/library/locale.html#locale.setlocale) изменяет настройки локали для категории *category*. Доступные категории перечислены ниже в описании данных. *locale* может быть строкой или итерируемым объектом из двух строк (код языка и кодировка). Если это итерируемый объект, он преобразуется в имя локали с помощью механизма псевдонимов локалей. Пустая строка задаёт настройки пользователя по умолчанию. Если изменение локали не удаётся, вызывается исключение [`Error`](https://python-all.ru/3.9/library/locale.html#locale.Error). В случае успеха возвращается новая настройка локали. Если *locale* опущен или равен `None`, возвращается текущая настройка для категории *category*. [`setlocale()`](https://python-all.ru/3.9/library/locale.html#locale.setlocale) не является потокобезопасной на большинстве систем. Приложения обычно начинают с вызова ```python import locale locale.setlocale(locale.LC_ALL, '') ``` Это устанавливает локаль для всех категорий в пользовательскую настройку по умолчанию (обычно заданную в переменной окружения `LANG`). Если впоследствии локаль не изменять, использование многопоточности не должно вызывать проблем. #### `locale.localeconv()` Возвращает словарь с данными о локальных соглашениях. Ключами этого словаря являются следующие строки: | Категория | Клавиша | Значение | | --- | --- | --- | | [`LC_NUMERIC`](https://python-all.ru/3.9/library/locale.html#locale.LC_NUMERIC) | `'decimal_point'` | Символ десятичной точки. | | | `'grouping'` | Последовательность чисел, указывающая, в каких относительных позициях ожидается `'thousands_sep'`. Если последовательность завершается значением [`CHAR_MAX`](https://python-all.ru/3.9/library/locale.html#locale.CHAR_MAX), дальнейшая группировка не выполняется. Если последовательность завершается значением `0`, размер последней группы используется повторно. | | | `'thousands_sep'` | Символ, используемый между группами. | | [`LC_MONETARY`](https://python-all.ru/3.9/library/locale.html#locale.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`](https://python-all.ru/3.9/library/locale.html#locale.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()`](https://python-all.ru/3.9/library/locale.html#locale.nl_langinfo) принимает один из следующих ключей. Большинство описаний взяты из соответствующих описаний в библиотеке GNU C. #### `locale.CODESET` Возвращает строку с именем кодировки символов, используемой в выбранной локали. #### `locale.D_T_FMT` Возвращает строку, которую можно использовать как строку форматирования для [`time.strftime()`](https://python-all.ru/3.9/library/time.html#time.strftime) для представления даты и времени с учётом локали. #### `locale.D_FMT` Возвращает строку, которую можно использовать как строку форматирования для [`time.strftime()`](https://python-all.ru/3.9/library/time.html#time.strftime) для представления даты с учётом локали. #### `locale.T_FMT` Возвращает строку, которую можно использовать как строку форматирования для [`time.strftime()`](https://python-all.ru/3.9/library/time.html#time.strftime) для представления времени с учётом локали. #### `locale.T_FMT_AMPM` Возвращает строку форматирования для [`time.strftime()`](https://python-all.ru/3.9/library/time.html#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`](https://python-all.ru/3.9/library/re.html#module-re). #### `locale.NOEXPR` Возвращает регулярное выражение, которое можно использовать с функцией regex(3) для распознавания отрицательного ответа на вопрос «да/нет». #### `locale.CRNCYSTR` Получить символ валюты, перед которым стоит «-», если символ должен отображаться перед значением, «+», если символ должен отображаться после значения, или «.», если символ должен заменить десятичный разделитель. #### `locale.ERA` Возвращает строку, представляющую эру, используемую в текущей локали. Большинство локалей не определяют это значение. Примером локали, которая определяет это значение, является японская. В Японии традиционное представление дат включает название эры, соответствующей правлению действующего императора. Обычно нет необходимости использовать это значение напрямую. Указание модификатора `E` в строках формата заставляет функцию [`time.strftime()`](https://python-all.ru/3.9/library/time.html#time.strftime) использовать эту информацию. Формат возвращаемой строки не определён, поэтому не следует полагаться на его вид в разных системах. #### `locale.ERA_D_T_FMT` Получить строку формата для [`time.strftime()`](https://python-all.ru/3.9/library/time.html#time.strftime) для представления даты и времени в локализованном формате, основанном на эре. #### `locale.ERA_D_FMT` Получить строку формата для [`time.strftime()`](https://python-all.ru/3.9/library/time.html#time.strftime) для представления даты в локализованном формате, основанном на эре. #### `locale.ERA_T_FMT` Получить строку формата для [`time.strftime()`](https://python-all.ru/3.9/library/time.html#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**](https://python-all.ru/3.9/library/locale.html). *Код языка* и *кодировка* могут быть `None`, если их значения не удаётся определить. #### `locale.getlocale(category=LC_CTYPE)` Возвращает текущую настройку для указанной категории локали в виде последовательности, содержащей *код языка*, *кодировку*. *Категория* может быть одним из значений `LC_*`, кроме [`LC_ALL`](https://python-all.ru/3.9/library/locale.html#locale.LC_ALL). По умолчанию [`LC_CTYPE`](https://python-all.ru/3.9/library/locale.html#locale.LC_CTYPE). За исключением кода `'C'`, код языка соответствует [**RFC 1766**](https://python-all.ru/3.9/library/locale.html). *Код языка* и *кодировка* могут быть `None`, если их значения не удаётся определить. #### `locale.getpreferredencoding(do_setlocale=True)` Возвращает кодировку, используемую для текстовых данных, в соответствии с пользовательскими настройками. Пользовательские настройки выражаются по-разному в разных системах и могут быть недоступны программно в некоторых системах, поэтому эта функция возвращает только предположение. В некоторых системах необходимо вызвать [`setlocale()`](https://python-all.ru/3.9/library/locale.html#locale.setlocale) для получения пользовательских настроек, поэтому эта функция не является потокобезопасной. Если вызов setlocale не требуется или нежелателен, *do\_setlocale* следует установить в `False`. На Android или в режиме UTF-8 (опция [`-X`](https://python-all.ru/3.9/using/cmdline.html#id5) `utf8`) всегда возвращает `'UTF-8'`, локаль и аргумент *do\_setlocale* игнорируются. Изменено в версии 3.7: Теперь функция всегда возвращает `UTF-8` на Android или если включен режим UTF-8. #### `locale.normalize(localename)` Возвращает нормализованный код локали для заданного имени локали. Возвращённый код локали отформатирован для использования с [`setlocale()`](https://python-all.ru/3.9/library/locale.html#locale.setlocale). Если нормализация не удалась, исходное имя возвращается без изменений. Если заданная кодировка неизвестна, функция использует кодировку по умолчанию для кода локали, как и [`setlocale()`](https://python-all.ru/3.9/library/locale.html#locale.setlocale). #### `locale.resetlocale(category=LC_ALL)` Устанавливает локаль для *category* в значение по умолчанию. Значение по умолчанию определяется вызовом [`getdefaultlocale()`](https://python-all.ru/3.9/library/locale.html#locale.getdefaultlocale). *category* по умолчанию равен [`LC_ALL`](https://python-all.ru/3.9/library/locale.html#locale.LC_ALL). #### `locale.strcoll(string1, string2)` Сравнивает две строки в соответствии с текущей настройкой [`LC_COLLATE`](https://python-all.ru/3.9/library/locale.html#locale.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`](https://python-all.ru/3.9/library/locale.html#locale.LC_NUMERIC). Формат следует соглашениям оператора `%`. Для чисел с плавающей запятой десятичная точка изменяется, если это уместно. Если *grouping* равно true, также учитывается группировка. Если *monetary* истинно, преобразование использует денежные разделители тысяч и строки группировки. Обрабатывает спецификаторы форматирования, как в `format % val`, но с учётом текущих настроек локали. Изменено в версии 3.7: Добавлен ключевой параметр *monetary*. #### `locale.format(format, val, grouping=False, monetary=False)` Обратите внимание, что эта функция работает как [`format_string()`](https://python-all.ru/3.9/library/locale.html#locale.format_string), но работает только для одного спецификатора `%char`. Например, `'%f'` и `'%.0f'` – оба допустимые спецификаторы, а `'%f KiB'` – нет. Для целых строк формата используйте [`format_string()`](https://python-all.ru/3.9/library/locale.html#locale.format_string). Устарело с версии 3.7: Вместо этого используйте [`format_string()`](https://python-all.ru/3.9/library/locale.html#locale.format_string). #### `locale.currency(val, symbol=True, grouping=False, international=False)` Форматирует число *val* в соответствии с текущими настройками [`LC_MONETARY`](https://python-all.ru/3.9/library/locale.html#locale.LC_MONETARY). Возвращаемая строка включает символ валюты, если *symbol* равно true (значение по умолчанию). Если *grouping* равно true (не по умолчанию), выполняется группировка значения. Если *international* равно true (не по умолчанию), используется международный символ валюты. Обратите внимание, что эта функция не работает с локалью 'C', поэтому сначала необходимо установить локаль через [`setlocale()`](https://python-all.ru/3.9/library/locale.html#locale.setlocale). #### `locale.str(float)` Форматирует число с плавающей запятой, используя тот же формат, что и встроенная функция `str(float)`, но учитывает десятичную точку. #### `locale.delocalize(string)` Преобразует строку в нормализованное строковое представление числа в соответствии с настройками [`LC_NUMERIC`](https://python-all.ru/3.9/library/locale.html#locale.LC_NUMERIC). Новое в версии 3.5. #### `locale.atof(string, func=float)` Преобразует строку в число, следуя настройкам [`LC_NUMERIC`](https://python-all.ru/3.9/library/locale.html#locale.LC_NUMERIC), вызывая *func* для результата вызова [`delocalize()`](https://python-all.ru/3.9/library/locale.html#locale.delocalize) для *string*. #### `locale.atoi(string)` Преобразует строку в целое число, следуя соглашениям [`LC_NUMERIC`](https://python-all.ru/3.9/library/locale.html#locale.LC_NUMERIC). #### `locale.LC_CTYPE` Категория локали для функций обработки символов. В зависимости от настроек этой категории функции модуля [`string`](https://python-all.ru/3.9/library/string.html#module-string), работающие с регистром, изменяют своё поведение. #### `locale.LC_COLLATE` Категория локали для сортировки строк. Функции [`strcoll()`](https://python-all.ru/3.9/library/locale.html#locale.strcoll) и [`strxfrm()`](https://python-all.ru/3.9/library/locale.html#locale.strxfrm) модуля [`locale`](https://python-all.ru/3.9/library/locale.html#module-locale) затрагиваются. #### `locale.LC_TIME` Категория локали для форматирования времени. Функция [`time.strftime()`](https://python-all.ru/3.9/library/time.html#time.strftime) следует этим соглашениям. #### `locale.LC_MONETARY` Категория локали для форматирования денежных значений. Доступные параметры можно получить из функции [`localeconv()`](https://python-all.ru/3.9/library/locale.html#locale.localeconv). #### `locale.LC_MESSAGES` Категория локали для отображения сообщений. В настоящее время Python не поддерживает сообщения, учитывающие локаль, для конкретных приложений. Сообщения, выводимые операционной системой, например возвращаемые [`os.strerror()`](https://python-all.ru/3.9/library/os.html#os.strerror), могут затрагиваться этой категорией. #### `locale.LC_NUMERIC` Категория локали для форматирования чисел. Функции [`format()`](https://python-all.ru/3.9/library/locale.html#locale.format), [`atoi()`](https://python-all.ru/3.9/library/locale.html#locale.atoi), [`atof()`](https://python-all.ru/3.9/library/locale.html#locale.atof) и [`str()`](https://python-all.ru/3.9/library/locale.html#locale.str) модуля [`locale`](https://python-all.ru/3.9/library/locale.html#module-locale) затрагиваются этой категорией. Все остальные операции форматирования чисел не затрагиваются. #### `locale.LC_ALL` Комбинация всех настроек локали. Если этот флаг используется при изменении локали, предпринимается попытка установить локаль для всех категорий. Если это не удаётся для какой-либо категории, ни одна категория не изменяется. При получении локали с помощью этого флага возвращается строка, указывающая настройки для всех категорий. Эту строку можно впоследствии использовать для восстановления настроек. #### `locale.CHAR_MAX` Это символическая константа, используемая для различных значений, возвращаемых [`localeconv()`](https://python-all.ru/3.9/library/locale.html#locale.localeconv). Пример: ```python >>> import locale >>> loc = locale.getlocale() # получить текущую локаль # use German locale; name might vary with platform >>> 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) # восстановить сохранённую локаль ``` ## Предыстория, подробности, подсказки, советы и предостережения Стандарт C определяет локаль как свойство всей программы, которое может быть относительно дорогим для изменения. Вдобавок некоторые реализации настолько некорректны, что частые смены локали могут приводить к дампам памяти. Это делает локаль несколько болезненной для правильного использования. Изначально при запуске программы локалью является `C`, независимо от того, какая локаль предпочтительна для пользователя. Есть одно исключение: категория [`LC_CTYPE`](https://python-all.ru/3.9/library/locale.html#locale.LC_CTYPE) изменяется при запуске, чтобы установить текущую кодировку локали на предпочтительную кодировку локали пользователя. Программа должна явно указать, что она хочет использовать предпочтительные настройки локали пользователя для других категорий, вызвав `setlocale(LC_ALL, '')`. Обычно плохая идея вызывать [`setlocale()`](https://python-all.ru/3.9/library/locale.html#locale.setlocale) в какой-либо библиотечной функции, так как побочный эффект затрагивает всю программу. Сохранение и восстановление почти так же плохо: это дорого и затрагивает другие потоки, которые могут выполняться до восстановления настроек. Если при написании модуля общего назначения требуется независимая от локали версия операции, на которую влияет локаль (например, определённые форматы, используемые с [`time.strftime()`](https://python-all.ru/3.9/library/time.html#time.strftime)), необходимо найти способ сделать это без использования процедур из стандартной библиотеки. Ещё лучше убедиться, что использование настроек локали допустимо. И только в крайнем случае стоит документировать, что модуль несовместим с настройками локали, отличными от `C`. Единственный способ выполнять числовые операции в соответствии с локалью – использовать специальные функции, определённые в этом модуле: [`atof()`](https://python-all.ru/3.9/library/locale.html#locale.atof), [`atoi()`](https://python-all.ru/3.9/library/locale.html#locale.atoi), [`format()`](https://python-all.ru/3.9/library/locale.html#locale.format), [`str()`](https://python-all.ru/3.9/library/locale.html#locale.str). Не существует способа выполнять преобразование регистра и классификацию символов в соответствии с локалью. Для текстовых строк (Unicode) они выполняются только по значению символа, тогда как для байтовых строк преобразования и классификации выполняются по значению ASCII байта, а байты, у которых установлен старший бит (т.е. не-ASCII байты), никогда не преобразуются и не считаются частью какого-либо класса символов, такого как буква или пробел. ## Для разработчиков расширений и программ, встраивающих Python Модули расширений никогда не должны вызывать [`setlocale()`](https://python-all.ru/3.9/library/locale.html#locale.setlocale), за исключением случаев, когда нужно узнать текущую локаль. Но поскольку возвращаемое значение можно переносимо использовать только для её восстановления, это не очень полезно (кроме, возможно, выяснения, является ли локаль `C` или нет). Когда код Python использует модуль [`locale`](https://python-all.ru/3.9/library/locale.html#module-locale) для смены локали, это также влияет на встраиваемое приложение. Если встраиваемое приложение не хочет, чтобы это происходило, оно должно удалить модуль расширения `_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`](https://python-all.ru/3.9/library/gettext.html#module-gettext), но используют бинарный формат библиотеки C для каталогов сообщений и алгоритмы поиска библиотеки C для нахождения каталогов сообщений. Приложениям Python обычно не требуется вызывать эти функции, и следует использовать [`gettext`](https://python-all.ru/3.9/library/gettext.html#module-gettext) вместо этого. Известным исключением из этого правила являются приложения, которые связываются с дополнительными библиотеками C, внутренне вызывающими `gettext()` или `dcgettext()`. Для таких приложений может потребоваться привязка текстового домена, чтобы библиотеки могли правильно найти свои каталоги сообщений.