| PO4A(7) | Інструменти Po4a | PO4A(7) |
po4a — набір інструментів для перекладу документації та інших матеріалів
po4a («PO for anything» або «PO для усього») спрощує супровід перекладу документації з використанням класичних інструментів gettext Основною перевагою po4a є відокремлення придатного до перекладу вмісту документа від його структури.
Це документ є вступом до документації з проєкту po4a. Акцент у ньому зроблено на відомостях для потенційних користувачів, які розглядають можливість використання цього інструмента і цікавляться тим, чому усе реалізовано саме таким чином.
Філософія вільного програмного забезпечення полягає у наданні доступу до технологій усім. Втім, ліцензування не є єдиною причиною: неперекладене вільне програмне забезпечення є недоступним для тих, хто не знає англійської. Для того, щоб зробити його цінним для усіх, слід докласти додаткових зусиль з перекладу.
Усе це добре розуміють у більшості проєктів — зараз усі вже переконані у тому, що перекладати слід усе. Втім, сам переклад є результатом величезних зусиль багатьох осіб, які ускладнюють невеличкі технічні труднощі.
На щастя, саме вільне програмне забезпечення має досить якісний інструментарій для перекладу, дякуючи чудовому набору інструментів gettext. У нас є інструменти для видобування рядків для перекладу з програми і представлення їх у стандартизованому форматі (який називають файлами PO або каталогами перекладу). З'явилася ціла екосистема інструментів, які допомагають перекладачам перекладати ці файли PO. Результат перекладу використовується gettext під час роботи програми для показу кінцевим користувачам перекладених повідомлень.
Якщо ж говорити про документацію, маємо дещо прикру картину. Спершу може здатися, що перекладати документацію простіше за саму програму, оскільки достатньо скопіювати файл документації і почати перекладати його вміст. Втім, якщо до початкового документа буде внесено зміни, стеження за ними може перетворитися на суцільний жах для перекладачів. Виконання цього завдання вручну є неприємною справою, у якій можна дуже просто помилитися.
Застарілі ж переклади часто є більшою проблемою, ніж неперекладена документація. Кінцевого користувача можна ввести в оману документацією, у якій описано поведінку застарілої версії програми. Крім того, користувачі перекладеної версії не можуть безпосередньо взаємодіяти із супровідниками, оскільки мають проблеми у спілкування англійською. До цього додається і те, що супровідник не може виправити проблему, оскільки не знає усі мови, якими перекладено документацію. Ці складнощі, часто викликані неналежним інструментарієм перекладу, можуть відлякати потенційних перекладачів, що робить ситуацію ще проблематичнішою.
Метою проєкту po4a є спрощення роботи для перекладачів документації. Зокрема, цей проєкт робить переклади документації придатними до супроводу.
Ідея полягає у повторному використанні і адаптації підходу gettext. Так само, як і з gettext для програм, текстові фрагменти видобуваються з початкових файлів і надаються перекладачам як каталоги перекладу PO. Перекладачі можуть скористатися класичними засобами gettext для стеження за виконанням завдань, співпраці та організації команд. Далі, po4a вставляє переклади безпосередньо до структури документації з метою створення перекладених початкових файлів, які можна обробляти і поширювати у той самий спосіб, у який обробляються і поширюються файли англійською. У документі-результаті усі неперекладені абзаци лишатимуться написаними англійською, отже кінцеві користувачі ніколи не побачать застарілих перекладів у документації.
Це автоматизує більшу частину нудної роботи із супроводу перекладу. Виявлення абзаців, які потребують оновлення стає дуже простим, а процес повністю автоматизується, якщо елементи просто перевпорядковуються без подальшого внесення змін. Також можна скористатися специфічними перевірками для зменшення ймовірності помилок у форматуванні, які можуть призвести до неможливості обробки документа.
Будь ласка, також ознайомтеся із розділом Поширені питання у цьому документі, щоб дізнатися більше про переваги і недоліки цього підходу.
У поточній версії цей підхід успішно реалізовано для декількох типів документів із текстовим форматуванням:
У модулі Locale::Po4a::Man(3pm) також передбачена підтримка формату mdoc, який використовується у сторінках підручника BSD (їх також доволі часто використовують у Linux).
У поточній версії передбачено підтримку лише DebianDoc і DocBook DTD, але додавання підтримки нових форматі є дуже простим. po4a можна навіть використовувати для невідомих DTD SGML без зміни коду, якщо надати потрібну інформацію за допомогою командного рядка. Див. Locale::Po4a::Sgml(3pm), щоб дізнатися більше.
Модуль Locale::Po4a::LaTeX(3pm) було перевірено на документації до Python, книзі і декількох презентаціях.
Цей формат є типовим для генераторів статичних сайтів, файлів README та інших систем документації. Див. Locale::Po4a::Text(3pm), щоб дізнатися більше.
У поточній версії po4a передбачено підтримку DocBook DTD (докладніше про це див. Locale::Po4a::Docbook(3pm)) та XHTML.
Історично, po4a побудовано на основі чотирьох скриптів, кожен з яких виконує певне власне завдання. po4a-gettextize(1) допомагає ініціювати переклади та, якщо потрібно, перетворити наявні проєкти перекладу до схеми po4a. po4a-updatepo(1) відображає зміни у початковій документації до відповідних файлів PO. po4a-translate(1) збирає файл перекладу на основі початкового файла та відповідного файла PO. Крім того, є ще po4a-normalize(1) — програма, яка здебільшого корисна для діагностики обробників po4a, оскільки вона створює неперекладендий документ з початкового файла. За результатами простіше знайти помилки, які є наслідком процедури обробки.
Для більшості проєктів достатньо можливостей po4a-updatepo(1) і po4a-translate(1), але керувати цими скриптами складно, неправильні параметри можуть призвести до помилок. Якщо документацію, яку слід перекласти, поділено на декілька початкових файлів, підтримання актуальності файлів PO і правильне збирання документації стає складним завданням. Щоб усунути проблеми, було створено універсальний інструмент — po4a(1). Ця програма працює із файлом налаштувань, який описує структуру проєкту перекладу: розташування файлів PO, список файлів, які слід перекласти та параметри, якими слід скористатися, а також повністю автоматизує процес. Коли ви викликаєте po4a(1), програма одразу оновлює файли PO і повторно створює файли перекладу, які цього потребують. Якщо файл є актуальним, po4a(1) не вносить до нього змін.
У решті цього розділу подано огляд користування інтерфейсом до скриптів po4a. Більшість користувачів, напевне, віддасть перевагу використанню універсального інструмента, який описано у документації до po4a(1).
На наведеній нижче схемі подано огляд того, як може бути використано кожен зі скриптів. На схемі основний.документ — приклад назви документації, яку слід перекласти; XX.документ — відповідний перекладений документ мовою XX, а doc.XX.po — каталог перекладу для цього документа мовою XX. Автори документації, здебільшого мають перейматися файлом основний.документ (це може бути сторінка підручника (man), документ XML, файл asciidoc або подібний документ); перекладачі, здебільшого, працюють із файлом PO, а кінцеві користувачі бачать лише файл XX.документ.
основний.документ
|
V
+<-----<----+<-----<-----<--------+------->-------->-------+
: | | :
{переклад} | { оновлення основний.документ } :
: | | :
XX.документ | V V
(необов'язковий) | основний.документ ->------>---->+
: | (новий) |
V V | |
[po4a-gettextize] документ.XX.po>+ | |
| (старий) | | |
| ^ V V |
| | [po4a-updatepo] |
V | | V
переклад.pot ^ V |
| | документ.XX.po |
| | (неточний) |
{ переклад } | | |
| ^ V V
| | {редагування вручну} |
| | | |
V | V V
документ.XX.po --->---->+<---<-документ.XX.po додаток основний.документ
(початковий) (актуальний) (необов'язковий)(актуальний)
: | | |
: V | |
+----->----->----->------> + | |
| | |
V V V
+------>-----+------<------+
|
V
[po4a-translate]
|
V
XX.документ
(актуальний)
Ця схема є складною, але на практиці після створення і налаштовування проєкту використовується лише її права частина (там, де ви працюєте з po4a-updatepo(1) і po4a-translate(1)).
У лівій частині показано як можна скористатися po4a-gettextize(1) для перетворення наявного проєкту перекладу до інфраструктури po4a. Цей скрипт працює із початковим документом та його перекладеним аналогом і намагається зібрати відповідний файл PO. Таке перетворення вручну є доволі марудним (подробиці наведено у документації до po4a-gettextize(1)), але таке перетворення потрібне лише один раз — для перетворення наявних перекладів. Якщо у вас немає ніяких перекладів для перетворення, ви можете забути про це і зосередитися на правій частині схеми.
У верхній частині праворуч зображено роботу автора початкового тексту (оновлення документації). У середній частині праворуч зображено послідовність автоматичних дій po4a-updatepo(1). Новий тестовий матеріал видобувається з документа і порівнюється із наявним перекладом. Виявляються частини, які не змінилися, — для них використовується наявний переклад. Частини, які зазнали часткових змін також пов'язуються із попереднім перекладом, але із особливою позначкою, яка вказує на те, що переклад має бути оновлено. Новий або значно змінений матеріал лишається неперекладеним.
Далі, пункт редагування вручну показує роботу перекладачів, які вносять зміни до файлів PO, перекладаючи усі початкові рядки або абзаци. Переклад можна здійснювати або за допомогою спеціалізованого редактора, зокрема Редактора перекладів GNOME або Lokalize з KDE або poedit, чи інтегрувати до платформи інтернет-перекладу, зокрема weblate або pootle. Результатом перекладу є набір файлів PO, по одному на кожну мову перекладу. Докладніший опис можна знайти у документації до gettext.
У нижній частині схеми показано, як po4a-translate(1) створює перекладений початкових документ на основі документа основний.документ та каталогу перекладу документ.XX.po, який було оновлено перекладачами. Програма використовує структуру початкового документа, але замінює початковий вміст на перекладені блоки. Якщо потрібно, може бути використано додаток для вставляння певного додаткового тексту до перекладу. Такі додатки часто використовуються для додавання імені перекладача до остаточного документа. Подробиці наведено нижче.
Як ми вже зауважували раніше, програма po4a(1) поєднує можливості окремих скриптів, оновлюючи файли PO і перекладений документ за один прохід. Базова логіка обробки лишається незмінною.
Якщо ви використовуєте po4a(1), ніякого специфічного кроку для того, щоб розпочати переклад, не буде. Вам просто слід вказати список мов у файлі налаштувань, і файли PO, яких не вистачає, буде створено автоматично. Природно, перекладач має надати переклади для усіх фрагментів тексту, які використано у документі. po4a(1) також створює файл POT, який є файлом шаблона перекладів. Потенційні перекладачі можуть перекладати ваш проєкт новою мовою, перейменувавши цей файл і надавши його переклад рідною мовою.
Якщо ви надаєте перевагу використанню окремих скриптів, для створення файла POT вам слід скористатися po4a-gettextize(1), як це вказано. Отриманий файл можна потім скопіювати як XX.po для започаткування нового перекладу.
$ po4a-gettextize --format <формат> --master <основний.документ> --po <переклад.pot>
На вході використовується основний документ, а файл POT є результатом цього процесу.
Скриптом, яким слід для цього скористатися є po4a-updatepo(1) (будь ласка, зверніться до відповідної сторінки документації, щоб дізнатися більше):
$ po4a-updatepo --format <формат> --master <новий_основний.документ> --p0 <старий_документ.XX.po>
На вході використовується основний документ, а файл PO оновлюється: його вміст використовується як вхідні дані і, одночасно, є результатом обробки.
Після завершення перекладу вам потрібна буде перекладена документація для надання її користувачам разом із оригінальною. Для отримання такої документації скористайтеся програмою po4a-translate(1) ось так:
$ po4a-translate --format <формат> --master <основний_документ> --po <документ.XX.po> --localized <документ_XX>
На вході використовується основний документ і файли PO, результатом процесу є перекладений документ.
Додавання нового тексту до перекладу є, ймовірно, єдиною дією, яку простіше виконувати, якщо ви перекладаєте файли вручну :). Додавання може знадобитися, якщо вам потрібно додати до перекладеного документа додатковий розділ, який не відповідає жодного з розділів у початковому документі. Класичним випадком є додавання подяк команді перекладачів та вставляння нотатки щодо того, як повідомляти про вади, які пов'язано із перекладом.
У інфраструктурі po4a вам слід вказати файли додатків, які концептуально можна розглядати як латки, які застосовуються до локалізованого документа після обробки. Кожен додаток має бути надано як окремий файл, формат якого, втім, значно відрізняється від формату класичних латок. Перший його рядок є рядком заголовка, який визначає позицію вставлення додатка (із, на жаль, доволі складним синтаксисом — див. нижче), а решту файла буде буквально вставлено у визначеній позиції.
Рядок заголовка має розпочинатися з рядка PO4A-HEADER:, за яким має бути вказано список відокремлених крапкою з комою полів ключ=значення.
Наприклад, у наведеному нижче заголовку оголошується додаток, який має бути вставлено наприкінці перекладу.
PO4A-HEADER: mode=eof
Все стає складнішим, якщо ви хочете додати додаткові дані всередину документа. У наведеному нижче заголовку оголошується додаток, який має бути вставлено після розділу XML, який у перекладі містить рядок "Про цей документ".
PO4A-HEADER: position=Про цей документ; mode=after; endboundary=</section>
На практиці, при спробі застосувати додаток po4a шукає перший рядок, який відповідає аргументу ключа "position" (аргументом може бути формальний вираз). Не забудьте, що po4a обробляє перекладений документ. Документацію перекладено українською, але ваш рядок може виглядати так, як вказано нижче, якщо додаток застосовується до французького перекладу документа.
PO4A-HEADER: position=À propos de ce document; mode=after; endboundary=</section>
Щойно аргумент ключа "position" буде знайдено у документі призначення, po4a виконає пошук наступного рядка після "position", який відповідає аргументу, заданому "endboundary". Додаток буде додано одразу після цього рядка (оскільки нами надано endboundary — межу поточного розділу).
Точно такого самого ефекту можна досягти із наведеним нижче заголовком, який є еквівалентним до вже використаного:
PO4A-HEADER: position=Про цей документ; mode=after; beginboundary=<section>
Тут po4a шукає перший рядок, який відповідає "<section"> після рядка "Про цей документ" у перекладі, і вставляє додаток до цього рядка, оскільки вказано beginboundary, тобто початкову межу наступного розділу. Отже, цей рядок заголовка вимагає від програми вставити додаток після розділу, що містить рядок "Про цей документ", і вказує po4a, що розділ починається з рядка, що містить теґ "<section">. Це еквівалентно до попереднього прикладу, оскільки насправді нам потрібно вставити цей додаток або після "/section">, або перед "<section">.
Ви також можете встановити режим вставляння у значення "before", використовуючи подібну семантику "mode=before" з "endboundary" призведе до вставляння додатка одразу після відповідної межі, який є останнім потенційним обмежувальним рядком перед "position". Поєднання "mode=before" із "beginboundary" призведе до вставляння додатка одразу перед відповідною межею, яка є останнім потенційним обмежувальним рядком перед "position".
Режим | Тип межі | Використана межа | Точка вставляння відносно межі ========|===============|==========================|======================================= 'before'| 'endboundary' | остання перед 'position' | Одразу після вибраної межі 'before'|'beginboundary'| остання перед 'position' | Одразу перед вибраною межею 'after' | 'endboundary' | перша після 'position' | Одразу після вибраної межі 'after' |'beginboundary'| перша після 'position' | Одразу перед вибраною межею 'eof' | (немає) | н/д | Кінець файла
Підказки і настанови щодо додатків
PO4A-HEADER: position=Про цей документ; mode=after; beginboundary=<section>
PO4A-HEADER: position=Про цей документ ; mode=after; beginboundary=<section>
Приклади додатків
.SH "AUTHORS"
Вам слід вибрати двокроковий підхід встановленням значення mode=after. Далі, вам слід звузити пошук до рядка після AUTHORS за допомогою параметра формального виразу position. Далі, вам потрібно встановити відповідність початку нового розділу (тобто, ^\.SH) за допомогою параметра формального виразу beginboundary. Тобто, слід зробити так:
PO4A-HEADER:mode=after;position=AUTHORS;beginboundary=\.SH
PO4A-HEADER:mode=after;position=Copyright Big Dude, 2004;beginboundary=^
PO4A-HEADER:mode=after;position=Про цей документ;beginboundary=FakePo4aBoundary
Докладніший приклад
Початковий документ (у форматуванні 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
Це працює, оскільки наступний рядок відповідника beginboundary /^=head1/ після розділу «NAME» (перекладеного як «ІМ'Я» українською) є розділ зі списком авторів. Отже, додаток буде розташовано між вказаними розділами. Зауважте, що якщо між розділами NAME і AUTHOR згодом буде додано ще якийсь розділ, po4a помилково додасть додаток перед новим розділом.
Щоб уникнути цього, ви можете досягти результату у інший спосіб за допомогою mode=before:
PO4A-HEADER:mode=before;position=^=head1 АВТОР
У цій главі наведено короткий огляд нутрощів po4a, який надасть вам впевненості, якщо ви захочете допомогти нам із супроводом та розвитком комплекту програм. Цей огляд також може допомогти вам зрозуміти, чому програма працює не так, як ви того сподівалися, та як усунути вашу проблему.
Архітектура po4a є об'єктно-орієнтованою. Клас Locale::Po4a::TransTractor(3pm) є спільним предком для усіх обробників po4a. Ця дивна назва походить від того факту, що він водночас відповідає за переклад документа (translator) та видобування рядків (extractor).
Формально, він отримує документ для перекладу і файл PO з перекладами на вході і створює два потоки виведених даних: ще один файл PO (який є результатом видобування придатних до перекладу рядків із вхідного документа) та перекладений документ (тієї самої структури, що і вхідний, але із заміною усіх придатних до перекладу рядків на вміст вхідного файла PO). Ось графічне представлення обробки:
Вхідний документ --\ /---> Вихідний документ
\ TransTractor:: / (перекладений)
+-->-- parse() --------+
/ \
Вхідний PO --------/ \---> Вихідний PO
(видобутий)
Ця маленька часточка коду є ядром усієї архітектури po4a. Якщо викинути вхідний файл PO і вихідний документ, ми отримуємо po4a-gettextize. Якщо надати вхідний PO і відкинути вихідний PO, отримуємо po4a-translate. po4a двічі викликає TransTractor і між цими викликами викликає msgmerge -U для забезпечення обробки даних у один прохід за допомогою одного файла налаштувань. Докладніший опис можна знайти на сторінці Locale::Po4a::TransTractor(3pm).
Це лише частина списку проєктів, у яких використовується po4a для роботи з документацією. Якщо хочете додати ваш проєкт до списку, просто надішліть ваше прохання електронною поштою (або створіть запит щодо об'єднання у сховищі з кодом).
Цей проєкт надає інфраструктуру для перекладу багатьох сторінок підручника різними мовами. Результати інтегруються до декількох основних дистрибутивів (Arch Linux, Debian і похідні, Fedora).
Особисто автор вимовляє це як pouah <https://en.wiktionary.org/wiki/pouah>, — французький аналог нашого «пхе!» :) Можливо, в автора дивне почуття гумору :)
Наскільки мені відомо, є лише два інших комплекти програм:
Ця програма може працювати лише із форматом XML і лише з певним DTD. Мені не дуже подобається робота зі списками у ній, оскільки використання списків за певних умов призводить до створення величезних msgid. Якщо список дуже великий, перекладати його стає дуже складно.
Основною перевагою po4a над цими програмами є простора додавання додаткових даних (що важко або неможливо зробити у цих програмах) та можливість перетворення даних до стандартного формату gettext.
- https://docs.kde.org/stable5/uk/kdesdk/lokalize/project-view.html
- http://www.debian.org/intl/l10n/
Втім, не усе так безхмарно. У цього підходу теж є недоліки, з якими доводиться мати справу.
Однією з моїх мрій є інтеграція po4a до Gtranslator або Lokalize. При відкритті файла документації програма автоматично б видобувала рядки для перекладу, а перекладений файл і файл po записувала б на диск. Якщо б нам вдалося створити модуль MS Word™ (принаймні модуль для RTF), такою комбінацією модуля з програмами для перекладу могли б користуватися навіть професійні перекладачі.
Denis Barbier <barbier,linuxfr.org> Martin Quinson (mquinson#debian.org)
| 2020-12-09 | Інструменти Po4a |