PO4A-GETTEXTIZE(1p)

НАЗВА
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 відповідає за перетворення файлів документації на файли PO. Вам достатньо один раз налаштувати ваш проєкт перекладу з po4a і забути про проблеми з перетворенням назавжди.

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

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

ПАРАМЕТРИ

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

-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-го рядка із початкового файла. Звичайно ж, нічого не вийде, якщо структура двох файлів є різною.

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

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

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

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

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

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

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

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

  Підказки і настанови щодо процедури перетворення до формату gettext
Перетворення до формату gettext буде зупинено, щойно буде виявлено розсинхронізацію. Теоретично, можна повторно синхронізувати процес перетворення до формату gettext пізніше у документах, наприклад, за допомогою того самого алгоритму, що і у програмі diff(1). Але ручне втручання все одно буде обов'язковим для встановлення відповідності елементів, які не може бути співвіднесено автоматично, ось чому автоматичну повторну синхронізацію (ще?) не реалізовано.

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

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

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

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

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

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

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

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

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

•   Іноді, ви трапляються випадки, коли програма po4a «з'їдає» частину тексту у початковому файлі або у перекладі. gettextization.failed.po вказує на те, що до певного моменту відповідність зберігалася (аж до абзацу N). Але потім, а потім сталася помилка через те, що програма намагалася встановити відповідність абзацу N+1 у початковому файлі, але встановила її не з абзацом N+1 перекладу, а з абзацом N+2. Таким чином, абзац N+2 у процесі обробки «зник» з файла результатів.

    Така неприємна ситуація трапляється, коли у документі повторюється певний абзац. У цьому випадку, у файлі PO не додається новий запис, а створюється посилання на вже наявний у ньому запис.

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

    Протилежний випадок: той самий абзац, який траплявся у початковому документі двічі, не було перекладено однаково у двох місцях. Результатом є умовне «зникнення» абзацу у перекладі. Просте копіювання вдалішого з перекладів на місце іншого у перекладеному документі має вирішити проблему.

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

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

ТАКОЖ ПЕРЕГЛЯНЬТЕ
po4a(1), po4a-normalize(1), po4a-translate(1), po4a-updatepo(1), po4a(7).

АВТОРИ
 Denis Barbier <barbier@linuxfr.org>
 Nicolas Francois <nicolas.francois@centraliens.net>
 Martin Quinson (mquinson#debian.org)

АВТОРСЬКІ ПРАВА ТА ЛІЦЕНЗУВАННЯ
© SPI, inc., 2002–2020.

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