22.1. gettext – Многоязычные службы интернационализации¶gettext – Multilingual internationalization services

22.1.2.1. Класс NullTranslations¶The NullTranslations class

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

class gettext.NullTranslations([fp])¶

Принимает необязательный объект файла fp, который игнорируется базовым классом. Инициализирует «защищённые» переменные экземпляра _info и _charset, которые устанавливаются производными классами, а также _fallback, который устанавливается через add_fallback(). Затем вызывает self._parse(fp), если fp не равен None.

_parse(fp)¶

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

add_fallback(fallback)¶

Добавляет fallback в качестве резервного объекта для текущего объекта перевода. Объект перевода должен обращаться к резервному, если не может предоставить перевод для заданного сообщения.

gettext(message)¶

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

lgettext(message)¶

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

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

ugettext(message)¶

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

ngettext(singular, plural, n)¶

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

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

lngettext(singular, plural, n)¶

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

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

ungettext(singular, plural, n)¶

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

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

info()¶

Возвращает «защищённую» переменную _info.

charset()¶

Возвращает «защищённую» переменную _charset.

output_charset()¶

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

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

set_output_charset(charset)¶

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

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

install([unicode[, names]])¶

Если флаг unicode равен false, этот метод устанавливает self.gettext() во встроенное пространство имён, связывая его с _. Если unicode равен true, он связывает self.ugettext(). По умолчанию unicode равен false.

Если задан параметр names, он должен быть последовательностью, содержащей имена функций, которые требуется установить во встроенное пространство имён в дополнение к _(). Поддерживаемые имена: 'gettext' (привязывается к self.gettext() или self.ugettext() в зависимости от флага unicode), 'ngettext' (привязывается к self.ngettext() или self.ungettext() в зависимости от флага unicode), 'lgettext' и 'lngettext'.

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

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

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

Изменено в версии 2.5: Добавлен параметр names.

22.1.2.2. Класс GNUTranslations¶The GNUTranslations class

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

GNUTranslations извлекает необязательные метаданные из каталога переводов. В GNU gettext принято включать метаданные как перевод пустой строки. Эти метаданные представлены в стиле RFC 822 пар key: value и должны содержать ключ Project-Id-Version. Если найден ключ Content-Type, то свойство charset используется для инициализации «защищённой» переменной экземпляра _charset, по умолчанию None, если не найдено. Если указана кодировка charset, то все идентификаторы сообщений и строки сообщений, читаемые из каталога, преобразуются в Unicode с использованием этой кодировки. Метод ugettext() всегда возвращает строку Unicode, а метод gettext() возвращает закодированную 8-битную строку. Для аргументов идентификаторов сообщений обоих методов допустимы как строки Unicode, так и 8-битные строки, содержащие только символы US-ASCII. Обратите внимание, что версии методов, работающие с Unicode (т.е. ugettext() и ungettext()), являются рекомендуемым интерфейсом для интернационализированных программ на Python.

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

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

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

GNUTranslations.gettext(message)¶

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

GNUTranslations.lgettext(message)¶

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

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

GNUTranslations.ugettext(message)¶

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

GNUTranslations.ngettext(singular, plural, n)¶

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

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

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

GNUTranslations.lngettext(singular, plural, n)¶

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

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

GNUTranslations.ungettext(singular, plural, n)¶

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

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

Вот пример:

n = len(os.listdir('.'))
cat = GNUTranslations(somefile)
message = cat.ungettext(
    'There is %(num)d file in this directory',
    'There are %(num)d files in this directory',
    n) % {'num': n}

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

22.1.2.3. Поддержка каталогов сообщений Solaris¶Solaris message catalog support

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

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

22.1.3.1. Локализация вашего модуля¶Localizing your module

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

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

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

Если переводчики предоставляют строки Unicode в своих файлах .po, вместо этого следует сделать:

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

22.1.3.2. Локализация вашего приложения¶Localizing your application

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

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

import gettext
gettext.install('myapplication')

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

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

22.1.3.3. Смена языка на лету¶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()

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

Обратите внимание, что второе использование _() не будет распознано программой pygettext как переводимое, поскольку это не строка.

Другой способ – следующий пример:

def N_(message): return message

animals = [N_('mollusk'),
           N_('albatross'),
           N_('rat'),
           N_('penguin'),
           N_('python'), ]

# ...
for a in animals:
    print _(a)

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

22.1.3.5. gettext() и lgettext()¶gettext() vs. lgettext()

В Python 2.4 было введено семейство функций lgettext(). Их цель – предоставить альтернативу, более совместимую с текущей реализацией GNU gettext. В отличие от gettext(), которая возвращает строки, закодированные с использованием той же кодировки, что и в файле перевода, lgettext() будет возвращать строки, закодированные в предпочтительной системной кодировке, возвращаемой locale.getpreferredencoding(). Также обратите внимание, что Python 2.4 вводит новые функции для явного выбора кодировки, используемой в переведённых строках. Если кодировка задана явно, даже lgettext() будет возвращать переведённые строки в запрошенной кодировке, как и следовало ожидать в реализации GNU gettext.