
        *****************************************************
        *           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 ($)

The column at which we should wrap text in output document (default: 76).

The negative value means not to wrap lines at all.

=back

Also it accepts next options for underlying Po-files: B<porefs>, B<copyright-holder>, B<msgid-bugs-address>, B<package-name>, B<package-version>, B<wrap-po>.

=back

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

=over 4

=item read($$$)

Add another input document data at the end of the existing array C<< @{$self->{TT}{doc_in}} >>.

This function takes two mandatory arguments and an optional one.
 * The filename to read on disk;
 * The name to use as filename when building the reference in the PO file;
 * The charset to use to read that file (UTF-8 by default)

Цей масив 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>

the column at which we should wrap (default: the value of B<wrapcol> specified during creation of the TransTractor or 76).

The negative value will be substracted from the default.

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

