gettext — Услуги по многоязычной интернационализации¶

GNU gettext API¶

Модуль gettext определяет следующий API, который очень похож на API GNU gettext. Если вы используете этот API, вы повлияете на перевод всего вашего приложения глобально. Часто это то, что вам нужно, если ваше приложение одноязычное, а выбор языка зависит от локали вашего пользователя. Если вы локализуете модуль Python или если вашему приложению нужно переключать языки «на лету», вы, вероятно, захотите использовать API на основе классов.

gettext.bindtextdomain(domain, localedir=None)¶

Связывает домен с каталогом локали localedir. Более конкретно, gettext будет искать двоичные .mo файлы для заданного домена, используя путь (на Unix): localedir/language/LC_MESSAGES/domain.mo, где language ищется в переменных окружения LANGUAGE, LC_ALL, LC_MESSAGES и LANG соответственно.

Если localedir опущен или None, то возвращается текущая привязка для domain. 1

gettext.bind_textdomain_codeset(domain, codeset=None)¶

Привязка domain к codeset, изменяющая кодировку байтовых строк, возвращаемых функциями lgettext(), ldgettext(), lngettext() и ldngettext(). Если codeset опущен, то возвращается текущая привязка.

Deprecated since version 3.8, removed in version 3.10.

gettext.textdomain(domain=None)¶

Изменение или запрос текущего глобального домена. Если domain равно None, то возвращается текущий глобальный домен, иначе глобальный домен устанавливается в domain, который и возвращается.

gettext.gettext(message)¶

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

gettext.dgettext(domain, message)¶

Как gettext(), но искать сообщение в указанном домене.

gettext.ngettext(singular, plural, n)¶

Аналогично gettext(), но учитывает формы множественного числа. Если перевод найден, примените формулу множественного числа к n и верните полученное сообщение (некоторые языки имеют более двух форм множественного числа). Если перевод не найден, верните singular, если n равно 1; верните plural в противном случае.

Формула множественного числа берется из заголовка каталога. Она представляет собой выражение на языке C или Python со свободной переменной n; выражение оценивается по индексу множественного числа в каталоге. Точный синтаксис для использования в файлах the GNU gettext documentation и формулы для различных языков смотрите в .po.

gettext.dngettext(domain, singular, plural, n)¶

Как ngettext(), но искать сообщение в указанном домене.

gettext.pgettext(context, message)¶

gettext.dpgettext(domain, context, message)¶

gettext.npgettext(context, singular, plural, n)¶

gettext.dnpgettext(domain, context, singular, plural, n)¶

Аналогичны соответствующим функциям без p в префиксе (то есть gettext(), dgettext(), ngettext(), dngettext()), но перевод ограничивается заданным контекстом сообщения.

Добавлено в версии 3.8.

gettext.lgettext(message)¶

gettext.ldgettext(domain, message)¶

gettext.lngettext(singular, plural, n)¶

gettext.ldngettext(domain, singular, plural, n)¶

Эквивалентна соответствующим функциям без префикса l (gettext(), dgettext(), ngettext() и dngettext()), но перевод возвращается в виде строки байт, закодированной в предпочтительной системной кодировке, если другая кодировка не была явно задана с помощью bind_textdomain_codeset().

Предупреждение

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

Deprecated since version 3.8, removed in version 3.10.

Обратите внимание, что в GNU gettext также определен метод dcgettext(), но он был признан бесполезным и в настоящее время не реализован.

Вот пример типичного использования этого API:

import gettext
gettext.bindtextdomain('myapplication', '/path/to/my/language/directory')
gettext.textdomain('myapplication')
_ = gettext.gettext
# ...
print(_('This is a translatable string.'))

API на основе классов¶

API на основе классов модуля gettext дает вам большую гибкость и большее удобство, чем API GNU gettext. Это рекомендуемый способ локализации приложений и модулей Python. gettext определяет класс GNUTranslations, который реализует разбор файлов формата GNU .mo и имеет методы для возврата строк. Экземпляры этого класса могут также устанавливаться во встроенное пространство имен как функция _().

gettext.find(domain, localedir=None, languages=None, all=False)¶

Эта функция реализует стандартный алгоритм поиска файлов .mo. Она принимает домен, идентичный тому, что принимает textdomain(). Необязательный localedir - как в bindtextdomain(). Необязательный languages - это список строк, где каждая строка - это код языка.

Если localedir не указан, то используется каталог системной локали по умолчанию. 2 Если languages не указан, то поиск выполняется по следующим переменным окружения: LANGUAGE, LC_ALL, LC_MESSAGES и LANG. Первая из них, возвращающая непустое значение, используется для переменной languages. Переменные окружения должны содержать список языков через двоеточие, который будет разделен на двоеточия для получения ожидаемого списка кодовых строк языка.

find() затем расширяет и нормализует языки, а затем итеративно просматривает их, ища существующий файл, построенный из этих компонентов:

localedir/language/LC_MESSAGES/domain.mo

Первое такое имя файла, которое существует, возвращается командой find(). Если такой файл не найден, то возвращается None. Если указано all, то возвращается список всех имен файлов, в том порядке, в котором они появляются в списке языков или переменных окружения.

gettext.translation(domain, localedir=None, languages=None, class_=None, fallback=False, codeset=None)¶

Возвращает экземпляр *Translations на основе domain, localedir и languages, которые сначала передаются в find() для получения списка соответствующих .mo путей к файлам. Экземпляры с одинаковыми именами файлов .mo кэшируются. Фактический инстанцируемый класс - это class_, если он указан, иначе GNUTranslations. Конструктор класса должен принимать один аргумент file object. Если предоставлено, codeset изменит кодовую сетку, используемую для кодирования переведенных строк в методах lgettext() и lngettext().

Если найдено несколько файлов, более поздние файлы используются в качестве запасных для более ранних. Для того чтобы можно было установить запасной вариант, copy.copy() используется для клонирования каждого объекта перевода из кэша; фактические данные экземпляра по-прежнему используются совместно с кэшем.

Если файл .mo не найден, эта функция поднимает OSError, если fallback равен false (что является значением по умолчанию), и возвращает экземпляр NullTranslations, если fallback равен true.

Изменено в версии 3.3: Раньше вместо IOError поднималось OSError.

Deprecated since version 3.8, removed in version 3.10: Параметр codeset.

gettext.install(domain, localedir=None, codeset=None, names=None)¶

Это устанавливает функцию _() в пространство имен Python builtins, основанное на domain, localedir и codeset, которые передаются в функцию translation().

Для параметра names см. описание метода install() объекта перевода.

Как показано ниже, вы обычно помечаете строки в вашем приложении, которые являются кандидатами на перевод, обернув их в вызов функции _(), как показано ниже:

print(_('This string will be translated.'))

Для удобства вы хотите, чтобы функция _() была установлена в пространстве имен Python builtins, чтобы она была легко доступна во всех модулях вашего приложения.

Deprecated since version 3.8, removed in version 3.10: Параметр codeset.

import gettext
cat = gettext.Catalog(domain, localedir)
_ = cat.gettext
print(_('hello world'))

Интернационализация ваших программ и модулей¶

Интернационализация (I18N) - это операция, с помощью которой программа воспринимает несколько языков. Локализация (L10N) - это адаптация вашей программы, после интернационализации, к местному языку и культурным традициям. Чтобы обеспечить многоязычные сообщения для ваших программ на Python, вам необходимо выполнить следующие шаги:

1. подготовить программу или модуль, специально пометив переводимые строки

2. запуск набора инструментов над вашими маркированными файлами для создания каталогов необработанных сообщений

3. создавать переводы каталогов сообщений на конкретные языки

4. использовать модуль gettext, чтобы строки сообщений переводились правильно

Для того чтобы подготовить код к I18N, необходимо просмотреть все строки в ваших файлах. Любая строка, которую необходимо перевести, должна быть помечена, обернув ее в _('...') — то есть вызовом функции _(). Например:

filename = 'mylog.txt'
message = _('writing a log message')
with open(filename, 'w') as fp:
    fp.write(message)

В этом примере строка 'writing a log message' помечена как кандидат на перевод, а строки 'mylog.txt' и 'w' - нет.

Существует несколько инструментов для извлечения строк, предназначенных для перевода. Оригинальный GNU gettext поддерживал только исходный код на C или C++, но его расширенная версия xgettext сканирует код, написанный на нескольких языках, включая Python, чтобы найти строки, помеченные как переводимые. Babel - это библиотека интернационализации Python, включающая сценарий pybabel для извлечения и компиляции каталогов сообщений. Программа Франсуа Пинара под названием xpot выполняет аналогичную работу и доступна как часть его po-utils package.

(Python также включает чисто питоновские версии этих программ, называемые pygettext.py и msgfmt.py; некоторые дистрибутивы Python установят их для вас. pygettext.py похож на xgettext, но понимает только исходный код Python и не может работать с другими языками программирования, такими как C или C++. pygettext.py поддерживает интерфейс командной строки, аналогичный xgettext; для получения подробной информации о его использовании запустите pygettext.py --help. msgfmt.py бинарно совместим с GNU msgfmt. С этими двумя программами вам может не понадобиться пакет GNU gettext для интернационализации ваших приложений Python).

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

Копии этих файлов .po затем передаются отдельным переводчикам, которые пишут переводы для каждого поддерживаемого естественного языка. Они отсылают готовые языковые версии в виде файла <language-name>.po, который компилируется в машиночитаемый файл двоичного каталога .mo с помощью программы msgfmt. Файлы .mo используются модулем gettext для фактической обработки перевода во время выполнения программы.

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

import gettext
t = gettext.translation('spam', '/usr/share/locale')
_ = t.gettext

import gettext
gettext.install('myapplication')

import gettext
gettext.install('myapplication', '/usr/share/locale')

import gettext

lang1 = gettext.translation('myapplication', languages=['en'])
lang2 = gettext.translation('myapplication', languages=['fr'])
lang3 = gettext.translation('myapplication', languages=['de'])

# start by using language1
lang1.install()

# ... time goes by, user selects language 2
lang2.install()

# ... more time goes by, user selects language 3
lang3.install()

animals = ['mollusk',
           'albatross',
           'rat',
           'penguin',
           'python', ]
# ...
for a in animals:
    print(a)

def _(message): return message

animals = [_('mollusk'),
           _('albatross'),
           _('rat'),
           _('penguin'),
           _('python'), ]

del _

# ...
for a in animals:
    print(_(a))

def N_(message): return message

animals = [N_('mollusk'),
           N_('albatross'),
           N_('rat'),
           N_('penguin'),
           N_('python'), ]

# ...
for a in animals:
    print(_(a))

Благодарности¶

Следующие люди предоставили код, отзывы, предложения по дизайну, предыдущие реализации и ценный опыт для создания этого модуля:

• Питер Функ

• Джеймс Хенстридж

• Хуан Давид Ибаньес Паломар

• Марк-Андре Лембург

• Мартин фон Лёвис

• Франсуа Пинар

• Барри Варшава

• Густаво Нимейер

Сноски

1

Каталог локали по умолчанию зависит от системы; например, в RedHat Linux это /usr/share/locale, а в Solaris это /usr/lib/locale. Модуль gettext не пытается поддерживать эти системно-зависимые значения по умолчанию; вместо этого по умолчанию используется sys.base_prefix/share/locale (см. sys.base_prefix). По этой причине всегда лучше вызывать bindtextdomain() с явным абсолютным путем в начале вашего приложения.

2

См. сноску для bindtextdomain() выше.