gettext — Услуги по многоязычной интернационализации¶

Класс NullTranslations¶

Классы перевода - это то, что фактически реализует перевод строк сообщений исходного файла в переведенные строки сообщений. Базовый класс, используемый всеми классами перевода, - это NullTranslations; он предоставляет базовый интерфейс, который вы можете использовать для написания собственных специализированных классов перевода. Вот методы NullTranslations:

class gettext.NullTranslations(fp=None)¶

Принимает необязательный file object 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() к резервному варианту. В противном случае верните единственное число, если n равно 1; в противном случае верните множественное число. Переопределяется в производных классах.

pgettext(context, message)¶

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

Добавлено в версии 3.8.

npgettext(context, singular, plural, n)¶

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

Добавлено в версии 3.8.

info()¶

Возвращает словарь, содержащий метаданные, найденные в файле каталога сообщений.

charset()¶

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

install(names=None)¶

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

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

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

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

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

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

Класс GNUTranslations¶

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

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

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

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

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

class gettext.GNUTranslations¶

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

gettext(message)¶

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

ngettext(singular, plural, n)¶

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

Если идентификатор сообщения не найден в каталоге и указан запасной вариант, запрос перенаправляется в резервный метод ngettext(). В противном случае, когда n равно 1, возвращается значение в единственном числе, а во всех остальных случаях - значение во множественном числе.

Вот пример:

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 в каталоге и верните соответствующую строку сообщения в виде строки в Юникоде. Если в каталоге нет записи для идентификатора сообщения и контекста и был установлен резервный вариант, поиск перенаправляется в метод pgettext(). В противном случае возвращается идентификатор сообщения.

Добавлено в версии 3.8.

npgettext(context, singular, plural, n)¶

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

Если идентификатор сообщения для context не найден в каталоге и указан резервный вариант, запрос перенаправляется методу npgettext(), который является резервным. В противном случае, когда n равно 1, возвращается единственное число, а во всех остальных случаях возвращается множественное число.

Добавлено в версии 3.8.

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

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

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

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

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

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

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

Локализация вашего модуля¶

Если вы локализуете свой модуль, вы должны позаботиться о том, чтобы не вносить глобальных изменений, например, во встроенное пространство имен. Вам следует использовать не GNU gettext API, а 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().