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 в качестве объекта fallback для текущего объекта перевода. Объект перевода должен обращаться к fallback, если он не может предоставить перевод для данного сообщения.

gettext(message)

Если fallback установлен, передаёт gettext() в fallback. В противном случае возвращает message. Переопределяется в производных классах.

ngettext(singular, plural, n)

Если fallback установлен, передаёт ngettext() в fallback. В противном случае возвращает singular, если n равно 1; в противном случае возвращает plural. Переопределяется в производных классах.

pgettext(context, message)

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

Новое в версии 3.8.

npgettext(context, singular, plural, n)

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

Новое в версии 3.8.

lgettext(message)

lngettext(singular, plural, n)

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

Предупреждение

От этих методов следует отказаться в Python 3. См. предупреждение для функции lgettext().

Устарело начиная с версии 3.8, удалено в версии 3.10.

info()

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

charset()

Возвращает кодировку файла каталога сообщений.

output_charset()

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

Устарело начиная с версии 3.8, удалено в версии 3.10.

set_output_charset(charset)

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

Устарело начиная с версии 3.8, удалено в версии 3.10.

install(names=None)

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

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

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

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.

lgettext(message)

lngettext(singular, plural, n)

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

Предупреждение

От этих методов следует отказаться в Python 3. См. предупреждение для функции lgettext().

Устарело с версии 3.8, удалено в версии 3.10.

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

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

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

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

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

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

Различие между этим модулем и модулем Henstridge: объекты его каталога поддерживали доступ через API отображения, но этот 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). Однако будьте осторожны, если у вас есть предыдущее определение _() в локальном пространстве имён.

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