locale — Службы интернационализации

Kod źródłowy: Lib/locale.py

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

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

Модуль locale визначає такі винятки та функції:

exception locale.Error

Виняток виникає, коли локаль, передана setlocale(), не розпізнається.

locale.setlocale(category, locale=None)

If locale is given and not None, setlocale() modifies the locale setting for the category. The available categories are listed in the data description below. locale may be a string, or a pair, language code and encoding. An empty string specifies the user’s default settings. If the modification of the locale fails, the exception Error is raised. If successful, the new locale setting is returned.

If locale is a pair, it is converted to a locale name using the locale aliasing engine. The language code has the same format as a locale name, but without encoding and @-modifier. The language code and encoding can be None.

Якщо locale пропущено або None, повертається поточне налаштування для category.

setlocale() не є потокобезпечним у більшості систем. Програми зазвичай починаються з виклику

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

Це встановлює локаль для всіх категорій на налаштування користувача за замовчуванням (зазвичай вказується у змінній середовища LANG). Якщо після цього локаль не буде змінено, використання багатопоточності не повинно викликати проблем.

locale.localeconv()

Повертає базу даних локальних угод як словник. Цей словник має такі рядки як ключі:

Категорія

Key

Znaczenie

LC_NUMERIC

'decimal_point'

Символ десяткової точки.

'групування''

Послідовність чисел, що вказує, які відносні позиції очікується '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'

Еквівалент 'групування'', що використовується для грошових значень.

'positive_sign'

Символ, який використовується для позначення додатної грошової вартості.

'негативний_знак'

Символ, який використовується для позначення від’ємної грошової вартості.

'p_sign_posn/n_sign_posn''

Розташування знака (для додатних чи від’ємних значень) див. нижче.

Для всіх числових значень можна встановити значення CHAR_MAX, щоб вказати, що в цій локалі не вказано значення.

Нижче наведено можливі значення для 'p_sign_posn' і 'n_sign_posn'.

Wartość

Wytłumaczenie

0

Валюта та значення взяті в дужки.

1

Знак має передувати символу вартості та валюти.

2

Знак повинен слідувати за символом вартості та валюти.

3

Знак повинен стояти безпосередньо перед значенням.

4

Знак повинен слідувати безпосередньо за значенням.

CHAR_MAX

У цій локалі нічого не вказано.

Функция временно устанавливает для локали LC_CTYPE локаль LC_NUMERIC или локаль LC_MONETARY, если локали различаются, а числовые или денежные строки не являются ASCII. Это временное изменение влияет на другие потоки.

Zmienione w wersji 3.7: В некоторых случаях функция теперь временно устанавливает локаль LC_CTYPE на локаль LC_NUMERIC.

locale.nl_langinfo(option)

Повертає деяку інформацію про локаль у вигляді рядка. Ця функція доступна не в усіх системах, і набір можливих параметрів також може відрізнятися на різних платформах. Можливими значеннями аргументів є числа, для яких у модулі локалі доступні символьні константи.

Функція 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.

locale.DAY_1
locale.DAY_2
locale.DAY_3
locale.DAY_4
locale.DAY_5
locale.DAY_6
locale.DAY_7

Отримайте назву n-го дня тижня.

Informacja

Це відповідає конвенції США про те, що DAY_1 є неділею, а не міжнародній конвенції (ISO 8601), що понеділок є першим днем тижня.

locale.ABDAY_1
locale.ABDAY_2
locale.ABDAY_3
locale.ABDAY_4
locale.ABDAY_5
locale.ABDAY_6
locale.ABDAY_7

Отримайте скорочену назву n-го дня тижня.

locale.MON_1
locale.MON_2
locale.MON_3
locale.MON_4
locale.MON_5
locale.MON_6
locale.MON_7
locale.MON_8
locale.MON_9
locale.MON_10
locale.MON_11
locale.MON_12

Отримайте назву n-го місяця.

locale.ABMON_1
locale.ABMON_2
locale.ABMON_3
locale.ABMON_4
locale.ABMON_5
locale.ABMON_6
locale.ABMON_7
locale.ABMON_8
locale.ABMON_9
locale.ABMON_10
locale.ABMON_11
locale.ABMON_12

Отримайте скорочену назву n-го місяця.

locale.RADIXCHAR

Отримайте символ основи (десяткову крапку, десяткову кому тощо).

locale.THOUSEP

Отримайте роздільник тисяч (групи з трьох цифр).

locale.YESEXPR

Отримайте регулярний вираз, який можна використовувати з функцією регулярного виразу, щоб розпізнати позитивну відповідь на запитання „так/ні”.

locale.NOEXPR

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

Informacja

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

locale.CRNCYSTR

Отримайте символ грошової одиниці, якому передує „-”, якщо символ має стояти перед значенням, „+”, якщо символ має стояти після значення, або „.” якщо символ повинен замінити символ основи.

locale.ERA

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

Більшість локалей не визначають це значення. Прикладом локалі, яка визначає це значення, є японська. У Японії традиційне представлення дат включає назву епохи, яка відповідає правлінню тодішнього імператора.

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

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])

Намагається визначити параметри мови за замовчуванням і повертає їх як кортеж у формі (код мови, кодування).

Відповідно до POSIX, програма, яка не викликала setlocale(LC_ALL, ''), працює з використанням портативної локалі 'C''. Виклик setlocale(LC_ALL, '') дозволяє використовувати локаль за замовчуванням, як визначено змінною LANG. Оскільки ми не хочемо втручатися в поточні налаштування локалі, ми таким чином емулюємо поведінку, як описано вище.

Щоб підтримувати сумісність з іншими платформами, перевіряється не лише змінна LANG, але й список змінних, наданий як параметр envvars. Використовуватиметься перший знайдений. envvars за умовчанням використовує шлях пошуку, який використовується в GNU gettext; він завжди повинен містити назву змінної 'LANG'. Шлях пошуку GNU gettext містить 'LC_ALL', 'LC_CTYPE', 'LANG' і 'LANGUAGE', у такому порядку.

The language code has the same format as a locale name, but without encoding and @-modifier. The language code and encoding may be None if their values cannot be determined. The „C” locale is represented as (None, None).

Deprecated since version 3.11, will be removed in version 3.15.

locale.getlocale(category=LC_CTYPE)

Returns the current setting for the given locale category as a tuple containing the language code and encoding. category may be one of the LC_* values except LC_ALL. It defaults to LC_CTYPE.

The language code has the same format as a locale name, but without encoding and @-modifier. The language code and encoding may be None if their values cannot be determined. The „C” locale is represented as (None, None).

locale.getpreferredencoding(do_setlocale=True)

Повертає locale encoding, що використовується для текстових даних, відповідно до вподобань користувача. Налаштування користувача виражаються по-різному в різних системах і можуть бути недоступні програмно в деяких системах, тому ця функція повертає лише припущення.

У деяких системах необхідно викликати setlocale(), щоб отримати параметри користувача, тому ця функція небезпечна для потоків. Якщо виклик setlocale не є необхідним або бажаним, do_setlocale має бути встановлено на False.

На Android или если включен режим Python UTF-8 <utf8-mode>, всегда возвращайте 'utf-8', кодировка locale и аргумент do_setlocale имеют значение игнорируется.

Попередня ініціалізація Python налаштовує локаль LC_CTYPE. Дивіться також filesystem encoding and error handler.

Zmienione w wersji 3.7: Функция теперь всегда возвращает "utf-8" на Android или если включен режим Python UTF-8 <utf8-mode>`.

locale.getencoding()

Получите текущую кодировку локали:

  • В Android и VxWorks верните "utf-8".

  • В Unix верните кодировку текущей локали LC_CTYPE. Верните "utf-8", если nl_langinfo(CODESET) возвращает пустую строку: например, если текущая локаль LC_CTYPE не поддерживается.

  • В Windows верните кодовую страницу ANSI.

Попередня ініціалізація Python налаштовує локаль LC_CTYPE. Дивіться також filesystem encoding and error handler.

Эта функция аналогична getpreferredencoding(False) за исключением того, что эта функция игнорирует Python UTF-8 Mode.

Dodane w wersji 3.11.

locale.normalize(localename)

Повертає нормалізований код мови для заданої назви мови. Повернений код мови відформатовано для використання з setlocale(). Якщо нормалізація не вдається, вихідне ім’я повертається без змін.

Якщо задане кодування невідоме, функція за замовчуванням використовує кодування за замовчуванням для коду мови, як setlocale().

locale.strcoll(string1, string2)

Порівнює два рядки відповідно до поточного параметра LC_COLLATE. Як і будь-яка інша функція порівняння, повертає від’ємне або додатне значення, або 0, залежно від того, чи рядок1 порівнює до чи після рядок2 або дорівнює йому.

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, але враховує поточні налаштування мови.

Zmienione w wersji 3.7: Додано параметр ключового слова monetary.

locale.currency(val, symbol=True, grouping=False, international=False)

Форматує число val відповідно до поточних налаштувань LC_MONETARY.

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

Informacja

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

locale.str(float)

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

locale.delocalize(string)

Перетворює рядок у нормалізований числовий рядок відповідно до параметрів LC_NUMERIC.

Dodane w wersji 3.5.

locale.localize(string, grouping=False, monetary=False)

Перетворює нормалізований числовий рядок у відформатований рядок відповідно до параметрів LC_NUMERIC.

Dodane w wersji 3.10.

locale.atof(string, func=float)

Перетворює рядок на число відповідно до налаштувань LC_NUMERIC, викликаючи func в результаті виклику delocalize() для string.

locale.atoi(string)

Перетворює рядок на ціле число, дотримуючись угод LC_NUMERIC.

locale.LC_CTYPE

Категория локали для функций типа символов. Самое главное, эта категория определяет кодировку текста, то есть то, как байты интерпретируются как кодовые точки Unicode. См. PEP 538 и PEP 540, чтобы узнать, как эта переменная может быть автоматически приведена к C.UTF-8, чтобы избежать проблем, создаваемых недопустимыми настройками в контейнерах или несовместимыми настройками, передаваемыми через удаленные соединения SSH.

Python не использует внутри себя функции преобразования символов, зависящие от локали, из ctype.h. Вместо этого внутренний pyctype.h предоставляет независимые от локали эквиваленты, такие как Py_TOLOWER.

locale.LC_COLLATE

Локальна категорія для сортування рядків. Це впливає на функції strcoll() і strxfrm() модуля locale.

locale.LC_TIME

Локальна категорія для форматування часу. Функція time.strftime() відповідає цим умовам.

locale.LC_MONETARY

Локальна категорія для форматування грошових значень. Доступні параметри доступні з функції localeconv().

locale.LC_MESSAGES

Категорія мови для відображення повідомлень. Python наразі не підтримує повідомлень із залежністю від мови програми. Ця категорія може вплинути на повідомлення, які відображає операційна система, наприклад ті, що повертає os.strerror().

Это значение может быть недоступно в операционных системах, не соответствующих стандарту POSIX, особенно в Windows.

locale.LC_NUMERIC

Категория локали для форматирования чисел. Эта категория влияет на функции format_string(), atoi(), atof() и str() модуля locale. Все остальные операции числового форматирования не затрагиваются.

locale.LC_ALL

Комбінація всіх налаштувань мови. Якщо цей прапорець використовується під час зміни локалі, намагається встановити локаль для всіх категорій. Якщо це не вдається для будь-якої категорії, жодна категорія не змінюється взагалі. Коли локаль отримується за допомогою цього прапорця, повертається рядок, що вказує на налаштування для всіх категорій. Цей рядок пізніше можна використати для відновлення налаштувань.

locale.CHAR_MAX

Це символічна константа, яка використовується для різних значень, які повертає localeconv().

Przykład:

>>> 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_string(), str() .

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

Locale names

The format of the locale name is platform dependent, and the set of supported locales can depend on the system configuration.

On Posix platforms, it usually has the format [1]:

     language ["_" territory] ["." charset] ["@" modifier]

where language is a two- or three-letter language code from ISO 639, territory is a two-letter country or region code from ISO 3166, charset is a locale encoding, and modifier is a script name, a language subtag, a sort order identifier, or other locale modifier (for example, „latin”, „valencia”, „stroke” and „euro”).

On Windows, several formats are supported. [2] [3] A subset of IETF BCP 47 tags:

     language ["-" script] ["-" territory] ["." charset]
     language ["-" script] "-" territory "-" modifier

where language and territory have the same meaning as in Posix, script is a four-letter script code from ISO 15924, and modifier is a language subtag, a sort order identifier or custom modifier (for example, „valencia”, „stroke” or „x-python”). Both hyphen ('-') and underscore ('_') separators are supported. Only UTF-8 encoding is allowed for BCP 47 tags.

Windows also supports locale names in the format:

     language ["_" territory] ["." charset]

where language and territory are full names, such as „English” and „United States”, and charset is either a code page number (for example, „1252”) or UTF-8. Only the underscore separator is supported in this format.

The „C” locale is supported on all platforms.

Для авторів розширень і програм, які вбудовують Python

Модулі розширення ніколи не повинні викликати setlocale(), за винятком того, щоб дізнатися, яка поточна локаль. Але оскільки значення, що повертається, можна використати лише портативно, щоб відновити його, це не дуже корисно (за винятком, можливо, для того, щоб дізнатися, чи є локаль C).

Когда код Python использует модуль 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.bind_textdomain_codeset(domain, codeset)

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

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