
        *****************************************************
        *           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"); # возвращает '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<file> — не выводить
номера строк (точнее, все номера строк будут заменены на 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>

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

=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)
