.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "LOCALE::PO4A::PO.3PM 1"
.TH LOCALE::PO4A::PO.3PM 1 2024-06-26 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH НАЗВАНИЕ
.IX Header "НАЗВАНИЕ"
Locale::Po4a::Po: модуль манипуляции PO\-файлами
.SH "КРАТКОЕ СОДЕРЖАНИЕ"
.IX Header "КРАТКОЕ СОДЕРЖАНИЕ"
.Vb 2
\&    use Locale::Po4a::Po;
\&    my $pofile=Locale::Po4a::Po\->new();
\&
\&    # Прочитать PO\-файл
\&    $pofile\->read(\*(Aqfile.po\*(Aq);
\&
\&    # Добавить запись
\&    $pofile\->push(\*(Aqmsgid\*(Aq => \*(AqHello\*(Aq, \*(Aqmsgstr\*(Aq => \*(Aqbonjour\*(Aq,
\&                  \*(Aqflags\*(Aq => "wrap", \*(Aqreference\*(Aq=>\*(Aqfile.c:46\*(Aq);
\&
\&    # Извлечь перевод
\&    $pofile\->gettext("Hello"); # returns \*(Aqbonjour\*(Aq
\&
\&    # Записать обратно в файл
\&    $pofile\->write(\*(Aqotherfile.po\*(Aq);
.Ve
.SH ОПИСАНИЕ
.IX Header "ОПИСАНИЕ"
Locale::Po4a::Po — это модуль, который позволяет вам производить манипуляции с каталогами сообщений. Вы можете читать и писать из/в файл (с расширением, обычно, \fIpo\fR), вы можете создавать новые записи на лету или запрашивать переводы строк.
.PP
Более всеобъемлющее описание того, что представляют из себя каталоги сообщений в PO\-формате и как их использовать, можно найти в документации программы gettext, в частности на её info\-странице (глава «PO Files»).
.PP
Этот модуль является частью проекта po4a, целью которого является использование PO\-файлов (разработанных изначально для перевода сообщений в самих программах) для перевода вообще всего, включая документацию (man и info\-страницы), описаний пакетов, шаблонов debconf, а также всего остального, где это только может принести хоть какую\-либо пользу.
.SH "ПАРАМЕТРЫ ПРИНИМАЕМЫЕ ЭТИМ МОДУЛЕМ"
.IX Header "ПАРАМЕТРЫ ПРИНИМАЕМЫЕ ЭТИМ МОДУЛЕМ"
.IP "\fB\-\-porefs\fR \fIтип\fR" 4
.IX Item "--porefs тип"
Задаёт формат сносок в комментариях PO\-файла. Аргумент \fIтип\fR может быть одним из: \fBnever\fR — не выводить никаких сносок, \fBnoline\fR — не выводить номера строк (точнее, все номера строк будут заменены на 1), \fBcounter\fR — заменяет номера строк инкрементным счётчиком и \fBfull\fR — включает полноценные сноски (по умолчанию: \fBfull\fR).
.IP "\fB\-\-wrap\-po\fR \fBno\fR|\fBnewlines\fR|\fIчисло\fR (по умолчанию: 76)" 4
.IX Item "--wrap-po no|newlines|число (по умолчанию: 76)"
Задаёт, как должны переносится строки в PO\-файле. С помощью этого параметра можно выбрать одно из двух: или чтобы переносы в файлах были удобно расставлены для чтения людьми (хотя это и может привести к конфликтам в git), или чтобы файлы больше подходили для автоматической обработки (хотя это и снизит удобство чтения оных людьми).
.Sp
Исторически сложилось так, что gettext переносил строки в PO\-файлах на 77\-м столбце (по косметическим соображениям). Этот параметр определяет, как должен вести себя po4a в связи с этим. Если в нём указано число, po4a будет переносить строки в PO\-файле после указанного столбца, а также после символов перевода строки в содержимом. Если указано \fBnewlines\fR, то po4a будет разделять msgid и msgstr на строки только в местах перевода строк в самом их содержимом. Если же указано \fBno\fR, то po4a вообще не будет переносить строки в PO\-файле. Строки комментариев со ссылками на местоположение строки в исходном документе всегда разбиваются на строки по усмотрению инструментов gettext, которые используются внутри po4a.
.Sp
Замечание: этот параметр ни как не влияет на то, как будут расставлены переносы строк внутри самих msgid и msgstr, т.е. на то, как переносы строк будут добавляться к их содержимому.
.IP "\fB\-\-msgid\-bugs\-address\fR \fIemail@address\fR" 4
.IX Item "--msgid-bugs-address email@address"
Установить адрес для сообщений об ошибках в msgid. По умолчанию, созданные POT\-файлы не имеют поля Report-Msgid-Bugs-To.
.IP "\fB\-\-copyright\-holder\fR \fIстрока\fR" 4
.IX Item "--copyright-holder строка"
Указать владельца авторских прав в заголовке POT файла. Значение по умолчанию: «Free Software Foundation, Inc.»
.IP "\fB\-\-package\-name\fR \fIстрока\fR" 4
.IX Item "--package-name строка"
Указать имя пакета в заголовке POT\-файла. Значение по умолчанию: «PACKAGE».
.IP "\fB\-\-package\-version\fR \fIстрока\fR" 4
.IX Item "--package-version строка"
Указать версию пакета в заголовке POT\-файла. Значение по умолчанию: «VERSION».
.SH "Функции, относящиеся ко всему каталогу сообщений"
.IX Header "Функции, относящиеся ко всему каталогу сообщений"
.IP \fBnew()\fR 4
.IX Item "new()"
Создаёт новый каталог сообщений. Если указан аргумент, то это имя PO\-файла, который будет загружен.
.IP read($) 4
.IX Item "read($)"
Читает PO\-файл (имя которого указано в качестве аргумента). Записи, уже присутствующие в каталоге, не удаляются; новые записи добавляются в конец каталога.
.IP write($) 4
.IX Item "write($)"
Записывает текущий каталог в указанный файл.
.IP write_if_needed($$) 4
.IX Item "write_if_needed($$)"
Аналогично \fBwrite()\fR, но если PO или POT\-файл уже существует, то объект будет записан во временный файл, который будет сравнён с существующим, дабы проверить, требуется ли обновление (это позволяет избежать изменения POT\-файла только для обновления сносок на строки в исходных документах или поля POT-Creation-Date).
.IP filter($) 4
.IX Item "filter($)"
Эта функция извлекает часть записей из существующего каталога сообщений в новый. В результирующий каталог будут помещены только записи, у которых есть сноски на строки в указанном файле (похоже, эта функция может фильтровать не только по файлу, \fIприм. переводчика\fR).
.Sp
Эта функция анализирует переданную ей строку, преобразуя её в функцию Perl, вызывает для неё \fBeval\fR и фильтрует каталог сообщений, оставляя только те поля, для которых функция возвращает true.
.Sp
Иногда я люблю Perl ;)
.SH "Функции для использования каталога сообщений для перевода"
.IX Header "Функции для использования каталога сообщений для перевода"
.IP gettext($%) 4
.IX Item "gettext($%)"
Запросить перевод строки, указанной в качестве аргумента, в текущем каталоге. Если строка не найдена, функция возвращает исходную (непереведённую) строку.
.Sp
После переводимой строки вы можете также передать хеш с дополнительными аргументами. Допустимые ключи:
.RS 4
.IP \fBwrap\fR 4
.IX Item "wrap"
логическое значение, указывающее, можем ли мы считать, что пробелы в строке не важны. Если да, функция канонизирует строку перед поиском перевода и добавляет переносы строк в результат по необходимости (вызывая \fBwrap()\fR).
.IP \fBwrapcol\fR 4
.IX Item "wrapcol"
количество символов в строке, после которых должен выполняться автоматический перенос текста на новую строку (по умолчанию: 76).
.RE
.RS 4
.RE
.IP \fBstats_get()\fR 4
.IX Item "stats_get()"
Возвращает статистику о коэффициенте попадания gettext (т.е. доли запросов, для которых был найден перевод строки) с момента последнего вызова \fBstats_clear()\fR. Обратите внимание, что это не та статистика, которую выводит \f(CW\*(C`msgfmt \-\-statistic\*(C'\fR. Эта функция возвращает статистику недавнего использования PO\-файла, в то с время как \fBmsgfmt\fR выводит информацию о количестве переводов и строк в самом файле. Пример использования:
.Sp
.Vb 1
\&    [некоторая работа с PO\-файлом для перевода чего\-нибудь]
\&
\&    ($percent,$hit,$queries) = $pofile\->stats_get();
\&    print "На данный момент мы нашли переводы для $percent\e% ($hit из $queries) строк.\en";
.Ve
.IP \fBstats_clear()\fR 4
.IX Item "stats_clear()"
Сбрасывает статистику успешности запросов gettext.
.SH "Функции для наполнения каталога сообщений"
.IX Header "Функции для наполнения каталога сообщений"
.IP push(%) 4
.IX Item "push(%)"
Добавить новую запись в конец текущего каталога. Принимает хеш\-таблицу. Допустимые ключи:
.RS 4
.IP \fBmsgid\fR 4
.IX Item "msgid"
строка на исходном языке.
.IP \fBmsgstr\fR 4
.IX Item "msgstr"
перевод.
.IP \fBreference\fR 4
.IX Item "reference"
указание, где была найдена эта строка. Например: file.c:46 (строка 46 из файла «file.c»). Может быть списком (разделённым пробелами) в случае, если строка встречается несколько раз.
.IP \fBcomment\fR 4
.IX Item "comment"
добавленный вручную (переводчиком) комментарий. Формат может быть произвольным.
.IP \fBautomatic\fR 4
.IX Item "automatic"
комментарий, добавленный программой извлечения строк. Для более подробной информации см. описание параметра \fB\-\-add\-comments\fR для программы \fBxgettext\fR.
.IP \fBflags\fR 4
.IX Item "flags"
список флагов, разделённых пробелами, которые были заданы для данной записи .
.Sp
Допустимы следующие флаги: \fBc\-text\fR, \fBpython-text\fR, \fBlisp-text\fR, \fBelisp-text\fR, \fBlibrep-text\fR, \fBsmalltalk-text\fR, \fBjava-text\fR, \fBawk-text\fR, \fBobject-pascal-text\fR, \fBycp-text\fR, \fBtcl-text\fR, \fBwrap\fR, \fBno-wrap\fR и \fBfuzzy\fR.
.Sp
См. документацию gettext для описания их значений.
.IP \fBtype\fR 4
.IX Item "type"
в основном это параметр для внутреннего использования: он используется при геттекстизации документов. Идея здесь состоит в том, чтобы разобрать и исходный документ, и перевод в PO\-объект и сшить их, используя msgid одного в качестве msgid, а msgid второго в качестве msgstr. Чтобы удостовериться, что всё корректно, каждому msgid в PO\-объектах присваивается тип, основываясь на структуре файла из которого они были извлечены (например, «chapt», «sect1», «p» и т.п. в DocBook). Если типы строк не совпадают, то это означает, что оба файла имеют разную структуру, и процесс завершается с ошибкой.
.Sp
Также эта информация записывается в виде автоматического комментария в PO\-файл, поскольку это предоставляет переводчикам некоторый дополнительный контекст для строк, которые они переводят.
.IP \fBwrap\fR 4
.IX Item "wrap"
логическое значение, указывающее, можно ли изменять пробельные символы ради косметического переформатирования. Если истина, то строка будет канонизирована перед использованием.
.Sp
Эта информация записывается в PO\-файл с помощью флагов \fBwrap\fR или \fBno-wrap\fR.
.IP \fBwrapcol\fR 4
.IX Item "wrapcol"
ignored; the key is kept for backward computability.
.RE
.RS 4
.RE
.SH "Прочие функции"
.IX Header "Прочие функции"
.IP \fBcount_entries()\fR 4
.IX Item "count_entries()"
Возвращает количество записей в каталоге (не считая заголовка).
.IP \fBcount_entries_doc()\fR 4
.IX Item "count_entries_doc()"
Возвращает количество записей в документе. Если строка встречается в документе несколько раз, она будет учитываться несколько раз.
.IP msgid($) 4
.IX Item "msgid($)"
Возвращает msgid записи с указанным порядковым номером.
.IP msgid_doc($) 4
.IX Item "msgid_doc($)"
Возвращает msgid с заданной порядковой позицией в документе.
.IP type_doc($) 4
.IX Item "type_doc($)"
Возвращает тип msgid с заданной позицией в документе. Вероятно, это полезно только для геттекстизации, и это значение хранится отдельно от \fB{$msgid}{'type'}\fR, поскольку этот тип может быть позднее перезаписан в случае, если строка с таким же \fR\f(CB$msgid\fR\fB\fR встретится в мастер\-докумете позднее.
.IP \fBget_charset()\fR 4
.IX Item "get_charset()"
Возвращает кодировку, указанную в PO\-заголовке. Если кодировка не установлена, возвращается \f(CW\*(C`UTF\-8\*(C'\fR.
.SH АВТОРЫ
.IX Header "АВТОРЫ"
.Vb 2
\& Денис Барбье (Denis Barbier) <barbier@linuxfr.org>
\& Мартин Кенсон (Martin Quinson) (mquinson#debian.org)
.Ve