НАЗВАНИЕ¶

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($%)

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

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

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".

gettext_wrap_opts($)

Маленькая служебная функция, которая возвращает строку с подходящими параметрами "--no-wrap"/"--width" соответствующими заданному значению wrap-po.

each_message

This method iterates over each message in the PO file and processes it. It takes a subroutine reference and executes it with two arguments: 1) the "msgid" and 2) a hash reference containing the message content, which includes fields such as "msgstr".

replant

This method takes two parameters: the current "msgid" and the new "msgid". It removes the entry with the current "msgid" from the PO instance and reinserts it under the new "msgid" value.

message_by_document_position

This method takes a document position and returns the matching message as a list containing three elements: the "msgid", the "msgctxt", and the message content (which includes fields such as "msgstr").

message_by_msgid

This method takes a "msgid" and an optional "msgctxt", and returns the first matching message content, which includes fields such as "msgstr". If no "msgctxt" is provided, an empty string value is used. If no message entry is found with the given context, the method falls back to searching for a message without context.

АВТОРЫ¶

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