23.1. gettext – Многоязычные службы интернационализации¶gettext – Multilingual internationalization services

23.1.1. API GNU gettext¶GNU gettext API

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

gettext.bindtextdomain(domain, localedir=None)¶

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

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

gettext.bind_textdomain_codeset(domain, codeset=None)¶

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

gettext.textdomain(domain=None)¶

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

gettext.gettext(message)¶

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

gettext.lgettext(message)¶

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

gettext.dgettext(domain, message)¶

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

gettext.ldgettext(domain, message)¶

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

gettext.ngettext(singular, plural, n)¶

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

The Plural formula is taken from the catalog header. It is a C or Python expression that has a free variable n; the expression evaluates to the index of the plural in the catalog. See the GNU gettext documentation for the precise syntax to be used in .po files and the formulas for a variety of languages.

gettext.lngettext(singular, plural, n)¶

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

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

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

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

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

Обратите внимание, что 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.'))

23.1.2. API на основе классов¶Class-based API

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

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

Эта функция реализует стандартный алгоритм поиска файлов .mo. Она принимает domain, такой же, как в 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.

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

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

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

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

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

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

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

23.1.3. Интернационализация программ и модулей¶Internationalizing your programs and modules

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

1. подготовить программу или модуль, специально помечая переводимые строки
2. запустить набор инструментов над размеченными файлами для создания исходных каталогов сообщений
3. создание языковых переводов каталогов сообщений
4. используйте модуль gettext, чтобы строки сообщений были правильно переведены

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

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

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

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

(Python также включает чистые реализации этих программ на 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.lgettext

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

# начните с использования language1
lang1.install()

# ... проходит время, пользователь выбирает language 2
lang2.install()

# ... проходит ещё больше времени, пользователь выбирает 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))

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

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

• Peter Funk
• James Henstridge
• Juan David Ibáñez Palomar
• Marc-André Lemburg
• Martin von Löwis
• François Pinard
• Barry Warsaw
• Gustavo Niemeyer

Сноски