LOCALE::PO4A::PO.3PM(1)

НАЗВАНИЕ
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"); # возвращает 'bonjour'

    # Записать файл обратно
    $pofile->write('otherfile.po');

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

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

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

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

--porefs тип
    Задаёт формат сносок в комментариях PO-файла. Аргумент тип может быть одним из: never — не выводить никаких сносок, file — не выводить номера строк (точнее, все номера строк будут заменены на 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($%)
    Запросить перевод строки, указанной в качестве аргумента, в текущем каталоге. Если строка не найдена, функция возвращает исходную (непереведённую) строку.

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

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

    wrapcol
        количество символов в строке, после которых должен выполняться автоматический перенос текста на новую строку (по умолчанию: 76).

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(%)
    Добавить новую запись в конец текущего каталога. Принимает хеш-таблицу. Допустимые ключи:

    msgid
        строка на исходном языке.

    msgstr
        перевод.

    reference
        указание, где была найдена эта строка. Например: file.c:46 (строка 46 из файла «file.c»). Может быть списком (разделённым пробелами) в случае, если строка встречается несколько раз.

    comment
        добавленный вручную (переводчиком) комментарий. Формат может быть произвольным.

    automatic
        комментарий, добавленный программой извлечения строк. Для более подробной информации см. описание параметра --add-comments для программы xgettext.

    flags
        список флагов, разделённых пробелами, которые были заданы для данной записи .

        Допустимы следующие флаги: c-text, python-text, lisp-text, elisp-text, librep-text, smalltalk-text, java-text, awk-text, object-pascal-text, ycp-text, tcl-text, wrap, no-wrap и fuzzy.

        См. документацию gettext для описания их значений.

    type
        в основном это параметр для внутреннего использования: он используется при геттекстизации документов. Идея здесь состоит в том, чтобы разобрать и исходный документ, и перевод в PO-объект и сшить их, используя msgid одного в качестве msgid, а msgid второго в качестве msgstr. Чтобы удостовериться, что всё корректно, каждому msgid в PO-объектах присваивается тип, основываясь на структуре файла из которого они были извлечены (например, «chapt», «sect1», «p» и т.п. в DocBook). Если типы строк не совпадают, то это означает, что оба файла имеют разную структуру, и процесс завершается с ошибкой.

        Также эта информация записывается в виде автоматического комментария в PO-файл, поскольку это предоставляет переводчикам некоторый дополнительный контекст для строк, которые они переводят.

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

        Эта информация записывается в PO-файл с помощью флагов wrap или no-wrap.

    wrapcol
        не используется; данный параметр сохранен в целях обратной совместимости.

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

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)