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

Обратите внимание, что второе использование _() не будет идентифицировать «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().