Locale::Po4a::Po

Section: Инструменты Po4a (3pm)
Updated: 2024-01-29
Index Return to Main Contents

НАЗВАНИЕ

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

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

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

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

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

Эта информация не записывается в PO-файл.

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

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)

Index

НАЗВАНИЕ
КРАТКОЕ СОДЕРЖАНИЕ
ОПИСАНИЕ
ПАРАМЕТРЫ ПРИНИМАЕМЫЕ ЭТИМ МОДУЛЕМ
Функции, относящиеся ко всему каталогу сообщений
Функции для использования каталога сообщений для перевода
Функции для наполнения каталога сообщений
Прочие функции
АВТОРЫ

This document was created by using the manual pages.
Time: 00:28:47 GMT, January 29, 2024

po4av0.70