gettext — службы интернационализации для многоязычных приложений

Класс NullTranslations

Классы перевода реализуют собственно преобразование строк сообщений в исходных файлах в переведённые строки сообщений. Базовым классом для всех классов перевода является NullTranslations; он предоставляет базовый интерфейс, который можно использовать для создания собственных специализированных классов перевода. Ниже перечислены методы NullTranslations:

class gettext.NullTranslations(fp=None)

Принимает необязательный файловый объект fp, который базовый класс игнорирует. Инициализирует «защищённые» переменные экземпляра _info и _charset, значения которым присваиваются в производных классах, а также _fallback, значение которой задаётся через add_fallback(). Затем вызывает self._parse(fp), если fp не равен None.

_parse(fp)

В базовом классе этот метод ничего не делает. Он принимает файловый объект fp, считывает данные из файла и инициализирует каталог сообщений. Если формат файла каталога сообщений не поддерживается, следует переопределить этот метод, чтобы реализовать разбор своего формата.

add_fallback(fallback)

Добавляет fallback в качестве резервного объекта для текущего объекта перевода. Объект перевода должен обращаться к резервному объекту, если не может предоставить перевод заданного сообщения.

gettext(message, /)

Если задан резервный объект, перенаправляет gettext() ему. В противном случае возвращает message. Переопределяется в производных классах.

ngettext(singular, plural, n, /)

Если задан резервный объект, перенаправляет ngettext() ему. В противном случае возвращает singular, когда n равно 1, и plural в остальных случаях. Переопределяется в производных классах.

pgettext(context, message, /)

Если задан резервный объект, перенаправляет pgettext() ему. В противном случае возвращает переведённое сообщение. Переопределяется в производных классах.

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

npgettext(context, singular, plural, n, /)

Если задан резервный объект, перенаправляет npgettext() ему. В противном случае возвращает переведённое сообщение. Переопределяется в производных классах.

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

info()

Возвращает словарь с метаданными из файла каталога сообщений.

charset()

Возвращает кодировку файла каталога сообщений.

install(names=None)

Этот метод устанавливает gettext() во встроенное пространство имён, связывая её с _.

Если указан параметр names, он должен быть последовательностью, содержащей имена функций, которые нужно установить во встроенном пространстве имён помимо _(). Поддерживаются имена 'gettext', 'ngettext', 'pgettext' и 'npgettext'.

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

import gettext
t = gettext.translation('mymodule', ...)
_ = t.gettext

Так _() помещается только в глобальное пространство имён модуля и влияет лишь на вызовы внутри него.

Изменено в версии 3.8: Добавлены 'pgettext' и 'npgettext'.

Класс GNUTranslations

Модуль gettext предоставляет ещё один класс, производный от NullTranslations: GNUTranslations. Этот класс переопределяет _parse(), чтобы поддерживать чтение файлов .mo в формате GNU gettext как с прямым, так и с обратным порядком байтов.

GNUTranslations извлекает необязательные метаданные из каталога перевода. В GNU gettext принято включать метаданные в перевод пустой строки. Эти метаданные представлены парами key: value в стиле RFC 822 и должны содержать ключ Project-Id-Version. Если найден ключ Content-Type, свойство charset используется для инициализации «защищённой» переменной экземпляра _charset; если ключ не найден, используется значение по умолчанию None. Если кодировка указана, все идентификаторы и строки сообщений, считанные из каталога, преобразуются в Unicode с использованием этой кодировки; в противном случае предполагается ASCII.

Поскольку идентификаторы сообщений также считываются как строки Unicode, все методы *gettext() будут считать идентификаторы сообщений строками Unicode, а не байтовыми строками.

Все пары ключ/значение помещаются в словарь, который задаётся в качестве «защищённой» переменной экземпляра _info.

Если неверно магическое число файла .mo, обнаружен неожиданный номер основной версии или возникли другие проблемы при чтении файла, при создании экземпляра класса GNUTranslations может быть вызвано исключение OSError.

class gettext.GNUTranslations

Переопределены следующие методы базового класса:

gettext(message, /)

Ищет в каталоге идентификатор message и возвращает соответствующую строку сообщения в формате Unicode. Если в каталоге нет записи для идентификатора message и задан резервный объект, поиск перенаправляется методу gettext() этого объекта. В противном случае возвращается идентификатор message.

ngettext(singular, plural, n, /)

Выполняет поиск формы множественного числа для идентификатора сообщения. Для поиска в каталоге в качестве идентификатора сообщения используется singular, а параметр n определяет, какую форму множественного числа использовать. Возвращённая строка сообщения имеет формат Unicode.

Если идентификатор сообщения не найден в каталоге и задан резервный объект, запрос перенаправляется методу ngettext() этого объекта. В противном случае, когда n равно 1, возвращается singular, а во всех остальных случаях — plural.

Пример:

n = len(os.listdir('.'))
cat = GNUTranslations(somefile)
message = cat.ngettext(
    'There is %(num)d file in this directory',
    'There are %(num)d files in this directory',
    n) % {'num': n}

pgettext(context, message, /)

Ищет в каталоге идентификатор message и context и возвращает соответствующую строку сообщения в формате Unicode. Если в каталоге нет записи для идентификатора message и контекста context, а резервный объект задан, поиск перенаправляется методу pgettext() этого объекта. В противном случае возвращается идентификатор message.

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

npgettext(context, singular, plural, n, /)

Выполняет поиск формы множественного числа для идентификатора сообщения. Для поиска в каталоге в качестве идентификатора сообщения используется singular, а параметр n определяет, какую форму множественного числа использовать.

Если идентификатор сообщения для контекста context не найден в каталоге и задан резервный объект, запрос перенаправляется методу npgettext() этого объекта. В противном случае, когда n равно 1, возвращается singular, а во всех остальных случаях — plural.

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

Поддержка каталогов сообщений Solaris

Операционная система Solaris определяет собственный двоичный формат файлов .mo, однако документации по этому формату найти не удалось, поэтому сейчас он не поддерживается.

Конструктор Catalog

В GNOME используется версия модуля gettext, созданного Джеймсом Хенстриджем, но в этой версии немного отличается API. Документированное использование выглядело так:

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

Для совместимости с этим более старым модулем функция Catalog() является псевдонимом функции translation(), описанной выше.

Одно из отличий этого модуля от версии Хенстриджа: его объекты каталогов поддерживали доступ через API отображений, однако, по-видимому, эта возможность не используется и поэтому сейчас не поддерживается.

Локализация модуля

При локализации модуля необходимо избегать глобальных изменений, например в пространстве имён встроенных объектов. Не следует использовать API GNU gettext; вместо него используйте API на основе классов.

Предположим, ваш модуль называется «spam», а файлы переводов .mo на разные естественные языки находятся в /usr/share/locale в формате GNU gettext. В начало модуля нужно поместить следующее:

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

Локализация приложения

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

В простом случае достаточно добавить следующий фрагмент кода в главный файл запуска приложения:

import gettext
gettext.install('myapplication')

Если нужно указать каталог локали, его можно передать функции install():

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)

В этом случае нужно отметить строки в списке animals как подлежащие переводу, но перевести их только при выводе на печать.

Вот один из способов решения этой задачи:

def _(message): return message

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

del _

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

Это работает, потому что фиктивное определение _() просто возвращает строку без изменений. Это фиктивное определение временно переопределяет любое определение _() в пространстве имён встроенных объектов (до команды del). Однако будьте осторожны, если в локальном пространстве имён уже есть предыдущее определение _().

Обратите внимание, что второе использование _() не позволит программе gettext распознать «a» как строку, подлежащую переводу, поскольку параметр не является строковым литералом.

Другой способ решения этой задачи показан в следующем примере:

def N_(message): return message

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

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

В этом случае строки, подлежащие переводу, отмечаются функцией N_(), которая не будет конфликтовать с каким-либо определением _(). Однако потребуется настроить программу извлечения сообщений так, чтобы она находила строки, отмеченные как подлежащие переводу с помощью N_(). xgettext, pygettext, pybabel extract и xpot поддерживают это с помощью параметра командной строки -k. Выбор N_() совершенно произволен; с тем же успехом можно было выбрать MarkThisStringForTranslation().