locale
— Internationalization services¶
Вихідний код: Lib/locale.py
Модуль locale
відкриває доступ до бази даних і функцій POSIX locale. Механізм локалізації POSIX дозволяє програмістам мати справу з певними культурними проблемами в додатку, не вимагаючи від програміста знання всіх особливостей кожної країни, де виконується програмне забезпечення.
The locale
module is implemented on top of the _locale
module,
which in turn uses an ANSI C locale implementation if available.
Модуль locale
визначає такі винятки та функції:
-
exception
locale.
Error
¶ Виняток виникає, коли локаль, передана
setlocale()
, не розпізнається.
-
locale.
setlocale
(category, locale=None)¶ Якщо вказано locale, а не
None
,setlocale()
змінює налаштування мови для категорії. Доступні категорії перераховані в описі даних нижче. locale може бути рядком або ітерацією двох рядків (код мови та кодування). Якщо це ітерація, вона перетворюється на назву локалі за допомогою механізму псевдонімів локалі. Порожній рядок визначає параметри користувача за замовчуванням. Якщо зміна локалі не вдається, виникає винятокError
. У разі успіху повертається нове налаштування мови.Якщо locale пропущено або
None
, повертається поточне налаштування для category.setlocale()
не є потокобезпечним у більшості систем. Програми зазвичай починаються з викликуimport locale locale.setlocale(locale.LC_ALL, '')
Це встановлює локаль для всіх категорій на налаштування користувача за замовчуванням (зазвичай вказується у змінній середовища
LANG
). Якщо після цього локаль не буде змінено, використання багатопоточності не повинно викликати проблем.
-
locale.
localeconv
()¶ Повертає базу даних локальних угод як словник. Цей словник має такі рядки як ключі:
Категорія
ключ
Значення
'десяткова_крапка''
Символ десяткової точки.
'групування''
Послідовність чисел, що вказує, які відносні позиції очікується
'thousands_sep
. Якщо послідовність закінчуєтьсяCHAR_MAX
, подальше групування не виконується. Якщо послідовність завершується0
, останній розмір групи використовується повторно.'thousands_sep''
Символ, що використовується між групами.
'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'
Еквівалент
'групування''
, що використовується для грошових значень.'позитивний_знак'
Символ, який використовується для позначення додатної грошової вартості.
'негативний_знак'
Символ, який використовується для позначення від’ємної грошової вартості.
'p_sign_posn/n_sign_posn''
Розташування знака (для додатних чи від’ємних значень) див. нижче.
Для всіх числових значень можна встановити значення
CHAR_MAX
, щоб вказати, що в цій локалі не вказано значення.Нижче наведено можливі значення для
'p_sign_posn'
і'n_sign_posn'
.Значення
Пояснення
0
Валюта та значення взяті в дужки.
1
Знак має передувати символу вартості та валюти.
2
Знак повинен слідувати за символом вартості та валюти.
3
Знак повинен стояти безпосередньо перед значенням.
4
Знак повинен слідувати безпосередньо за значенням.
CHAR_MAX
У цій локалі нічого не вказано.
The function sets temporarily the
LC_CTYPE
locale to theLC_NUMERIC
locale or theLC_MONETARY
locale if locales are different and numeric or monetary strings are non-ASCII. This temporary change affects other threads.Змінено в версії 3.7: The function now sets temporarily the
LC_CTYPE
locale to theLC_NUMERIC
locale in some cases.
-
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.
-
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
¶ Отримайте регулярний вираз, який можна використовувати з функцією регулярного виразу, щоб розпізнати позитивну відповідь на запитання «так/ні».
Примітка
The expression is in the syntax suitable for the
regex()
function from the C library, which might differ from the syntax used inre
.
-
locale.
NOEXPR
¶ Get a regular expression that can be used with the regex(3) function to recognize a negative response to a yes/no question.
-
locale.
CRNCYSTR
¶ Отримайте символ грошової одиниці, якому передує «-», якщо символ має стояти перед значенням, «+», якщо символ має стояти після значення, або «.» якщо символ повинен замінити символ основи.
-
locale.
ERA
¶ Get a string that represents the era used in the current locale.
Більшість локалей не визначають це значення. Прикладом локалі, яка визначає це значення, є японська. У Японії традиційне представлення дат включає назву епохи, яка відповідає правлінню тодішнього імператора.
Normally it should not be necessary to use this value directly. Specifying the
E
modifier in their format strings causes thetime.strftime()
function to use this information. The format of the returned string is not specified, and therefore you should not assume knowledge of it on different systems.
-
locale.
ERA_D_T_FMT
¶ Отримайте рядок формату для
time.strftime()
, щоб представити дату й час у спосіб, що залежить від місцевості й епохи.
-
locale.
ERA_D_FMT
¶ Отримайте рядок формату для
time.strftime()
, щоб представити дату залежно від локалі на основі епохи.
-
locale.
ERA_T_FMT
¶ Отримайте рядок формату для
time.strftime()
, щоб представити час залежно від локалі на основі епохи.
-
locale.
ALT_DIGITS
¶ Get a representation of up to 100 values used to represent the values 0 to 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'
, у такому порядку.За винятком коду
'C
, код мови відповідає RFC 1766. код мови і кодування можуть мати значенняNone
, якщо їх значення неможливо визначити.
-
locale.
getlocale
(category=LC_CTYPE)¶ Returns the current setting for the given locale category as sequence containing language code, encoding. category may be one of the
LC_*
values exceptLC_ALL
. It defaults toLC_CTYPE
.За винятком коду
'C
, код мови відповідає RFC 1766. код мови і кодування можуть мати значенняNone
, якщо їх значення неможливо визначити.
-
locale.
getpreferredencoding
(do_setlocale=True)¶ Return the encoding used for text data, according to user preferences. User preferences are expressed differently on different systems, and might not be available programmatically on some systems, so this function only returns a guess.
У деяких системах необхідно викликати
setlocale()
, щоб отримати параметри користувача, тому ця функція небезпечна для потоків. Якщо виклик setlocale не є необхідним або бажаним, do_setlocale має бути встановлено наFalse
.On Android or in the UTF-8 mode (
-X
utf8
option), always return'UTF-8'
, the locale and the do_setlocale argument are ignored.Змінено в версії 3.7: The function now always returns
UTF-8
on Android or if the UTF-8 mode is enabled.
-
locale.
normalize
(localename)¶ Повертає нормалізований код мови для заданої назви мови. Повернений код мови відформатовано для використання з
setlocale()
. Якщо нормалізація не вдається, вихідне ім’я повертається без змін.Якщо задане кодування невідоме, функція за замовчуванням використовує кодування за замовчуванням для коду мови, як
setlocale()
.
-
locale.
resetlocale
(category=LC_ALL)¶ Sets the locale for category to the default setting.
The default setting is determined by calling
getdefaultlocale()
. category defaults toLC_ALL
.
-
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)¶ Formats a number val according to the current
LC_NUMERIC
setting. The format follows the conventions of the%
operator. For floating point values, the decimal point is modified if appropriate. If grouping is true, also takes the grouping into account.Якщо monetary має значення true, для перетворення використовуються грошові розділювачі тисяч і рядки групування.
Обробляє специфікатори форматування як у
format % val
, але враховує поточні налаштування мови.Змінено в версії 3.7: Додано параметр ключового слова monetary.
-
locale.
format
(format, val, grouping=False, monetary=False)¶ Please note that this function works like
format_string()
but will only work for exactly one%char
specifier. For example,'%f'
and'%.0f'
are both valid specifiers, but'%f KiB'
is not.For whole format strings, use
format_string()
.Застаріло починаючи з версії 3.7: Use
format_string()
instead.
-
locale.
currency
(val, symbol=True, grouping=False, international=False)¶ Форматує число val відповідно до поточних налаштувань
LC_MONETARY
.The returned string includes the currency symbol if symbol is true, which is the default. If grouping is true (which is not the default), grouping is done with the value. If international is true (which is not the default), the international currency symbol is used.
Note that this function will not work with the „C“ locale, so you have to set a locale via
setlocale()
first.
-
locale.
str
(float)¶ Formats a floating point number using the same format as the built-in function
str(float)
, but takes the decimal point into account.
-
locale.
delocalize
(string)¶ Перетворює рядок у нормалізований числовий рядок відповідно до параметрів
LC_NUMERIC
.Нове в версії 3.5.
-
locale.
atof
(string, func=float)¶ Перетворює рядок на число відповідно до налаштувань
LC_NUMERIC
, викликаючи func в результаті викликуdelocalize()
для string.
-
locale.
atoi
(string)¶ Перетворює рядок на ціле число, дотримуючись угод
LC_NUMERIC
.
-
locale.
LC_CTYPE
¶ Locale category for the character type functions. Depending on the settings of this category, the functions of module
string
dealing with case change their behaviour.
-
locale.
LC_COLLATE
¶ Локальна категорія для сортування рядків. Це впливає на функції
strcoll()
іstrxfrm()
модуляlocale
.
-
locale.
LC_TIME
¶ Локальна категорія для форматування часу. Функція
time.strftime()
відповідає цим умовам.
-
locale.
LC_MONETARY
¶ Локальна категорія для форматування грошових значень. Доступні параметри доступні з функції
localeconv()
.
-
locale.
LC_MESSAGES
¶ Категорія мови для відображення повідомлень. Python наразі не підтримує повідомлень із залежністю від мови програми. Ця категорія може вплинути на повідомлення, які відображає операційна система, наприклад ті, що повертає
os.strerror()
.
-
locale.
LC_NUMERIC
¶ Locale category for formatting numbers. The functions
format()
,atoi()
,atof()
andstr()
of thelocale
module are affected by that category. All other numeric formatting operations are not affected.
-
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
Передумови, деталі, підказки, поради та застереження¶
The C standard defines the locale as a program-wide property that may be relatively expensive to change. On top of that, some implementation are broken in such a way that frequent locale changes may cause core dumps. This makes the locale somewhat painful to use correctly.
Спочатку, коли програма запускається, локаль C
локаль, незалежно від того, яку локаль вибирає користувач. Є один виняток: категорія LC_CTYPE
змінюється під час запуску, щоб встановити поточне кодування мови на бажане кодування мови користувача. Програма має чітко вказати, що їй потрібні бажані налаштування локалі користувача для інших категорій, викликавши setlocale(LC_ALL, '')
.
Викликати setlocale()
у певній бібліотечній процедурі, як правило, погана ідея, оскільки як побічний ефект це впливає на всю програму. Зберігати та відновлювати його майже так само погано: це дорого та впливає на інші потоки, які запускаються до відновлення налаштувань.
Якщо під час кодування модуля для загального використання вам потрібна незалежна від локалі версія операції, на яку впливає локаль (наприклад, певні формати, що використовуються з time.strftime()
), вам доведеться знайти спосіб зробити це без використання стандартної бібліотечної процедури. Ще краще — переконати себе, що використання налаштувань мови — це нормально. Лише в крайньому випадку ви повинні задокументувати, що ваш модуль несумісний з налаштуваннями локалі, відмінними від C
.
The only way to perform numeric operations according to the locale is to use the
special functions defined by this module: atof()
, atoi()
,
format()
, str()
.
Немає способу виконати перетворення регістру та класифікацію символів відповідно до локалі. Для текстових рядків (Unicode) вони виконуються лише відповідно до значення символу, тоді як для рядків байтів перетворення та класифікація виконуються відповідно до значення ASCII байта та байтів, для яких встановлено старший біт (тобто байти, що не належать до ASCII ) ніколи не перетворюються та не вважаються частиною класу символів, такого як літера чи пробіл.
Для авторів розширень і програм, які вбудовують Python¶
Модулі розширення ніколи не повинні викликати setlocale()
, за винятком того, щоб дізнатися, яка поточна локаль. Але оскільки значення, що повертається, можна використати лише портативно, щоб відновити його, це не дуже корисно (за винятком, можливо, для того, щоб дізнатися, чи є локаль C
).
When Python code uses the locale
module to change the locale, this also
affects the embedding application. If the embedding application doesn’t want
this to happen, it should remove the _locale
extension module (which does
all the work) from the table of built-in modules in the config.c
file,
and make sure that the _locale
module is not accessible as a shared
library.
Доступ до каталогів повідомлень¶
-
locale.
gettext
(msg)¶
-
locale.
dgettext
(domain, msg)¶
-
locale.
dcgettext
(domain, msg, category)¶
-
locale.
textdomain
(domain)¶
-
locale.
bindtextdomain
(domain, dir)¶
The locale module exposes the C library’s gettext interface on systems that
provide this interface. It consists of the functions gettext()
,
dgettext()
, dcgettext()
, textdomain()
, bindtextdomain()
,
and bind_textdomain_codeset()
. These are similar to the same functions in
the gettext
module, but use the C library’s binary format for message
catalogs, and the C library’s search algorithms for locating message catalogs.
Python applications should normally find no need to invoke these functions, and
should use gettext
instead. A known exception to this rule are
applications that link with additional C libraries which internally invoke
gettext()
or dcgettext()
. For these applications, it may be
necessary to bind the text domain, so that the libraries can properly locate
their message catalogs.