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

22.1.2.1. Класс NullTranslations¶The NullTranslations class

Классы перевода – это то, что фактически реализует перевод строк исходного сообщения в переведённые строки. Базовым классом, используемым всеми классами перевода, является 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() запасному объекту. В противном случае вернуть переведённое сообщение. Переопределяется в производных классах.

lgettext(message)¶

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

ngettext(singular, plural, n)¶

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

lngettext(singular, plural, n)¶

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

info()¶

Возвращает «защищённую» переменную _info.

charset()¶

Возвращает «защищённую» переменную _charset, которая является кодировкой файла каталога сообщений.

output_charset()¶

Возвращает «защищённую» переменную _output_charset, которая определяет кодировку для возврата переведённых сообщений в методах lgettext() и lngettext().

set_output_charset(charset)¶

Изменяет «защищённую» переменную _output_charset, которая определяет кодировку, используемую для возврата переведённых сообщений.

install(names=None)¶

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

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

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

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

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

22.1.2.2. Класс GNUTranslations¶The GNUTranslations class

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

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

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

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

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

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

GNUTranslations.gettext(message)¶

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

GNUTranslations.lgettext(message)¶

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

GNUTranslations.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}

GNUTranslations.lngettext(singular, plural, n)¶

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

22.1.2.3. Поддержка каталогов сообщений Solaris¶Solaris message catalog support

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

22.1.2.4. Конструктор Catalog¶The Catalog constructor

GNOME использует версию модуля gettext от James Henstridge, но эта версия имеет несколько иной API. Её задокументированное использование было:

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

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

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

22.1.3.1. Локализация модуля¶Localizing your module

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

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

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

22.1.3.2. Локализация приложения¶Localizing your application

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

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

import gettext
gettext.install('myapplication')

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

import gettext
gettext.install('myapplication', '/usr/share/locale')

22.1.3.3. Смена языка на лету¶Changing languages on the fly

Если программа должна одновременно поддерживать много языков, можно создать несколько экземпляров перевода и переключаться между ними явно:

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

22.1.3.4. Отложенные переводы¶Deferred translations

В большинстве случаев строки переводятся там же, где и пишутся. Однако иногда нужно пометить строки для перевода, но отложить собственно перевод на потом. Классический пример:

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). Следует соблюдать осторожность, если в локальном пространстве имён существует предыдущее определение _().

Обратите внимание, что второе использование _() не будет распознано программой pygettext как переводимое, поскольку это не строка.

Другой способ – следующий пример:

def N_(message): return message

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

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

В этом случае переводимые строки помечаются функцией N_(), [5] которая не конфликтует ни с одним определением _(). Однако потребуется научить программу извлечения сообщений искать переводимые строки, помеченные N_(). pygettext и xpot поддерживают это с помощью параметров командной строки.