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)

Ищет в каталоге контекст 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().