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, он должен быть последовательностью, содержащей имена функций, которые вы хотите установить в пространстве имён builtins помимо _(). Поддерживаемые имена — 'gettext', 'ngettext', 'pgettext', и 'npgettext'.

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

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

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

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

Класс GNUTranslations

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

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)

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

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)

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

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

npgettext(context, singular, plural, n)

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

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

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

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

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

Конструктор каталога

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

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

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

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

Локализация вашего модуля

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

Предположим, что ваш модуль называется «spam», а различные файлы перевода на естественные языки модуля находятся в /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). Однако будьте осторожны, если у вас есть предыдущее определение _() в локальном пространстве имен.

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

Другой способ обработки этого — следующий пример:

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().