gettext – Многоязычные сервисы интернационализации¶gettext – Multilingual internationalization services

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

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

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

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

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

Класс GNUTranslations¶The GNUTranslations class

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

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

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

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

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

class gettext.GNUTranslations¶

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

gettext(message)¶

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

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

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

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

npgettext(context, singular, plural, n)¶

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

Если идентификатор сообщения для context не найден в каталоге и указан резервный источник, запрос перенаправляется в метод 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 message catalog support

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

Конструктор каталога¶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), но, по-видимому, эта возможность не используется и поэтому в настоящее время не поддерживается.

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

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

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

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

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

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

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

import gettext
gettext.install('myapplication')

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

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

Переключение языков на лету¶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()

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

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