
        *****************************************************
        *           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 та принципів їхнього використання наведено у документації info до комплекту програм gettext (вузол «PO Files»).

Цей модуль є частиною проєкту po4a. Метою його створення було використання файлів PO (від початку створених для полегшення перекладу інтерфейсу програм) для перекладу будь-чого, зокрема документації (сторінок підручника, документації info), описів пакунків, шаблонів debconf та будь-чого, що корисно перекладати.

=head1 ПАРАМЕТРИ, ЯКІ МОЖНА ПЕРЕДАВАТИ ЦЬОМУ МОДУЛЮ

=over 4

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

Вказує формат посилань. Аргумент I<тип> може мати значення B<never>, якщо не слід взагалі створювати посилань; B<file>, якщо слід вказати файл без номерів рядків; B<counter>, якщо слід замінити номер рядка значенням лічильника; і B<full>, якщо посилання слід включити повністю (типове значення: 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, які програма використовує на внутрішньому рівні.

Зауважте, що цей параметр не стосується того, яким чином переноситимуться рядки у msgid і msgstr, тобто того, у який спосіб до цих рядків додаватимуться символи розриву рядків.

=item B<--msgid-bugs-address> I<адреса@електронної.пошти>

Встановити адресу для звітування щодо помилок у msgid (початкових неперекладених рядках). Типово, у створених файлах POT не буде полів Report-Msgid-Bugs-To.

=item B<--copyright-holder> I<рядок>

Встановити запис авторських прав у заголовку POTr. Типовим значенням є «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 (назва передається як аргумент). Наявні у self записи не вилучаються, нові додаються наприкінці каталогу.

=item write($)

Записує поточний каталог до вказаного файла.

=item write_if_needed($$)

Подібна до write, але якщо файл PO або POT вже існує, об'єкт буде записано до тимчасового файла, який буде порівняно із наявним файлом з метою визначити, чи потрібне оновлення (таким чином, ми уникаємо внесення змін до POT лише для оновлення посилань на рядки або поля дати створення POT).

=item filter($)

Ця функція видобуває каталог з наявного файла перекладу. До каталогу-результату буде включено лише ті записи, які містять посилання на вказаний файл.

Ця функція обробляє свій аргумент, перетворює його на визначення функції Perl, обробляє це визначення і фільтрує поля, для яких створена функція повертає true.

Іноді я люблю Perl ;)

=back

=head1 Функції для використання каталогу повідомлень для перекладів

=over 4

=item gettext($%)

Надсилає запит щодо перекладу рядка, переданого як аргумент, до поточного каталогу перекладів. Функція повертає початковий (неперекладений) рядок, якщо рядок не буде знайдено у каталозі.

Після рядка, який слід перекласти, ви можете передати хеш додаткових аргументів. Ось коректні записи цих аргументів:

=over 

=item B<wrap>

булеве значення, яке вказує на те, чи розглядаєте ви пробіли як неважливу частину рядка. Якщо має значення «yes» («так»), функція переводить рядок у канонічну форму, перш ніж шукати переклад, а потім виконує перенесення рядків у результаті пошуку.

=item B<wrapcol>

позиція, на якій слід переносити рядки (типове значення: 76).

=back

=item stats_get()

Повертає статистичні дані щодо пошуку відповідників з часу останнього виклику stats_clear(). Будь ласка, зауважте, що ці статистичні дані — це не ті дані, які виводить команда msgfmt --statistic. Це статистичні дані щодо використання файла PO, тоді як дані 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 (означає «file.c», у рядку 46). Може бути списком відокремлених пробілами значень, якщо рядок трапляється у декількох місцях.

=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> and B<fuzzy>.

Із призначенням прапорців можна ознайомитися у документації з gettext.

=item B<type>

здебільшого внутрішній аргумент: використовується під час перетворення на формат gettext даних документів. Ідея полягає у поєднанні оригіналу і перекладу у одному об'єкті PO, який використовує один із елементів msgid як msgid, а інший — як msgstr. Щоб переконатися, що усе гаразд, кожному msgid в об'єктах PO надається тип, який визначається на основі структури документа (наприклад «chapt», «sect1», «p» тощо у DocBook). Якщо типи рядків не однакові, це означає, що структура документів є різною, тому процес обробки повідомляє про помилку.

Ці відомості автоматично записуються як коментар до файла PO, оскільки надають перекладачам контекст щодо рядка, який вони перекладають.

=item B<wrap>

булеве значення, яке вказує на те, чи можна нехтувати пробілами при косметичному переформатуванні. Якщо має значення true, рядок переводиться до канонічної форми перед його використанням.

Ця інформація записується до файла 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 із заданою позицією у документі. Це, ймовірно, корисно лише для перетворення до формату gettext, і позиція зберігається окремо від {$msgid}{'type'}, оскільки останній запис може бути перезаписано іншим типом, коли $msgid дубльовано в основному документі.

=item get_charset()

Повертає кодування символів, яке вказано у заголовку файла PO. Якщо таке кодування не вказано, поверне рядок «UTF-8».

=back

=head1 АВТОРИ

 Denis Barbier <barbier@linuxfr.org>
 Martin Quinson (mquinson#debian.org)

