
        *****************************************************
        *           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 НАЗВА

po4a — набір інструментів для перекладу документації та інших матеріалів

=head1 Вступ

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

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

=head1 Чому po4a?

Філософія вільного програмного забезпечення полягає у наданні доступу до технологій усім. Втім, ліцензування не є єдиною причиною: неперекладене вільне програмне забезпечення є недоступним для тих, хто не знає англійської. Для того, щоб зробити його цінним для усіх, слід докласти додаткових зусиль з перекладу.

Усе це добре розуміють у більшості проєктів — зараз усі вже переконані у тому, що перекладати слід усе. Втім, сам переклад є результатом величезних зусиль багатьох осіб, які ускладнюють невеличкі технічні труднощі.

На щастя, саме вільне програмне забезпечення має досить якісний інструментарій для перекладу, дякуючи чудовому набору інструментів gettext. У нас є інструменти для видобування рядків для перекладу з програми і представлення їх у стандартизованому форматі (який називають файлами PO або каталогами перекладу). З'явилася ціла екосистема інструментів, які допомагають перекладачам перекладати ці файли PO. Результат перекладу використовується gettext під час роботи програми для показу кінцевим користувачам перекладених повідомлень.

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

Застарілі ж переклади часто є більшою проблемою, ніж неперекладена документація. Кінцевого користувача можна ввести в оману документацією, у якій описано поведінку застарілої версії програми. Крім того, користувачі перекладеної версії не можуть безпосередньо взаємодіяти із супровідниками, оскільки мають проблеми у спілкування англійською. До цього додається і те, що супровідник не може виправити проблему, оскільки не знає усі мови, якими перекладено документацію. Ці складнощі, часто викликані неналежним інструментарієм перекладу, можуть відлякати потенційних перекладачів, що робить ситуацію ще проблематичнішою.

B<Метою проєкту po4a є спрощення роботи для перекладачів документації>. Зокрема, цей проєкт робить переклади документації I<придатними до супроводу>.

Ідея полягає у повторному використанні і адаптації підходу gettext. Так само, як і з gettext для програм, текстові фрагменти видобуваються з початкових файлів і надаються перекладачам як каталоги перекладу PO. Перекладачі можуть скористатися класичними засобами gettext для стеження за виконанням завдань, співпраці та організації команд. Далі, po4a вставляє переклади безпосередньо до структури документації з метою створення перекладених початкових файлів, які можна обробляти і поширювати у той самий спосіб, у який обробляються і поширюються файли англійською. У документі-результаті усі неперекладені абзаци лишатимуться написаними англійською, отже кінцеві користувачі ніколи не побачать застарілих перекладів у документації.

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

Будь ласка, також ознайомтеся із розділом B<Поширені питання> у цьому документі, щоб дізнатися більше про переваги і недоліки цього підходу.

=head2 Підтримувані формати

У поточній версії цей підхід успішно реалізовано для декількох типів документів із текстовим форматуванням:

=over 

=item man (надійний обробник)

Старий добрий формат сторінок підручника, який використовується у багатьох програмах. Підтримка у po4a тут дуже доречна, оскільки цей формат доволі складний у використанні і не дуже зручний для недосвідчених користувачів.

У модулі L<Locale::Po4a::Man(3pm)|Man> також передбачена підтримка формату mdoc, який використовується у сторінках підручника BSD (їх також доволі часто використовують у Linux).

=item AsciiDoc (надійний обробник)

Цей формат є спрощеним форматом розмітки, призначенням якого є спростити написання документації. Його, наприклад, використано для документування системи git. Такі сторінки підручників перекладено за допомогою po4a.

Див. L<Locale::Po4a::AsciiDoc>, щоб дізнатися більше.

=item pod (надійний обробник)

Це формат інтернет-документації до Perl (Perl Online Documentation). За його допомогою документовано саму мову і її розширення, а також більшість із наявних скриптів Perl. Він спрощує синхронізацію документації із кодом, оскільки і документація, і код є частиною одного файла. Це спрощує завдання програміста, але, на жаль, не перекладача, доки ви не скористаєтеся po4a.

Див. L<Locale::Po4a::Pod>, щоб дізнатися більше.

=item sgml (надійний обробник)

Хоча цей формат на сьогодні дещо поступився місцем XML, його ще досить часто використовуються для досить довгих документів. За його допомогою можна створювати цілі книги. Оновлення перекладів таких довгих документів може стати справжнім жахом. B<diff> часто виявляється безпорадним, якщо відступи у початковому тексті після оновлення буде змінено. На щастя, тут у пригоді вам стане po4a.

У поточній версії передбачено підтримку лише DebianDoc і DocBook DTD, але додавання підтримки нових форматі є дуже простим. po4a можна навіть використовувати для невідомих DTD SGML без зміни коду, якщо надати потрібну інформацію за допомогою командного рядка. Див. L<Locale::Po4a::Sgml(3pm)>, щоб дізнатися більше.

=item TeX / LaTeX (надійний обробник)

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

Модуль L<Locale::Po4a::LaTeX(3pm)|LaTeX> було перевірено на документації до Python, книзі і декількох презентаціях.

=item text (надійний обробник)

Текстовий формат є базовим форматом для багатьох інших форматів, у яких ви маєте справу зі довгими блоками тексту, зокрема Markdown, fortune-и, розділ титульних елементів YAML, debian/changelog та debian/control.

Цей формат є типовим для генераторів статичних сайтів, файлів README та інших систем документації. Див. L<Locale::Po4a::Text(3pm)|Text>, щоб дізнатися більше.

=item xml і XHMTL (ймовірно, надійний обробник)

Формат XML є базовим для багатьох форматів документації.

У поточній версії po4a передбачено підтримку DocBook DTD (докладніше про це див. L<Locale::Po4a::Docbook(3pm)>) та XHTML.

=item BibTex (ймовірно, надійний обробник)

Формат BibTex використовують разом із LaTex для форматування списку посилань (бібліографій).

Див. L<Locale::Po4a::BibTex>, щоб дізнатися більше.

=item Docbook (ймовірно, надійний обробник)

Заснована на XML мова розмітки, у якій використовують семантичні теґи для опису документів.

Див. L<Locale::Po4a:Docbook>, щоб дізнатися більше.

=item Guide XML (ймовірно, надійний обробник)

Формат документації XML. Цей модуль розроблявся спеціально для того, щоб допомогти із підтримкою та супроводом перекладів документації Gentoo Linux, принаймні до березня 2016 року (дані засновано на даних Wayback Machine). З того часу Gentoo перейшла на формат XML DevBook.

Див. L<Locale::Po4a:Guide>, щоб дізнатися більше.

=item Wml (ймовірно, надійний обробник)

Мова розмітки інтернету (Web Markup Language), не плутати з WML із WAP, яку використовують для стільникового зв'язку. Роботу цього модуля засновано на роботі модуля Xhtml, який сам є надбудовою над модулем XML.

Див. L<Locale::Po4a::Wml>, щоб дізнатися більше.

=item Yaml (ймовірно, надійний обробник)

Строго обмежена надбудова над JSON. YAML часто використовують для проєктів систем або налаштувань. YAML є частиною ядра Ansible від Red Hat.

Див. L<Locale::Po4a::Yaml>, щоб дізнатися більше.

=item RubyDoc (ймовірно, надійний обробник)

Формат документів Ruby (RD), розроблено як типовий формат документації до Ruby і проєктів на Ruby до переходу на RDoc у 2002 році. Втім, принаймні японська версія підручника-довідника з Ruby усе ще використовує RD.

Див. L<Locale::Po4a::RubyDoc>, щоб дізнатися більше.



=item Halibut (ймовірно, експериментальний обробник)

Система створення документації із елементами, подібними до TeX, debiandoc-sgml, TeXinfo та інших систем. Розроблено Саймоном Тетгемом (Simon Tatham), розробником PuTTY.

Див. L<Locale::Po4a:Halibut>, щоб дізнатися більше.

=item Ini (ймовірно, експериментальний обробник)

Формат файлів налаштувань, який став популярним завдяки MS-DOS.

Див. L<Locale::Po4a::Ini>, щоб дізнатися більше.

=item texinfo (дуже експериментальний обробник)

У цьому форматі записано усю документацію GNU (наявність такої документації є навіть однією із вимог для отримання статусу офіційного проєкту GNU). Підтримка модуля L<Locale::Po4a::Texinfo(3pm)|Texinfo> у po4a усе ще перебуває на початковому етапі. Будь ласка, повідомляйте про вади та ваші запити щодо реалізації функціональних можливостей.

=item gemtext (very highly experimental parser)

The native plain text format of the Gemini protocol.  The extension ".gmi" is commonly used.  Support for this module in po4a is still in its infancy. If you find anything, please file a bug or feature request.

=item Інші підтримувані формати

Крім того, po4a також може працювати із іншими рідкісними і спеціалізованими форматами, зокрема документацією до параметрів компіляції ядер Linux 2.4+ (L<Locale::Po4a::KernelHelp>) та діаграмами, які створено за допомогою програми Dia (L<Locale::Po4a:Dia>). Додати новий формат часто доволі просто. Основним у цьому є є створення обробника початкового формату. Докладніший опис цього можна знайти у розділі L<Locale::Po4a::TransTractor(3pm)>.

=item Непідтримувані формати

На жаль, у po4a досі не реалізовано підтримку декількох форматів документації. Підтримку багатьох з них могло б бути доволі просто реалізовано у po4a. Це стосується і форматів, які не є форматами документації, зокрема описів пакунків (deb і rpm), питань у скриптах встановлення пакунків, журналів змін пакунків та усіх спеціалізованих форматів файлів, які використовуються програмами, зокрема сценаріїв ігор та файлів ресурсів wine.

=back

=head1 Користування po4a

Найпростішим способом використання цього інструмента у вашому проєкті є написання файла налаштувань для програми B<po4a> із наступною роботою лише із цією програмою. Будь ласка, зверніться до документації у підручнику з L<po4a(1)>. Решту цього розділу присвячено подробицям для досвідчених користувачів po4a, які хочуть дізнатися більше про роботу програми.

=head2 Докладна схема робочого процесу po4a

Спочатку ознайомтеся із підручником з L<po4a(1)>, щоб дізнатися про базові принципи роботи po4a. Повертайтеся до цього докладного опису, якщо хочете дізнатися про майже усі подробиці.

На наведеній нижче схемі F<основний.документ> — приклад назви документації, яку слід перекласти; F<XX.документ> — відповідний перекладений документ мовою XX, а F<doc.XX.po> — каталог перекладу для цього документа мовою XX. Автори документації, здебільшого мають перейматися файлом F<основний.документ> (це може бути сторінка підручника (man), документ XML, файл AsciiDoc або подібний документ); перекладачі, здебільшого, працюють із файлом PO, а кінцеві користувачі бачать лише файл F<XX.документ>.

Переходи із квадратними дужками, зокрема C<[po4a оновлює po]>, означають виконання програми po4a, а переходи із фігурними дужками, зокрема C<{оновлення основний.документ}>, означають внесення до файлів проєкту змін вручну.

                                   основний.документ
                                       |
                                       V
     +<-----<----+<-----<-----<--------+------->-------->-------+
     :           |                     |                        :
{переклад}       |     {оновлення основний.документ}          :
     :           |                     |                        :
 XX.документ     |                     V                        V
(необов'язковий) |              основний.документ ->------>---->+
     :           |                 (новий)                      |
     V           V                     |                        |
  [po4a-gettextize] документ.XX.po>+   |                        |
          |          (старий)      |   |                        |
          |              ^         V   V                        |
          |              |     [po4a оновлює po]                  |
          V              |           |                          V
     переклад.pot        ^           V                          |
          |              |      документ.XX.po                  |
          |              |       (неточний)                     |
     {переклад}        |           |                          |
          |              ^           V                          V
          |              |    {редагування вручну}              |
          |              |           |                          |
          V              |           V                          V
 документ.XX.po --->---->+<---<-документ.XX.po додаток  основний.документ
    (початковий)               (актуальний) (необов'язковий)(актуальний)
          :                          |            |             |
          :                          V            |             |
          +----->----->----->------> +            |             |
                                     |            |             |
                                     V            V             V
                                     +------>-----+------<------+
                                                  |
                                                  V
                                           [po4a оновлює переклади]
                                                  |
                                                  V
                                             XX.документ
                                             (актуальний)

Знову ж таки, ця схема надмірно складна. Зверніться до документації з L<po4a(1)>, щоб ознайомитися зі спрощеним оглядом.

У лівій частині показано як можна скористатися L<po4a-gettextize(1)> для перетворення наявного проєкту перекладу до інфраструктури po4a. Цей скрипт працює із початковим документом та його перекладеним аналогом і намагається зібрати відповідний файл PO. Таке перетворення вручну є доволі марудним (подробиці наведено у документації до L<po4a-gettextize(1)>), але таке перетворення потрібне лише один раз — для перетворення наявних перекладів. Якщо у вас немає ніяких перекладів для перетворення, ви можете забути про це і зосередитися на правій частині схеми.

У верхній частині праворуч зображено роботу автора початкового тексту (оновлення документації). У середній частині праворуч зображено послідовність автоматичних оновлень файлів перекладу. Новий тестовий матеріал видобувається з документа і порівнюється із наявним перекладом. Виявляються частини, які не змінилися, — для них використовується наявний переклад. Частини, які зазнали часткових змін також пов'язуються із попереднім перекладом, але із особливою позначкою, яка вказує на те, що переклад має бути оновлено. Новий або значно змінений матеріал лишається неперекладеним.

Then, the I<manual editing> block depicts the action of the translators, that modify the PO files to provide translations to every original string and paragraph. This can be done using either a specific editor such as the B<GNOME Translation Editor>, KDE's B<Lokalize> or B<poedit>, or using an online localization platform such as B<weblate> or B<pootle>. The translation result is a set of PO files, one per language. Please refer to the gettext documentation for more details.

У нижній частині схеми показано, як B<po4a> створює перекладений початкових документ на основі документа F<основний.документ> та каталогу перекладу F<документ.XX.po>, який було оновлено перекладачами. Програма використовує структуру початкового документа, але замінює початковий вміст на перекладені блоки. Якщо потрібно, може бути використано додаток для вставляння певного додаткового тексту до перекладу. Такі додатки часто використовуються для додавання імені перекладача до остаточного документа. Подробиці наведено нижче.

Після виклику B<po4a> оновлює файли перекладу та файли перекладеної документації автоматично.

=head2 Започаткування нового проєкту перекладу

Якщо ви починаєте на порожньому місці, вам слід просто написати файл налаштувань для po4a, і все. Програма створить відповідні шаблони для потрібних файлів, і ваші перекладачі зможуть перекласти проєкт рідною мовою. Будь ласка, зверніться до підручника з L<po4a(1)>, де наведено короткі відомості і подробиці.

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

=head2 Оновлення перекладів і документів

Після встановлення достатньо викликати B<po4a>, щоб оновити як файл PO перекладу, так і перекладені документи. Ви можете передати C<--no-translations> до B<po4a>, щоб не оновлювати переклади (таким чином оновлюючи лише файли PO) або C<--no-update>, щоб не оновлювати файли PO (таким чином оновлюючи лише переклади). Це приблизно відповідає окремим скриптам B<po4a-updatepo> і B<po4a-translate>, які зараз не рекомендуються (див. «Чому окремі скрипти застаріли» у розділі поширених питань нижче).

=head2 Використання додатків для вставляння додаткового тексту до перекладів

Додавання нового тексту до перекладу є, ймовірно, єдиною дією, яку простіше виконувати, якщо ви перекладаєте файли вручну :). Додавання може знадобитися, якщо вам потрібно додати до перекладеного документа додатковий розділ, який не відповідає жодного з розділів у початковому документі. Класичним випадком є додавання подяк команді перекладачів та вставляння нотатки щодо того, як повідомляти про вади, які пов'язано із перекладом.

У інфраструктурі po4a вам слід вказати файли B<додатків>, які концептуально можна розглядати як латки, які застосовуються до локалізованого документа після обробки. Кожен додаток має бути надано як окремий файл, формат якого, втім, значно відрізняється від формату класичних латок. Перший його рядок є I<рядком заголовка>, який визначає позицію вставлення додатка (із, на жаль, доволі складним синтаксисом — див. нижче), а решту файла буде буквально вставлено у визначеній позиції.

Рядок заголовка має розпочинатися з рядка B<PO4A-HEADER:>, за яким має бути вказано список відокремлених крапкою з комою полів I<ключ>B<=>I<значення>.

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

 PO4A-HEADER: mode=eof

Все стає складнішим, якщо ви хочете додати додаткові дані всередину документа. У наведеному нижче заголовку оголошується додаток, який має бути вставлено після розділу XML, який у перекладі містить рядок C<Про цей документ>.

=pod

 PO4A-HEADER: position=Про цей документ; mode=after; endboundary=</section>

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

 PO4A-HEADER: position=À propos de ce document; mode=after; endboundary=</section>

Щойно аргумент ключа C<position> буде знайдено у документі призначення, po4a виконає пошук наступного рядка після C<position>, який відповідає аргументу, заданому C<endboundary>. Додаток буде додано одразу B<після> цього рядка (оскільки нами надано I<endboundary> — межу поточного розділу).

Точно такого самого ефекту можна досягти із наведеним нижче заголовком, який є еквівалентним до вже використаного:

 PO4A-HEADER: position=Про цей документ; mode=after; beginboundary=<section>

Тут po4a шукає перший рядок, який відповідає C<< <section> >> після рядка C<Про цей документ> у перекладі, і вставляє додаток B<до> цього рядка, оскільки вказано I<beginboundary>, тобто початкову межу наступного розділу. Отже, цей рядок заголовка вимагає від програми вставити додаток після розділу, що містить рядок C<Про цей документ>, і вказує po4a, що розділ починається з рядка, що містить теґ C<< <section> >>. Це еквівалентно до попереднього прикладу, оскільки насправді нам потрібно вставити цей додаток або після C<< </section> >>, або перед C<< <section> >>.

You can also set the insertion I<mode> to the value C<before>, with a similar semantic: combining C<mode=before> with an C<endboundary> will put the addendum just B<after> the matched boundary, that is the last potential boundary line before the C<position>. Combining C<mode=before> with an C<beginboundary> will put the addendum just B<before> the matched boundary, that is the last potential boundary line before the C<position>.

  Режим  |    Тип межі   |     Використана межа     | Точка вставляння відносно межі
 ========|===============|==========================|=======================================
 'before'| 'endboundary' | остання перед 'position' | Одразу після вибраної межі
 'before'|'beginboundary'| остання перед 'position' | Одразу перед вибраною межею
 'after' | 'endboundary' | перша після 'position'   | Одразу після вибраної межі
 'after' |'beginboundary'| перша після 'position'   | Одразу перед вибраною межею
 'eof'   |   (немає)     |  н/д                   | Кінець файла

=head3 Підказки і настанови щодо додатків

=over 

=item 

Пам'ятайте, що ці рядки є формальними виразами. Наприклад, якщо ви хочете знайти кінець розділу nroff, що завершується рядком C<.fi>, не використовуйте C<.fi> у полі B<endboundary>, оскільки вказаний рядок є формальним виразом, за яким може бути знайдено, наприклад, рядок C<the[ fi]le>, що, звичайно ж, є небажаним. Правильним значенням для B<endboundary> у цьому випадку буде таке: C<^\.fi$>.

=item 

Пробіли є важливими у сенсі C<position> і меж. Отже, два наступних рядки B<є різними>. Другий рядок буде знайдено, лише якщо у перекладеному документі достатньо кінцевих пробілів.

 PO4A-HEADER: position=Про цей документ; mode=after; beginboundary=<section>
 PO4A-HEADER: position=Про цей документ ; mode=after; beginboundary=<section>

=item 

Хоча цей контекстний пошук можна розглядати як такий, що працює має із усіма рядками B<перекладеного> документа, насправді, він працює з внутрішніми даними рядка перекладеного документа. Цей внутрішній рядок даних може бути фрагментом тексту абзацу із декількох рядків або може бути лише теґом XML. Точна I<точка вставлення> додатка має знаходитися до або після внутрішнього рядка даних і не може перебувати всередині внутрішнього рядка даних.

=item 

Щоб зрозуміти, як програма вставляє додаток у переклад, передайте B<po4a> аргумент C<-vv>. Також може бути корисним запуск B<po4a> у режимі діагностики, щоб переглянути справжні внутрішні дані, якщо програма відмовляється вставляти ваш додаток.

=back

=head3 Приклади додатків

=over 

=item 

Якщо ви хочете додати щось після такого розділу nroff:

  .SH "AUTHORS"

Вам слід вибрати двокроковий підхід встановленням значення B<mode=after>. Далі, вам слід звузити пошук до рядка після B<AUTHORS> за допомогою параметра формального виразу B<position>. Далі, вам потрібно встановити відповідність початку нового розділу (тобто, B<^\.SH>) за допомогою параметра формального виразу B<beginboundary>. Тобто, слід зробити так:

 PO4A-HEADER:mode=after;position=AUTHORS;beginboundary=\.SH

=item 

Якщо ви хочете додати щось одразу після заданого рядка (наприклад, після «Copyright Big Dude»), вкажіть для B<position> критерій пошуку відповідного рядка, B<mode=after>, а для B<beginboundary> вкажіть відповідник будь-якого рядка.

 PO4A-HEADER:mode=after;position=Copyright Big Dude, 2004;beginboundary=^

=item 

Якщо ви хочете щось додати наприкінці документа, вкажіть для B<position> відповідник будь-якого рядка вашого документа (але лише одного, бо po4a відмовиться виконувати дію, якщо буде знайдено декілька таких рядків), а для B<endboundary> вкажіть рядок, якого немає у документі. Не використовуйте для цього рядка надто прості варіанти, наприклад B<"EOF">, — вкажіть щось, що має набагато менші шанси бути знайденим у документі.

 PO4A-HEADER:mode=after;position=Про цей документ;beginboundary=FakePo4aBoundary

=back



=head3 Докладніший приклад

Початковий документ (у форматуванні POD):

 |=head1 NAME
 |
 |dummy - a dummy program
 |
 |=head1 AUTHOR
 |
 |me

Далі, наведений нижче додаток забезпечить додавання розділу (українською) щодо перекладачів наприкінці файла.

 |PO4A-HEADER:mode=after;position=АВТОР;beginboundary=^=head
 |
 |=head1 ПЕРЕКЛАДАЧ
 |
 |я
 |

Щоб розташувати ваш додаток перед записом АВТОР, скористайтеся таким заголовком:

 PO4A-HEADER:mode=after;position=ІМ'Я;beginboundary=^=head1

Це працює, оскільки наступний рядок відповідника B<beginboundary> C</^=head1/> після розділу «NAME» (перекладеного як «ІМ'Я» українською) є розділ зі списком авторів. Отже, додаток буде розташовано між вказаними розділами. Зауважте, що якщо між розділами NAME і AUTHOR згодом буде додано ще якийсь розділ, po4a помилково додасть додаток перед новим розділом.

Щоб уникнути цього, ви можете досягти результату у інший спосіб за допомогою B<mode>=I<before>:

 PO4A-HEADER:mode=before;position=^=head1 АВТОР

=head1 Як усе це працює?

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

=head2 TransTractor-и та архітектура проєкту

В основі проєкту po4a клас L<Locale::Po4a::TransTractor(3pm)|TransTractor> є спільним предком для усіх обробників po4a. Ця дивна назва походить від того факту, що він водночас відповідає за переклад документа (translator) та видобування рядків (extractor).

Формально, він отримує документ для перекладу і файл PO з перекладами на вході і створює два потоки виведених даних: ще один файл PO (який є результатом видобування придатних до перекладу рядків із вхідного документа) та перекладений документ (тієї самої структури, що і вхідний, але із заміною усіх придатних до перекладу рядків на вміст вхідного файла PO). Ось графічне представлення обробки:

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

Ця маленька часточка коду є ядром усієї архітектури po4a. Якщо ви надаєте вхідні дані та ігноруєте вихідний PO, ви отримуєте B<po4a-translate>. Якщо натомість проігнорувати вихідний документ, ви отримаєте B<po4a-updatepo>. B<po4a> використовує перший TransTractor, щоб отримати оновлений вихідний файл POT (без урахування вихідних документів), викликає B<msgmerge -U>, щоб оновити файли PO перекладу на диску, і будує другий TransTractor з цими оновленими файлами PO для оновлення вихідних документів. Коротше кажучи, B<po4a> забезпечує універсальне рішення для оновлення того, що потрібно, за допомогою єдиного файла налаштувань.

B<po4a-gettextize> також використовує два TransTractor-и, але у інший спосіб: вона створює один TransTractor для кожної мови, а потім створює новий файл PO, використовуючи msgid початкового документа як msgid, і msgid перекладеного документа як msgstr. Слід бути дуже уважним і переконатися, що рядки, зіставлені таким чином, дійсно збігаються, як описано у L<po4a-gettextize(1)>.

=head2 Специфічні обробники форматів

Усі обробники форматів po4a реалізовано на основі TransTractor. Деякі з них дуже прості, наприклад Text, Markdown і AsciiDoc. Вони завантажують рядки один за одним за допомогою C<TransTractor::shiftline()>, накопичують дані абзаців або щось інше. Після повного аналізу рядка аналізатор використовує C<TransTractor::translate()>, щоб (1) додати цей рядок до вихідного файла PO та (2) отримати переклад із вхідного файла PO. Потім аналізатор надсилає результат у вихідний файл за допомогою C<TransTractor::pushline()>.

Деякі інші аналізатори є більш складними, оскільки вони покладаються на зовнішній аналізатор для аналізу вхідного документа. Обробники Xml, HTML, SGML і Pod побудовані на основі обробників SAX. Вони оголошують зворотні виклики до таких подій, як «Я знайшов новий заголовок із таким вмістом», щоб оновити вихідний документ і вихідні файли POT відповідно до вхідних даних за допомогою C<TransTractor::translate()> і C<TransTractor::pushline ()>. Синтаксичний аналізатор Yaml подібний, але відрізняється: він серіалізує структуру даних, створену обробником YAML::Tiny. Ось чому модуль Yaml po4a не може оголосити еталонні рядки: розташування кожного рядка у вхідному файлі не зберігається аналізатором, тому ми можемо надати лише "$назва_файла:1" як розташування рядка. SAX-орієнтовані обробники використовують змінні загального рівня та інші трюки, щоб зберегти назву файла та номери рядків посилань.

One specific issue arises from file encodings and BOM markers. Simple parsers can forget about this issue, that is handled by C<TransTractor::read()> (used internally to get the lines of an input document), but the modules relying on an external parser must ensure that all files are read with an appropriate PerlIO decoding layer. The easiest is to open the file yourself, and provide an filehandle or directly the full string to your external parser. Check on C<Pod::read()> and C<Pod::parse()> for an example. The content read by the TransTractor is ignored, but a fresh filehandle is passed to the external parser. The important part is the C<< "<:encoding($charset)" >> mode that is passed to the B<open()> perl function.

=head2 Об'єкти PO

Клас L<Locale::Po4a::Po(3pm)|Po> відповідає за завантаження та використання файлів PO і POT. Загалом, ви можете прочитати файл, додати записи, отримати переклади за допомогою методу B<gettext()>, записати PO до файла. Додаткові функціональні можливості, такі як об’єднання файла PO з файлом POT або перевірка файла, передано до B<msgmerge> і B<msgfmt> відповідно.

=head2 Участь у розробці po4a

Навіть якщо ви ніколи раніше не брали участі в жодному проєкті з відкритим кодом, ласкаво просимо: ми готові допомогти та наставити вас тут. Найкращий супровід po4a можуть надати лише його користувачі. Оскільки нам не вистачає розробників, ми намагаємося зробити проєкт якомога гостиннішим, покращуючи документацію та автоматичні тести, щоб ви були впевнені у своєму внеску до проєкту. Для отримання додаткової інформації зверніться до файла CONTRIBUTING.md.

=head1 Проєкти із відкритим кодом, у яких використовується po4a

Це лише частина списку проєктів, у яких використовується po4a для роботи з документацією. Якщо хочете додати ваш проєкт до списку, просто надішліть ваше прохання електронною поштою (або створіть запит щодо об'єднання у сховищі з кодом).

=over 

=item 

adduser (man): інструмент для керування записами користувачів і груп.

=item 

apt (man, docbook): програма для керування пакунками Debian.

=item 

aptitude (docbook, svg): програма для керування пакунками у терміналі Debian

=item 

L<Сайт F-Droid|https://gitlab.com/fdroid/fdroid-website> (markdown): каталог вільних програм з відкритим кодом для платформи Android.

=item 

L<git|https://github.com/jnavila/git-manpages-l10n> (asciidoc): розподілена система керування версіями для стеження за змінами у початковому коді програм і документації.

=item 

L<Сторінки підручника Linux|https://salsa.debian.org/manpages-l10n-team/manpages-l10n> (man)

Цей проєкт надає інфраструктуру для перекладу багатьох сторінок підручника різними мовами. Результати інтегруються до декількох основних дистрибутивів (Arch Linux, Debian і похідні, Fedora).

=item 

L<Stellarium|https://github.com/Stellarium/stellarium> (HTML): вільний планетарій з відкритим кодом для вашого комп'ютера. po4a використовується для перекладу описів картин зоряного неба.

=item 

L<Jamulus|https://jamulus.io/> (markdown, yaml, HTML): вільний проєкт з відкритим кодом для створення інтернет-джемів у режимі реального часу. Супровід документації на сайті виконується декількома мовами за допомогою po4a.

=item 

Інші пункти для упорядковування: L<https://gitlab.com/fdroid/fdroid-website/> L<https://github.com/fsfe/reuse-docs/pull/61>

=back

=head1 Поширені питання

=head2 Як вимовляти po4a?

Особисто автор вимовляє це як L<pouah|https://en.wiktionary.org/wiki/pouah>, — французький аналог нашого «пхе!» :) Можливо, в автора дивне почуття гумору :)

=head2 Чому окремі скрипти вважаються застарілими?

Справді, B<po4a-updatepo> і B<po4a-translate> застаріли, і перевагу слід надавати B<po4a>. Причина полягає в тому, що хоча B<po4a> можна використовувати як додаткову заміну для цих скриптів, маємо досить багато дубльованого коду. Окремі скрипти містять приблизно 150 рядків коду, тоді як програма B<po4a> складається з 1200 рядків, тому ці рядки виконують додаткові завдання щодо загальних вбудованих функцій. Дублювання коду призводить до помилок, що виникають в обох версіях і потребують двох виправлень. Одним із прикладів такого дублювання є помилка №1022216 у Debian і проблема №442 у GitHub, які мали те саме виправлення, але одне у B<po4a>, а інше — B<po4a-updatepo>.

Зрештою, автор хотів би відмовитися від окремих скриптів і підтримувати лише одну версію цього коду. Звичайно, окремі сценарії більше не покращуватимуться, тому лише B<po4a> отримає нові можливості. Зважаючи на це, вилучення скриптів не є нагальною потребою. Я планую зберігати окремі скрипти якомога довше і принаймні до 2030 року. Якщо ваш проєкт все ще використовуватиме B<po4a-updatepo> та B<po4a-translate> у 2030 році, у вас можуть виникнути проблеми.

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

=head2 Як щодо інших засобів перекладу документації, де використовується gettext?

Їх декілька. Нижче наведено неповний список. Існують плани щодо впровадження у декількох інших програмах.

=over 

=item B<poxml>

Це програма, яку розроблено KDE для роботи із XML DocBook. Наскільки мені відомо, це була перша програма, яка видобувала рядки для перекладу з документації до файлів PO і вставляла ці рядки назад після перекладу.

Ця програма може працювати лише із форматом XML і лише з певним DTD. Мені не дуже подобається робота зі списками у ній, оскільки використання списків за певних умов призводить до створення величезних msgid. Якщо список дуже великий, перекладати його стає дуже складно.

=item B<po-debiandoc>

Цю програму створено Денісом Барбьє (Denis Barbier) як певним чином попередницю модуля SGML po4a, який більшою чи меншою мірою зробив цю програму застарілою. Як можна зрозуміти з назви, програма здатна працювати лише з DTD DebianDoc, який є більшою чи меншою мірою застарілим DTD.

=item B<xml2po.py>

Використовують у команді з документування GIMP з 2004 року. Працює доволі добре, незважаючи на те, що, як зрозуміло з назви, працює лише з файлами XML і потребує спеціально налаштованиих файлів make.

=item B<Sphinx>

У проєкті з документування Sphinx також широко використовують gettext для керування перекладами. На жаль, це працює лише для декількох текстових форматів, rest та markdown, хоча, можливо, це єдиний інструмент, який може керувати усім процесом перекладу.

=back

Основною перевагою po4a над цими програмами є простора додавання додаткових даних (що важко або неможливо зробити у цих програмах) та можливість перетворення даних до стандартного формату gettext.

=head2 РЕЗЮМЕ щодо переваг заснованого на gettext підходу

=over 2

=item 

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

=item 

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

=item 

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

=item 

Для кінцевого користувача нічого не міняється (окрім факту кращого супроводу перекладів). Остаточний файл документації розповсюджується у звичний спосіб.

=item 

Перекладачам не потрібно вивчати новий синтаксис файлів, а їхня улюблена програма для перекладу (наприклад, режим PO у Emacs, Lokalize чи Gtranslator) легко може бути використана для перекладу.

=item 

У gettext передбачено прості способи отримання статистичних даних щодо виконаної роботи, потрібного рецензування та оновлення, а також обсягу роботи, яку ще треба виконати. Приклади можна знайти за цими адресами:

 - https://docs.kde.org/stable5/uk/kdesdk/lokalize/project-view.html
 - http://www.debian.org/intl/l10n/

=back

Втім, не усе так безхмарно. У цього підходу також є недоліки, з якими доводиться мати справу.

=over 2

=item 

Додатки… вони на перший погляд доволі дивні.

=item 

Ви не можете адаптувати перекладений текст згідно до власних уподобань, зокрема поділити абзац на два або з'єднати два абзаци. Втім, у певному сенсі, потреба у таких змінах означає ваду у початковому тексті, — про неї усе одно довелося б повідомити авторові тексту.

=item 

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

Однією з моїх мрій є інтеграція po4a до Gtranslator або Lokalize. При відкритті файла документації програма автоматично б видобувала рядки для перекладу, а перекладений файл і файл po записувала б на диск. Якщо б нам вдалося створити модуль MS Word™ (принаймні модуль для RTF), такою комбінацією модуля з програмами для перекладу могли б користуватися навіть професійні перекладачі.

=back

=head1 ТАКОЖ ПЕРЕГЛЯНЬТЕ

=over 

=item 

Документація до універсального інструмента, яким вам слід користуватися: L<po4a(1)>.

=item 

Документація до окремих скриптів po4a: L<po4a-gettextize(1)>, L<po4a-updatepo(1)>, L<po4a-translate(1)>, L<po4a-normalize(1)>.

=item 

Додаткові допоміжні скрипти: L<msguntypot(1)>, L<po4a-display-man(1)>, L<po4a-display-pod(1)>.

=item 

Обробники для усіх форматів, зокрема для перегляду параметрів, які приймає кожен з них: L<Locale::Po4a::AsciiDoc(3pm)> L<Locale::Po4a::Dia(3pm)>, L<Locale::Po4a::Guide(3pm)>, L<Locale::Po4a::Ini(3pm)>, L<Locale::Po4a::KernelHelp(3pm)>, L<Locale::Po4a::Man(3pm)>, L<Locale::Po4a::RubyDoc(3pm)>, L<Locale::Po4a::Texinfo(3pm)>, L<Locale::Po4a::Text(3pm)>, L<Locale::Po4a::Xhtml(3pm)>, L<Locale::Po4a::Yaml(3pm)>, L<Locale::Po4a::BibTeX(3pm)>, L<Locale::Po4a::Docbook(3pm)>, L<Locale::Po4a::Halibut(3pm)>, L<Locale::Po4a::LaTeX(3pm)>, L<Locale::Po4a::Pod(3pm)>, L<Locale::Po4a::Sgml(3pm)>, L<Locale::Po4a::TeX(3pm)>, L<Locale::Po4a::Wml(3pm)>, L<Locale::Po4a::Xml(3pm)>.

=item 

Реалізація базової інфраструктури: L<Locale::Po4a::TransTractor(3pm)> (частково важливо розуміти організацію коду), L<Locale::Po4a::Chooser(3pm)>, L<Locale::Po4a::Po(3pm)>, L<Locale::Po4a::Common(3pm)>. Будь ласка, ознайомтеся також із файлом F<CONTRIBUTING.md> у дереві початкового коду.

=back

=head1 АВТОРИ

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

