НАЗВА

       po4a-gettextize — програма для перетворення початкового файла (і його перекладу) на файл
       PO

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

       po4a-gettextize -f формат -m основний.документ -l XX.документ -p XX.po

       (XX.po вказує на результат, усі інші вказують на вхідні дані)

ОПИС

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

       Скрипт po4a-gettextize допоможе вам перетворити ваші наявні переклади до формату,
       придатного до робочої процедури на основі po4a. Таке перетворення до формату po4a для
       збереження наявного перекладу достатньо зробити один раз. Його не доведеться робити
       регулярно після перетворення вашого проєкту. Цю марудну процедуру докладно описано у
       розділі «Перетворення виконаного вручну перекладу до формату po4a» нижче.

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

       Якщо у основному документі є символи, як не є символами ASCII, новостворений файл PO буде
       записано у кодуванні UTF-8. У інших випадках (якщо основний документ містить лише символи
       ASCII), створений файл PO використовуватиме кодування перекладеного вхідного документа.

ПАРАМЕТРИ

       -f, --format
           Формат документації, з якою ви працюватимете. Скористайтеся параметром --help-format,
           щоб ознайомитися зі списком доступних форматів.

       -m, --master
           Файл, який містить основний документ для перекладу. Ви можете скористатися цим
           параметром декілька разів, якщо ви хочете перетворити на формат gettext декілька
           документів одночасно.

       -M, --master-charset
           Кодування символів файла, який містить дані документа, який слід перекласти.

       -l, --localized
           Файл, який містить дані перекладеного документа. Якщо було вказано декілька основних
           файлів, вам варто вказати декілька перекладених файлів, додавши їх до списку
           декількома використаннями цього параметра у одній команді.

       -L, --localized-charset
           Кодування символів файла, який містить дані перекладеного документа.

       -p, --po
           Файл, до якого слід записати каталог повідомлень. Якщо файл не вказано, каталог
           повідомлень буде записано до стандартного виведення (stdout).

       -o, --option
           Додаткові параметри, які слід передати додатку форматування. Докладніші відомості щодо
           параметрів кожного з додатків можна знайти у документації до відповідного додатка.
           Наприклад, ви можете передати «-o tablecells» до обробника AsciiDoc, а обробнику
           звичайного тексту можна передати «-o tabs=split».

       -h, --help
           Показати коротке довідкове повідомлення.

       --help-format
           Список форматів документації, відомих po4a.

       -k --keep-temps
           Зберегти тимчасові основний файл POT і локалізований файл, які зібрано до об'єднання.
           Може бути корисним для визначення причини розсинхронізації, яка призвела до проблем із
           перетворенням у формат gettext.

       -V, --version
           Вивести дані щодо версії скрипту і завершити роботу.

       -v, --verbose
           Збільшити докладність повідомлень програми.

       -d, --debug
           Вивести деякі діагностичні відомості.

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

       --copyright-holder рядок
           Встановити запис авторських прав у заголовку POTr. Типовим значенням є «Free Software
           Foundation, Inc.»

       --package-name рядок
           Встановити назву пакунка для заголовка POT. Типовою є назва пакунка «PACKAGE».

       --package-version рядок
           Встановити версію пакунка для заголовка POT. Типовим є запис «VERSION».

   Перетворення виконаного вручну перекладу до формату po4a
       po4a-gettextize намагається виконати видобування перекладів з перекладених документів і
       зберегти як записи msgstr їх до записаного файла PO. Майте на увазі, що можливості із
       розбору тексту у цьому процесі доволі обмежено: програма просто вважатиме N-ий рядок із
       перекладеного файла перекладом N-го рядка із початкового файла. Звичайно ж, нічого не
       вийде, якщо структура двох файлів є різною.

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

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

           Оригінал         Переклад

         глава                глава
           абзац                абзац
           абзац                абзац
           абзац              глава
         глава                абзац
           абзац                абзац

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

       If you are lucky enough to have a perfect match in the file structures out of the box,
       building a correct PO file is a matter of seconds. Otherwise, you will soon understand why
       this process has such an ugly name :) Even so, gettextization often remains faster than
       translating everything again. I gettextized the French translation of the whole Perl
       documentation in one day despite the many synchronization issues. Given the amount of text
       (2MB of original text), restarting the translation without first salvaging the old
       translations would have required several months of work. In addition, this grunt work is
       the price to pay to get the comfort of po4a. Once converted, the synchronization between
       master documents and translations will always be fully automatic.

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

       Підказки і настанови щодо процедури перетворення до формату gettext

       Коли таке трапляється, усе зводиться до повторного вирівнювання структури файлів вручну.
       po4a-gettextize доволі докладно повідомляє про те, що не так. Програма повідомить вам про
       рядки, які не збігаються, їхнє розташування у тексті та тип кожного з них. Більше того,
       дані PO, які буде отримано на момент помилки, буде записано до файла
       gettextization.failed.po для подальшого вивчення.

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

       •   Вилучіть усі зайві елементи перекладу, зокрема розділ із подяками перекладачам. Їх
           слід додати окремо до po4a за допомогою додатків (див. po4a(7)).

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

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

       •   Вам, ймовірно, слід повідомити автора початкового документа про будь-які зміни у
           структурі перекладу, які варто зробити. Якщо у оригіналі документа були вади, вам слід
           повідомити про них авторові. Виправлення цих вад у вашому перекладі буде корисним лише
           частині спільноти. Більше того, таке виправлення неможливе, якщо використовується
           система po4a ;) Втім, вам, ймовірно, слід зачекати до завершення перетворення до
           формату po4a, перш ніж вносити зміни до початкових файлів.

       •   Іноді вміст абзаців збігається, але їхні типи є різними. Шлях виправлення цієї помилки
           залежить від формату документа. У POD і man поширеною причиною подібних проблем є те,
           що один з рядків починається із пробілу, а інший — ні. У таких форматах абзац із
           пробілом не можна переносити за рядками, отже він стає абзацом іншого типу. Достатньо
           вилучити пробіл, і усе запрацює. Також причиною може бути друкарська помилку у назві
           теґу у XML.

           Далі, у POD два абзаци може бути об'єднано, якщо рядок, який їх відокремлює містить
           пробіли, або якщо між рядком =item і вмістом запису немає порожнього рядка.

       •   Іноді між файлами виникає розсинхронізація, і переклад поєднується із помилковим
           початковим рядком. Це означає, що під час перетворення виникли якісь проблеми ще до
           розсинхронізованого рядка. Знайдіть у створеному gettextization.failed.po місце, де
           починається розсинхронізація, і виправте її.

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

   Рецензування файлів, які створено po4a-gettextize
       Усі файли, які створено po4a-gettextize має бути переглянуто вручну, навіть якщо роботу
       скрипту буде завершено без помилок. Вам слід передивитися увесь файл PO, переконавшись, що
       msgid і msgstr є насправді відповідними. Необхідності у ідеальній правильності перекладу
       поки немає, оскільки усі записи буде все одно позначено як неточні. Вам слід лише виявити
       явні невідповідності, оскільки погана відповідність перекладів зашкодить на наступних
       кроках спроби зберегти їх.

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

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

   Перший запуск po4a
       Найпростішим способом налаштовування po4a є створення файла налаштувань po4a.conf і
       використання інтегрованої програми po4a (po4a-updatepo і po4a-translate вважаються
       застарілими). Будь ласка, ознайомтеся із розділом «ФАЙЛ НАЛАШТУВАНЬ» документації до
       po4a(1), щоб дізнатися більше.

       Під час першого запуску po4a поточну версію основних документів буде використано для
       оновлення файлів PO, що містять застарілі переклади, які було збережено шляхом
       перетворення до формату gettext. На це можна знадобитися доволі багато часу, оскільки
       багато msgid з перетворених до формату gettext даних не точно відповідатимуть елементам
       файла POT, який побудовано на основі поточних основних файлів. Це примушує gettext до
       пошуку найближчого відповідника з використанням складного алгоритму пошуку близьких за
       вмістом рядків. Наприклад, перший запуск програми для перекладу документації Perl
       французькою мовою (файл PO розміром 5,5 МБ) тривав 48 годин (так, два дні), а наступні
       запускати триватимуть лише секунди.

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

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

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

       po4a(1), po4a-normalize(1), po4a-translate(1), po4a-updatepo(1), po4a(7).

АВТОРИ

        Denis Barbier <barbier@linuxfr.org>
        Nicolas François <nicolas.francois@centraliens.net>
        Martin Quinson (mquinson#debian.org)

АВТОРСЬКІ ПРАВА ТА ЛІЦЕНЗУВАННЯ

       © SPI, inc., 2002–2023.

       Ця програма є вільним програмним забезпеченням; ви можете поширювати її і/або вносити до
       неї зміни за умов дотримання GPL версії 2.0 або пізнішої (див. файл COPYING).