НАЗВАНИЕ

Locale::Po4a::Po: модуль манипуляции PO-файлами

КРАТКОЕ СОДЕРЖАНИЕ

use Locale::Po4a::Po;
my $pofile=Locale::Po4a::Po->new();
# Прочитать PO-файл
$pofile->read('file.po');
# Добавить запись
$pofile->push('msgid' => 'Hello', 'msgstr' => 'bonjour',
              'flags' => "wrap", 'reference'=>'file.c:46');
# Извлечь перевод
$pofile->gettext("Hello"); # returns 'bonjour'
# Записать обратно в файл
$pofile->write('otherfile.po');

ОПИСАНИЕ

Locale::Po4a::Po — это модуль, который позволяет вам производить манипуляции с каталогами сообщений. Вы можете читать и писать из/в файл (с расширением, обычно, po), вы можете создавать новые записи на лету или запрашивать переводы строк.

Более всеобъемлющее описание того, что представляют из себя каталоги сообщений в PO-формате и как их использовать, можно найти в документации программы gettext, в частности на её info-странице (глава «PO Files»).

Этот модуль является частью проекта po4a, целью которого является использование PO-файлов (разработанных изначально для перевода сообщений в самих программах) для перевода вообще всего, включая документацию (man и info-страницы), описаний пакетов, шаблонов debconf, а также всего остального, где это только может принести хоть какую-либо пользу.

ПАРАМЕТРЫ ПРИНИМАЕМЫЕ ЭТИМ МОДУЛЕМ

--porefs тип

Задаёт формат сносок в комментариях PO-файла. Аргумент тип может быть одним из: never — не выводить никаких сносок, noline — не выводить номера строк (точнее, все номера строк будут заменены на 1), counter — заменяет номера строк инкрементным счётчиком и full — включает полноценные сноски (по умолчанию: full).

--wrap-po no|newlines|число (по умолчанию: 76)

Задаёт, как должны переносится строки в PO-файле. С помощью этого параметра можно выбрать одно из двух: или чтобы переносы в файлах были удобно расставлены для чтения людьми (хотя это и может привести к конфликтам в git), или чтобы файлы больше подходили для автоматической обработки (хотя это и снизит удобство чтения оных людьми).

Исторически сложилось так, что gettext переносил строки в PO-файлах на 77-м столбце (по косметическим соображениям). Этот параметр определяет, как должен вести себя po4a в связи с этим. Если в нём указано число, po4a будет переносить строки в PO-файле после указанного столбца, а также после символов перевода строки в содержимом. Если указано newlines, то po4a будет разделять msgid и msgstr на строки только в местах перевода строк в самом их содержимом. Если же указано no, то po4a вообще не будет переносить строки в PO-файле. Строки комментариев со ссылками на местоположение строки в исходном документе всегда разбиваются на строки по усмотрению инструментов gettext, которые используются внутри po4a.

Замечание: этот параметр ни как не влияет на то, как будут расставлены переносы строк внутри самих msgid и msgstr, т.е. на то, как переносы строк будут добавляться к их содержимому.

--msgid-bugs-address email@address

Установить адрес для сообщений об ошибках в msgid. По умолчанию, созданные POT-файлы не имеют поля Report-Msgid-Bugs-To.

--copyright-holder строка

Указать владельца авторских прав в заголовке POT файла. Значение по умолчанию: «Free Software Foundation, Inc.»

--package-name строка

Указать имя пакета в заголовке POT-файла. Значение по умолчанию: «PACKAGE».

--package-version строка

Указать версию пакета в заголовке POT-файла. Значение по умолчанию: «VERSION».

Функции, относящиеся ко всему каталогу сообщений

new()

Создаёт новый каталог сообщений. Если указан аргумент, то это имя PO-файла, который будет загружен.

read($)

Читает PO-файл (имя которого указано в качестве аргумента). Записи, уже присутствующие в каталоге, не удаляются; новые записи добавляются в конец каталога.

write($)

Записывает текущий каталог в указанный файл.

write_if_needed($$)

Аналогично write(), но если PO или POT-файл уже существует, то объект будет записан во временный файл, который будет сравнён с существующим, дабы проверить, требуется ли обновление (это позволяет избежать изменения POT-файла только для обновления сносок на строки в исходных документах или поля POT-Creation-Date).

filter($)

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

Эта функция анализирует переданную ей строку, преобразуя её в функцию Perl, вызывает для неё eval и фильтрует каталог сообщений, оставляя только те поля, для которых функция возвращает true.

Иногда я люблю Perl ;)

Функции для использования каталога сообщений для перевода

gettext($%)

Запросить перевод строки, указанной в качестве аргумента, в текущем каталоге. Если строка не найдена, функция возвращает исходную (непереведённую) строку.

После переводимой строки вы можете также передать хеш с дополнительными аргументами. Допустимые ключи:

stats_get()

Возвращает статистику о коэффициенте попадания gettext (т.е. доли запросов, для которых был найден перевод строки) с момента последнего вызова stats_clear(). Обратите внимание, что это не та статистика, которую выводит "msgfmt --statistic". Эта функция возвращает статистику недавнего использования PO-файла, в то с время как msgfmt выводит информацию о количестве переводов и строк в самом файле. Пример использования:

[некоторая работа с PO-файлом для перевода чего-нибудь]
($percent,$hit,$queries) = $pofile->stats_get();
print "На данный момент мы нашли переводы для $percent\% ($hit из $queries) строк.\n";

stats_clear()

Сбрасывает статистику успешности запросов gettext.

Функции для наполнения каталога сообщений

push(%)

Добавить новую запись в конец текущего каталога. Принимает хеш-таблицу. Допустимые ключи:

Прочие функции

count_entries()

Возвращает количество записей в каталоге (не считая заголовка).

count_entries_doc()

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

msgid($)

Возвращает msgid записи с указанным порядковым номером.

msgid_doc($)

Возвращает msgid с заданной порядковой позицией в документе.

type_doc($)

Возвращает тип msgid с заданной позицией в документе. Вероятно, это полезно только для геттекстизации, и это значение хранится отдельно от {$msgid}{'type'}, поскольку этот тип может быть позднее перезаписан в случае, если строка с таким же $msgid встретится в мастер-докумете позднее.

get_charset()

Возвращает кодировку, указанную в PO-заголовке. Если кодировка не установлена, возвращается "UTF-8".

АВТОРЫ

Денис Барбье (Denis Barbier) <barbier@linuxfr.org>
Мартин Кенсон (Martin Quinson) (mquinson#debian.org)