
        *****************************************************
        *           GENERATED FILE, DO NOT EDIT             *
        * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
        *****************************************************

This file was generated by po4a(7). Do not store it (in VCS, for example),
but store the PO file used as source file by po4a-translate.

In fact, consider this as a binary, and the PO file as a regular .c file:
If the PO get lost, keeping this translation up-to-date will be harder.

=encoding UTF-8

=head1 НАЗВАНИЕ

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

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

    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');

=head1 ОПИСАНИЕ

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

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

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

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

=over 4

=item B<--porefs> I<тип>

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

=item B<--wrap-po> B<no>|B<newlines>|I<число> (по умолчанию: 76)

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

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

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

=item B<--msgid-bugs-address> I<email@address>

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

=item B<--copyright-holder> I<строка>

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

=item B<--package-name> I<строка>

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

=item B<--package-version> I<строка>

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

=back

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

=over 4

=item new()

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

=item read($)

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

=item write($)

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

=item write_if_needed($$)

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

=item filter($)

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

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

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

=back

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

=over 4

=item gettext($%)

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

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

=over 

=item B<wrap>

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

=item B<wrapcol>

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

=back

=item stats_get()

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

    [некоторая работа с PO-файлом для перевода чего-нибудь]

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

=item stats_clear()

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

=back

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

=over 4

=item push(%)

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

=over 4

=item B<msgid>

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

=item B<msgstr>

перевод.

=item B<reference>

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

=item B<comment>

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

=item B<automatic>

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

=item B<flags>

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

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

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

=item B<type>

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

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

=item B<wrap>

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

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

=item B<wrapcol>

ignored; the key is kept for backward computability.

=back

=back

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

=over 4

=item count_entries()

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

=item count_entries_doc()

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

=item msgid($)

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

=item msgid_doc($)

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

=item type_doc($)

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

=item get_charset()

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

=back

=head1 АВТОРЫ

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

