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.

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

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

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, метаданные включаются как перевод для пустой строки. Эти метаданные находятся в парах типа RFC 822-стиля key: value и должны содержать ключ 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 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().