| PO4A(1p) | Інструменти Po4a | PO4A(1p) |
po4a — оновлення файлів PO і перекладених документів у один прохід
po4a [параметри] файл_налаштувань
po4a («PO for anything» або «PO для усього») спрощує супровід перекладу документації з використанням класичних інструментів gettext. Основною перевагою po4a є відокремлення придатного до перекладу вмісту документа від його структури. Будь ласка, зверніться до сторінки po4a(7), щоб ознайомитися зі вступними зауваженнями щодо цього проєкту.
Під час виконання po4a обробляє усі файли документації, вказані у файлі налаштувань програми. Програма оновлює файли PO (файли, які містять переклад) відповідно до усіх змін у документації і створює перекладені документи, вставивши вміст перекладу (який зберігається у файлах PO) до структури початкових основних документів.
Спочатку, у файлах PO містяться лише рядки з початкової документації, які слід перекласти. Файли у цьому форматі надають змогу перекладачам вручну перекласти кожен із абзаців документації, які видобуто po4a. Якщо до документації після того, як її буде перекладено, буде внесено зміни, po4a позначить відповідні переклади у файлі PO як «неточні» з метою наступного рецензування цих перекладів перекладачами. Крім того, перекладачі можуть надавати так звані «додатки», додаткові дані, у яких, наприклад, вказано, ким виконано переклад і як надсилати повідомлення про вади.
основні документи---+---->-------->---------+
(документування) | |
V (виконання po4a) >-----+--> переклади
| | |
наявні файли PO -->-> оновлені файли PO >-+ |
^ | |
| V |
+----------<---------<-------+ ^
(процес перекладу підручника) |
|
додаток --->--------------------------------------+
Робочий процес у po4a є асинхронним, таким, що пасує проєктам із відкритим кодом. Автори документації створюють основні документи за власним графіком. Перекладачі рецензують і оновлюють переклади у файлах PO. Супровідники перезапускають po4a, якщо це потрібно, для відтворення будь-яких змін у початковій документації у файлах PO і створення оновлених перекладів документації шляхом вставлення найсвіжіших перекладів до найсвіжішої структури документації.
Типово, програма створюватиме заданий перекладений документ, якщо перекладено принаймні 80% вмісту. Неперекладений текст зберігається початковою мовою. Таким чином, у створеній документації поєднуються мови, якщо переклад не завершено. ви можете змінити порогове значення у 80%, за допомогою параметра --keep, який описано нижче. Відкидання перекладів, які виконано не на 100% може знизити мотивацію перекладачів, роботу яких ніколи не буде показано користувачам, але надання «перекладів», які є фрагментарними, може призвести до проблем у кінцевих користувачів.
Ймовірно, не варто зберігати файли перекладеної документації у системі керування версіями, оскільки їхнє створення відбувається автоматично. Вартими уваги є лише файли PO, які містять результати важкої праці ваших колег-перекладачів. Крім того, багато кому простіше взаємодіяти з перекладачами за допомогою інтернет-платформи, подібної до weblate, але це, звичайно ж, справа уподобань.
Припустімо, що ви є супровідником програми із назвою foo, яка має сторінку підручника man/foo.1, написану англійською мовою (базова мова у більшості проєктів із відкритим кодом, але po4a можна скористатися для перекладу з будь-якої мови будь-якою мовою). Колись хтось вже виконав переклад німецькою, який має назву man/foo.de.1, а потім припинив участь у перекладі. Це стало проблемою, коли ви отримали звіт про ваду, яка полягає у тому, що у документації містяться помилкові дані, які слід виправити в усіх перекладах, але ви не дуже добре знаєте німецьку, тому можете виправити оригінал, але не переклад. Крім того, інший учасник хоче взяти участь у перекладі японською, мовою, якої ви також не знаєте.
Час перетворити документацію до формату po4a, щоб усунути ці жахи супроводу документації. Ви хочете оновити документацію потрібним чином, хочете спростити роботу колегам-перекладачам і хочете бути певні, що користувачі не бачитимуть застарілої, а отже, помилкової документації.
Перетворення відбувається у два кроки: налаштовування інфраструктури po4a і перетворення попереднього перекладу німецькою з метою збереження результатів раніше виконаної роботи. Другу частину роботи виконає po4a-gettextize, як це описано нижче. Як зазначено у документації до po4a-gettextize(1), процес перетворення нечасто буває повністю автоматичним, але після його завершення, файл de.po, що містить переклад німецькою, може бути інтегровано до вашого робочого процесу po4a.
po4a-gettextize --format man --master foo.1 --localized foo.de.1 --po de.po
Налаштуймо po4a. Якщо використати відповідну структуру каталогів і файлів, ваш файл налаштувань може бути доволі простим:
[po_directory] man/po4a/ [type: man] man/foo.1 $lang:man/translated/foo.$lang.1
Тут вказано, що усі файли PO (файли, що містять роботу перекладачів) зберігаються у каталозі man/po4a/, і у проєкт є лише один основний файл, man/foo.1. Якщо б у вас було декілька основних файлів, вам слід було б дописати декілька рядків, які були б подібні до другого рядка. Кожен такий рядок визначає, куди записувати відповідні файли перекладу. Тут, перекладом man/foo.1 є man/translated/foo.de.1.
Останнім для завершення налаштовування po4a ми маємо вказати файл POT, який міститиме шаблонний матеріал, яким слід користуватися для того, щоб розпочати новий переклад. Просто створіть порожній файл із суфіксом назви .pot у вказаному po_directory (наприклад man/po4a/foo.pot), і po4a заповнить його відповідними даними.
Ось короткий перелік файлів для цієї схеми роботи:
├── man/ │ ├── foo.1 <- Початкова сторінка підручника англійською. │ ├── po4a/ │ │ ├── de.po <- Переклад німецькою у форматі PO після перетворення. │ │ └── foo.pot <- Шаблон POT для майбутніх перекладів (спочатку порожній) │ └── translated/ <- Каталог, у якому буде створено переклади └── po4a.cfg <- Файл налаштувань.
Після завершення налаштовування виконання po4a призведе до обробки документації, оновлення файла шаблонів POT, використання його для оновлення файлів перекладу PO і використання перекладів для оновлення файлів перекладу документації. Усе однією командою:
po4a --verbose po4a.cfg
Ось і все. Тепер po4a повністю налаштовано. Після виправлення вашої помилки у man/foo.1 помилковий абзац у перекладі німецькою буде замінено виправленим текстом англійською. Суміш мов не є оптимальною, але це єдиний спосіб усувати помилки у перекладах мовами, які ви навіть не розумієте, та надання користувачам даних, які не є помилковими. Крім того, за допомогою відповідного файла PO також набагато простіше оновлювати переклад німецькою, тому суміш мов у перекладі не триматиметься аж надто довго. Нарешті, коли перекладач японською надасть вам перекладений файл jp.po, просто запишіть його як man/po4a/po/. Перекладена сторінка з'явиться як man/translated/foo.jp.1 (якщо переклад є достатньо повним), коли ви знову запустите po4a.
Типова поведінка (якщо не вказано --force) така:
Крім того, перекладений документ буде повторно створено, лише якщо його основний документ, файл PO, один із додатків або файл налаштувань виявиться актуальнішим. Щоб запобігти спробам повторного створення перекладених документів, які не проходять перевірки на порогове значення перекладів (див. --keep), буде створено файл із суфіксом назви .po4a-stamp (див. --stamp).
Якщо до основного документа включаються додаткові файли, вам слід скористатися прапорцем --force, інакше час внесення змін до цих включених файлів не буде враховано.
Файли PO завжди повторно створюються на основі файла POT за допомогою msgmerge -U.
Зауваження: цей параметр вмикає лише створення файлів .po4a-stamp. Програма завжди використовуватиме файли штампів, якщо вони існують, їх буде вилучено, лише якщо вказано параметр --rm-translations або переклад файла буде завершено.
УВАГА: цей прапорець змінює поведінку po4a у доволі критичний спосіб: файли перекладу не оновлюватимуться, аж доки не буде поліпшено переклад. Використовуйте цей прапорець, лише якщо ви надаєте перевагу розповсюдженню застарілої перекладеної документації перед розповсюдженням точної, але не перекладеної документації.
Якщо вказано одразу destdir і srcdir, пошук вхідних файлів відбуватиметься у таких категоріях, у вказаному порядку: destdir, поточний каталог і srcdir. Файли результатів записуються до destdir, якщо вказано, або до поточного каталогу.
Так історично склалося, що комплект програм gettext виконує переформатування файлів po так, щоб рядки було перенесено на 77-й позиції, з косметичних міркувань. За допомогою цього параметра можна встановити відповідну поведінку po4a. Якщо встановлено числове значення, po4a переноситиме рядки у файлі po після вказаної позиції і після символів розриву рядка у самих рядках. Якщо встановити значення newlines, po4a розриватиме рядки у msgid і msgstr лише після символів нового рядка у вмісті. Якщо встановити значення no, po4a не переноситиме рядки у файлі po взагалі. Перенесення рядків у коментарях виконується завжди інструментами gettext, які програма використовує на внутрішньому рівні.
Зауважте, що цей параметр не стосується того, яким чином переноситимуться рядки у msgid і msgstr, тобто того, у який спосіб до цих рядків додаватимуться символи розриву рядків.
Зауваження: $lang буде розгорнуто до запису поточної мови.
po4a потрібен аргумент із назвою файла налаштувань. Цей файл має містити такі елементи:
В усіх рядках міститься запис команди у квадратних дужках, за яким вказано параметри. Коментарі починаються з символу «#» і завершуються кінцем рядка. Ви можете екранувати кінець рядка і поділити команду на декілька рядків.
На цій сторінці представлено декілька повних прикладів. Інші приклади можна знайти у каталозі "t/cfg" пакунка із початковим кодом програми.
Найпростішим рішенням є явне визначення шляху до файлів POT та PO, ось так:
[po4a_paths] man/po/project.pot de:man/po/de.po fr:man/po/fr.po
Тут ми спочатку вказуємо шлях до файла POT, а потім шляхи до файлів PO перекладів німецькою та французькою мовами.
Те саме можна записати для зменшення ризику помилок при копіюванні ось так:
[po4a_langs] fr de [po4a_paths] man/po/project.pot $lang:man/po/$lang.po
Компонент $lang буде автоматично розгорнути на основі наданого списку мов. Це зменшить ризик помилки під час вставляння при додаванні нової мови перекладу.
Зробити той самий запис компактнішим можна надавши шлях до каталогу, у якому міститься проєкт з перекладу. Приклад наведено нижче.
[po_directory] man/po/
У вказаному каталозі має міститися набір файлів PO, назви яких слід записувати у форматі XX.po, де "XX" — код мови перекладу за ISO 639-1. У каталозі також має зберігатися один файл POT із суфіксом назви ".pot". Для першого запуску цей файл може бути порожнім, але має існувати (po4a не може визначити назву, якою слід скористатися перед суфіксом).
Зауважте, що слід вибрати лише один з варіантів, "po_directory" або "po4a_paths". Перший ("po_directory") є компактнішим, зменшує ризик помилки під час копіювання, але примушує вас до використання очікуваної структури проєкту та назв файлів. Другий ("po4a_paths") є більш явним, ймовірно, зручнішим для читання, радимо користуватися ним, якщо ви налаштовуєте ваш перший проєкт у po4a.
Централізовані чи поділені файли PO?
Типово, po4a створює по одному файлу PO для кожної мови перекладу. У цих файлах міститиметься увесь ваш проєкт перекладу. Зі зростанням вашого проєкту розмір цих файлів може стати проблемою. При використанні weblate можна встановити для кожного з повідомлень перекладу (тобто msgid) пріоритетність, тому варто встановити її так, щоб важливі рядки було перекладено першими, але деякі команди перекладачів, попри це, можуть просити про поділ даних на декілька файлів.
Щоб створити один файл PO для кожного основного файла, вам слід просто скористатися рядком $master у назві ваших файлів PO у рядку "[po4a_paths]", як це показано нижче.
[po4a_paths] doc/$master/$master.pot $lang:doc/$master/$lang.po
Якщо використати цей рядок, po4a створюватиме окремі файли POT і PO для кожного документа, який слід перекласти. Наприклад, якщо у вас є 3 документи та 5 мов, буде створено 3 файли POT та 15 файлів PO. Назви для цих файлів буде вибрано за шаблоном "po4a_paths", а $master буде замінено на базову назву кожного документа, який слід перекласти. Якщо виникне конфлікт назв, ви можете вказати файл POT, який слід використати, так, як це показано нижче, за допомогою параметра "pot = ".
Цією можливістю також можна скористатися для групування декількох перекладених файлів до одного файла POT. У наведеному нижче прикладі буде створено лише 2 файли POT: l10n/po/foo.pot (що містить матеріал з foo/gui.xml) і l10n/po/bar.pot (що містить матеріал з bar/gui.xml і bar/cli.xml).
[po4a_langs] de fr ja [po4a_paths] l10n/po/$master.pot $lang:l10n/po/$master.$lang.po [type: xml] foo/gui.xml $lang:foo/gui.$lang.xml pot=foo [type: xml] bar/gui.xml $lang:bar/gui.$lang.xml pot=bar [type: xml] bar/cli.xml $lang:bar/cli.$lang.xml pot=bar
У режимі поділу po4a будує тимчасову збірку під час оновлення файлів PO, щоб розподілити переклади між усіма файлами PO. Якщо буде виявлено два файли PO із різними перекладами одного і того самого рядка, po4a позначить переклад рядка як неточний і надішле обидва переклади до усіх файлів PO, які містять цей рядок. Коли перекладач оновлюватиме переклад і вилучить позначку неточного перекладу у одному з файлів PO, переклад цього рядка буде оновлено у всіх інших файлах PO автоматично.
Вам слід також вказати список документів, які має бути перекладено. Для кожного основного файла вам слід вказати обробник формату, розташування перекладеного документа, який слід створити, та, необов'язково, додаткові налаштування. Ось приклад:
[type: sgml] doc/my_stuff.sgml fr:doc/fr/mon_truc.sgml \
de:doc/de/mein_kram.sgml
[type: man] script fr:doc/fr/script.1 de:doc/de/script.1
[type: docbook] doc/script.xml fr:doc/fr/script.xml \
de:doc/de/script.xml
Втім, знову, ці складні рядки важко читати і редагувати, наприклад, додавати нову мову. Набагато простіше перевпорядкувати речі за допомогою шаблона $lang ось так:
[type: sgml] doc/my_stuff.sgml $lang:doc/$lang/my_stuff.sgml [type: man] script.1 $lang:po/$lang/script.1 [type: docbook] doc/script.xml $lang:doc/$lang/script.xml
Ви можете вказати два типи параметрів: параметри po4a є типовими значенням параметрів командного рядка po4a, а параметри форматування використовуються для зміни поведінки засобів обробки форматування. За допомогою параметрів po4a, наприклад, ви можете вказати у вашому файлі налаштувань типове значення параметра командного рядка --keep 50% замість 80%. Параметри форматування документовано на окремих сторінках кожного з модулів обробки форматування, наприклад, Locale::Po4a::Xml(3pm). Ви можете, наприклад, передати nostrip до засобу обробки XML наказ не обрізати пробіли навколо видобутих рядків.
Ви можете передати ці параметри для певного основного файла або навіть для певного перекладу цього файла за допомогою "opt:" і "opt_XX:" для мови "XX". У наступному прикладі параметр nostrip передається обробнику XML (для усіх мов), а пороговий відсоток перекладу зменшено до 0% для перекладу французькою (тобто визначено, що цей переклад зберігатиметься завжди).
[type:xml] toto.xml $lang:toto.$lang.xml opt:"-o nostrip" opt_fr:"--keep 0"
За будь-яких умов, ці фрагменти налаштувань має бути розташовано наприкінці рядка. Оголошення файлів мають бути першими, далі мають бути додатки, якщо такі є (див. нижче), а лише потім має бути вказано параметри. Групування фрагментів налаштувань не є дуже важливим, оскільки на внутрішньому рівні елементи буде поєднано як рядки. Наступні приклади є еквівалентними:
[type:xml] toto.xml $lang:toto.$lang.xml opt:"--keep 20" opt:"-o nostrip" opt_fr:"--keep 0" [type:xml] toto.xml $lang:toto.$lang.xml opt:"--keep 20 -o nostrip" opt_fr:"--keep 0" [type:xml] toto.xml $lang:toto.$lang.xml opt:--keep opt:20 opt:-o opt:nostrip opt_fr:--keep opt_fr:0
Зауважте, що специфічні для мов параметри не використовуватимуться при збиранні файла POT. Наприклад, не можна передати nostrip обробнику лише для збирання французького перекладу, оскільки той самий файл POT використовується для оновлення у кожній з мов. Тому єдині параметри, які можуть бути специфічними для мови, є параметри, які буде використано для створення перекладених документів, наприклад параметр "--keep".
Альтернативи налаштувань
Щоб передати ті самі параметри для декількох файлів, варто створити альтернативний тип у наведений нижче спосіб. У наступному прикладі, "--keep 0" передається для усіх перекладів італійською за допомогою типу "test", який є розширенням типу "man".
[po4a_alias:test] man opt_it:"--keep 0" [type: test] man/page.1 $lang:man/$lang/page.1
Ви також можете розширити наявний тип повторним використанням тієї самої назви як альтернативної у наведений нижче спосіб. Такі оголошення не вважаються помилковими рекурсивними оголошеннями.
[po4a_alias:man] man opt_it:"--keep 0" [type: man] man/page.1 $lang:man/$lang/page.1
Загальні типові параметри
Ви також можете скористатися рядками "[options]" для визначення параметрів, які має бути використано для усіх файлів, незалежно від типу.
[options] --keep 20 --option nostrip
Як і з параметрами командного рядка, ви можете скорочувати записи параметрів, які передаються через файл налаштувань:
[options] -k 20 -o nostrip
Пріоритетність параметрів
Параметри для усіх джерел буде поєднано. Це забезпечить просте перевизначення типових значень специфічними параметрами. Порядок визначення є таким:
Приклад
Ось приклад, який демонструє те, як екранувати пробіли і лапки:
[po_directory] man/po/
[options] --master-charset UTF-8
[po4a_alias:man] man opt:"-o \"mdoc=NAME,SEE ALSO\""
[type:man] t-05-config/test02_man.1 $lang:tmp/test02_man.$lang.1 \
opt:"-k 75" opt_it:"-L UTF-8" opt_fr:--verbose
Якщо вам потрібно додати додатковий розділ до вашого перекладу, наприклад, вказати у ньому подяки перекладачу, вам слід визначити додаток у рядку, який визначає ваш основний файл. Будь ласка, зверніться до сторінки підручника (man) po4a(7), щоб дізнатися більше про синтаксис файлів додатків.
[type: pod] script fr:doc/fr/script.1 \
add_fr:doc/l10n/script.fr.add
Використовувати шаблони мов можна так:
[type: pod] script $lang:doc/$lang/script.1 \
add_$lang:doc/l10n/script.$lang.add
Якщо додаток не вдасться застосувати, переклад буде відкинуто.
Модифікатори для оголошення додатка
Модифікатори додатків можуть спростити файл налаштувань, якщо додатки надаються не для усіх мов або якщо список додатків для різних мов є різним. Модифікатор — одинарний символ, який вказують перед назвою файла.
Вказана нижче інструкція призводить до включення додатка для усіх мов, але лише якщо такий додаток існує. Якщо додатка не існує, програма не повідомлятиме про це додатково.
[type: pod] script $lang:doc/$lang/script.1 add_$lang:?doc/l10n/script.$lang.add
Наведений нижче код включає список додатків для будь-якої мови:
[type: pod] script $lang:doc/$lang/script.1 add_$lang:@doc/l10n/script.$lang.add
Іноді, може виникнути потреба в усуванні частини рядків з перекладу. Для цього ви можете передати параметр "pot_in" для вашого основного файла з метою визначення назви файла, який буде використано замість основного при побудові файла POT. Ось приклад:
[type:docbook] book.xml \
pot_in:book-filtered.xml \
$lang:book.$lang.xml
У прикладі, рядки для перекладу буде видобуто з файла book-filtered.xml (який має бути створено до виклику po4a), а перекладені файли буде створено з файла book.xml. У результаті, усі рядки, які є частиною файла book.xml, але не є частиною book-filtered.xml не буде включено до файлів PO, а отже, перекладачі не витрачатимуть час на переклад цих рядків. Тому ці рядки лишатимуться незмінними і у перекладених документах. Це, звичайно ж, знизить рівень перекладеності документа, тому вам слід скористатися параметром "--keep" для забезпечення створення перекладених документів навіть для неповних перекладів.
Denis Barbier <barbier@linuxfr.org> Nicolas François <nicolas.francois@centraliens.net> Martin Quinson (mquinson#debian.org)
© SPI, inc., 2002–2022.
Ця програма є вільним програмним забезпеченням; ви можете поширювати її і/або вносити до неї зміни за умов дотримання GPL (див. файл COPYING).
| 2023-01-03 | Інструменти Po4a |