
        *****************************************************
        *           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::TransTractor — загальний засіб перекладу-видобування.

=head1 ОПИС

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

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

Формально, вхідними є такі аргументи:

=over 2

=item -

документ для перекладу;

=item -

файл PO, який містить переклади, які слід використати.

=back

На виході матимемо ось що:

=over 2

=item -

інший файл PO, який є результатом видобування придатних до перекладу рядків
із вхідного документа;

=item -

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

=back

Ось графічна схема роботи:

   Вхідний документ --\                             /---> Вихідний документ
                     \                           /       (перекладений)
                      +-> функція parse() ------+
                     /                           \
 Вхідний PO --------/                             \---> Вихідний PO
                                                         (видобутий)

=head1 ФУНКЦІЇ, ЯКІ ВАШ ОБРОБНИК МАЄ ПЕРЕВИЗНАЧИТИ

=over 4

=item parse()

Тут відбувається уся справа: обробка вхідних документів, створення виведених
даних та видобування придатних до перекладу рядків. Усе це доволі просто
зробити за допомогою функцій, які представлено у розділі B<ВНУТРІШНІ
ФУНКЦІЇ> нижче. Див. також розділ B<КОРОТКИЙ ОПИС>, де наведено приклад.

Ця функція викликається нижче функцією process(), але якщо ви захочете
використати функцію new() і додати дані до вашого документа вручну, вам слід
викликати цю функцію власноруч.

=item docheader()

Ця функція повертає заголовок, який слід додати до створеного документа із
належним обрамленням, щоб бути коментарем мовою перекладу. Див. розділ
B<Навчання розробників основам створення придатного для перекладу коду> з
підручника з L<po4a(7)|po4a.7>, щоб дізнатися більше про те, де її
використовують.

=back

=head1 КОРОТКИЙ ОПИС

Нижче наведено приклад коду обробки списку абзаців, кожен з яких починається
з «<p>». З міркувань простоти, будемо вважати, що документ має коректне
форматування, тобто у ньому є лише теґи «<p>», і ці теґи розташовано на
самому початку кожного абзацу.

 sub parse {
   my $self = shift;

   PARAGRAPH: while (1) {
       my ($paragraph,$pararef)=("","");
       my $first=1;
       my ($line,$lref)=$self->shiftline();
       while (defined($line)) {
           if ($line =~ m/<p>/ && !$first--; ) {
               # Ми бачимо <p> не вперше.
               # Повторно надсилаємо поточний рядок на вхід,
               #  і надсилаємо зібраний абзац на вихід
               $self->unshiftline($line,$lref);

               # Тепер, коли документ сформовано, перекладаємо його:
               #   - Вилучаємо початковий теґ
               $paragraph =~ s/^<p>//s;

               #   - додаємо на вихід початковий теґ (без перекладу) і
               #     решту абзаца (перекладену)
               $self->pushline(  "<p>"
                               . $self->translate($paragraph,$pararef)
                               );

               next PARAGRAPH;
           } else {
               # Дописуємо до абзаца
               $paragraph .= $line;
               $pararef = $lref unless(length($pararef));
           }

           # Повторно ініціалізуємо цикл
           ($line,$lref)=$self->shiftline();
       }
       # Не отримали визначеного рядка? Кінець вхідного файла.
       return;
   }
 }

Після реалізації функції parse ви можете використовувати ваш клас document
за допомогою відкритого (public) інтерфейсу, який представлено у наступному
розділі.

=head1 ВІДКРИТИЙ ІНТЕРФЕЙС для скриптів, які використовують ваш обробник

=head2 Конструктор

=over 4

=item process(%)

Ця функція може виконувати усі дії, які слід виконати з документом po4a за
один виклик. Її аргументи слід запакувати як хеш. ДІЇ:

=over 3

=item а)

Читає усі файли PO, вказані у po_in_name

=item б)

Читає усі початкові документи, вказані у file_in_name

=item в)

Обробляє документ

=item г)

Читає і дописує вказані додатки

=item д)

Записує перекладений документ до file_out_name (якщо вказано)

=item е)

Записує видобутий файл PO до po_out_name (якщо вказано)

=back

АРГУМЕНТИ, окрім тих, які приймаються new() (із очікуваним типом):

=over 4

=item file_in_name (@)

Список назв файлів, з яких слід прочитати вхідні дані документа.

=item file_in_charset ($)

Таблиця кодування, яку використано у вхідному документі (якщо не вказано,
буде використано UTF-8).

=item file_out_name ($)

Назва файла, до якого слід записати вихідний документ.

=item file_out_charset ($)

Таблиця кодування, яку використано у вихідному документі (якщо не вказано,
буде використано UTF-8).

=item po_in_name (@)

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

=item po_out_name ($)

Назва файла, до якого слід записати дані PO, що містять рядки, видобуті з
вхідного документа.

=item addendum (@)

Список назв файлів, з яких слід прочитати додатки.

=item addendum_charset ($)

Кодування символів додатків.

=back

=item new(%)

Створити документ po4a. Прийнятні параметри (у хеші, який передано як
параметр):

=over 4

=item verbose ($)

Встановлює рівень докладності.

=item debug ($)

Встановлює рівень діагностики.

=item wrapcol ($)

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

Від'ємне значення означає «не переносити рядки взагалі».

=back

Також приймаються такі параметри для базових файлів PO: B<porefs>,
B<copyright-holder>, B<msgid-bugs-address>, B<package-name>, B<package-Також
приймаються такі параметри для базових файлів PO: B<porefs>,
B<copyright-holder>, B<msgid-bugs-address>, B<package-name>,
B<package-version>, B<wrap-po>.

=back

=head2 Робота з файлами документів

=over 4

=item read($$$)

Додати ще дані з вхідного документа наприкінці наявного масиву C<<
@{$self->{TT}{doc_in}} >>.Додати ще дані з вхідного документа наприкінці
наявного масиву C<< @{$self->{TT}{doc_in}} >>.

Ця функція приймає два обов'язкових аргументи і один необов'язковий.
 * Назва файла, який слід прочитати з диска;
 * Назва, яку слід використати як назву файла при побудові посилання у файлі PO;
 * Назва, яку слід використати як назву файла при побудові посилання у файлі PO;
 * Кодування, яким слід скористатися для читання файла (типовим є UTF-8)

Цей масив C<< @{$self->{TT}{doc_in}} >> містить дані вхідного документа у форматі
масиву рядків із різним призначенням.
 * Рядок C<$textline> містить кожен з рядків вхідних текстових даних.
 * Рядок C<< $filename:$linenum >> містить його розташування у тексті і
   називається «прив'язка» (C<linenum> починається з 1).

Будь ласка, зауважте, що функція не обробляє будь-що. Функцію parse() слід
використовувати після завершення пакування вхідних файлів до документа.

=item write($)

Записати перекладений документ до файла із вказаною назвою.

Ці дані перекладеного документа можна отримати так:
 * C<< $self->docheader() >> містить текст заголовка для додатка, а
 * C<< @{$self->{TT}{doc_out}} >> містить кожен з рядків основного перекладеного тексту у форматі масиву.

=back

=head2 Робота з файлами PO

=over 4

=item readpo($)

Додати вміст файла (назва якого передається як аргументи) до наявного файла
вхідних даних PO. Старий вміст файла не відкидається.

=item writepo($)

Записати видобуті дані PO до файла із вказаною назвою.

=item stats()

Повертає деякі статистичні дані щодо поточного стану перекладу. Будь ласка,
зауважте, що ці статистичні дані — це не ті дані, які виводить команда
msgfmt --statistic. Це статистичні дані щодо використання файла PO, тоді як
дані msgfmt — це звіт щодо стану файла. Є обгорткою до функції
Locale::Po4a::Po::stats_get, застосованою до файла PO вхідних даних. Приклад
використання:

    [звичайне використання документа po4a...]

    ($percent,$hit,$queries) = $document->stats();
    print "Знайдено переклади $percent\%  ($hit з $queries) рядків.\n";

=back

=head2 Робота із додатками

=over 4

=item addendum($)

Будь ласка, зверніться до розділу L<po4a(7)|po4a.7>, щоб дізнатися більше
про додатки та те, як перекладачі мають їх писати. Щоб застосувати додаток
до перекладеного документа, просто передайте його назву цій функції, ось і
усе. ;)

Ця функція повертає ненульове ціле число, якщо станеться помилка.

=back

=head1 ВНУТРІШНІ ФУНКЦІЇ, які використовуються для написання похідних обробників

=head2 Отримуємо вхідні дані, надаємо результати

Передбачено чотири функції для отримання вхідних даних і повернення вихідних
даних. Вони дуже подібні до функцій shift/unshift та push/pop у Perl.

 * shift у Perl повертає перший запис масиву і викидає його з масиву.
 * unshift у Perl дописує запис на початку масиву як його перший запис.
 * pop у Perl повертає останній запис масиву і викидає його з масиву.
 * push у Perl дописує запис до масиву наприкінці.

Перша пара працює із вхідними даними, а друга — з вихідними. Мнемоніка: у
вхідних даних вас цікавитиме перший рядок, який дає shift, у вихідних ви
додаєте результат наприкінці, як це робить push.

=over 4

=item shiftline()

Ця функція повертає перший рядок для обробки і відповідне посилання
(запаковане до масиву) з масиву C<< @{$self->{TT}{doc_in}} >> і викидає з
цього масиву два перших записи. Тут дані посилання надаються рядком C<<
$filename:$linenum >>.

=item unshiftline($$)

Скасовує зсування останнього зсунутого рядка вхідного документа і його
прив'язки на початку C<< {$self->{TT}{doc_in}} >>.

=item pushline($)

Вставити новий рядок наприкінці C<< {$self->{TT}{doc_out}} >>.

=item popline()

Виштовхнути останній вставлений рядок з кінця C<< {$self->{TT}{doc_out}} >>.

=back

=head2 Позначення придатних до перекладу рядків

Одну функцію передбачено для обробки тексту, який має бути перекладено.

=over 4

=item translate($$$)

Обов'язкові аргументи:

=over 2

=item -

Рядок для перекладу

=item -

Посилання цього рядка (тобто розташування рядка у файлі вхідних даних)

=item -

Тип цього рядка (тобто текстовий опис його структурної ролі;
використовується у Locale::Po4a::Po::gettextization(); див. також
L<po4a(7)|po4a.7>, розділ B<Перетворення на формат gettextization: як це
працює?>)

=back

Ця функція також може приймати додаткові аргументи. Їх має бути упорядковано
як хеш. Приклад:

  $self->translate("string","ref","type",
                   'wrap' => 1);

=over

=item B<wrap>

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

=item B<wrapcol>

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

Від'ємне значення буде віднято від типового.

=item B<comment>

додатковий коментар, який буде дописано до запису.

=back

Дії:

=over 2

=item -

Вставляє рядок, посилання і тип до po_out.

=item -

Повертає переклад рядка (знайдений у po_in), щоб обробник міг зібрати
doc_out.

=item -

Обробляє кодування для перекодовування рядків до надсилання їх до po_out і
перед повертанням перекладів.

=back

=back

=head2 Інші функції

=over 4

=item verbose()

Повертає значення, яке вказує, чи було передано під час створення
TransTractor параметр докладного режиму повідомлень.

=item debug()

Повертає значення, яке вказує, чи було передано під час створення
TransTractor параметр режиму діагностики.

=item get_in_charset()

Ця функція повертає набір символів (кодування), який було визначено як
основний

=item get_out_charset()

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

Функція використовуватиме для виведення кодування, вказане у рядку
команди. Якщо кодування не вказано, буде використано кодування з вхідного
файла PO. Якщо ж у цьому файлі лишатиметься типове значення кодування,
«CHARSET», функція поверне значення кодування вхідного документа, отже
ніякого перекодування не виконуватиметься.

=back

=head1 МАЙБУТНІ НАПРЯМКИ

Недоліком поточної реалізації TransTractor є те, що модуль не здатен
обробляти перекладені документи, у яких містяться переклади усіма мовами,
наприклад, шаблони debconf або файли .desktop.

Для усування цієї проблеми достатньо змінити у інтерфейсі таке:

=over 2

=item -

отримати хеш як po_in_name (один список на мову)

=item -

додати аргумент для перекладу, щоб вказати мову перекладу

=item -

створити функцію pushline_all, яка виконуватиме pushline своїх даних для
усіх мов з використанням map-подібного синтаксису:

    $self->pushline_all({ "Description[".$langcode."]=".
                          $self->translate($line,$ref,$langcode)
                        });

=back

Побачимо, чи цього досить ;)

=head1 АВТОРИ

 Denis Barbier <barbier@linuxfr.org>
 Martin Quinson (mquinson#debian.org)
 Jordi Vilalta <jvprat@gmail.com>
