PO4A-GETTEXTIZE.1P

Section: User Contributed Perl Documentation (1)
Updated: 2024-06-17
Index Return to Main Contents

НАЗВА

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)

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

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