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(), чтобы обеспечить чтение файлов формата GNU gettext .mo в форматах с прямым и обратным порядком байтов.

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)

Ищет в каталоге идентификаторы context и message и возвращает соответствующую строку сообщения в виде строки 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().