Проблема, яка розв'язується¶

Відповіді щодо po4a¶

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

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

Підтримувані формати¶

man

Старий добрий формат сторінок підручника, який використовується у багатьох програмах. Підтримка у po4a тут дуже доречна, оскільки цей формат доволі складний у використанні і не дуже зручний для недосвідчених користувачів. У модулі Locale::Po4a::Man(3pm) також передбачена підтримка формату mdoc, який використовується у сторінках підручника BSD (їх також доволі часто використовують у Linux).

pod

Це формат інтернет-документації до Perl (Perl Online Documentation). За його допомогою документовано саму мову і її розширення, а також більшість із наявних скриптів Perl. Він спрощує синхронізацію документації із кодом, оскільки і документація, і код є частиною одного файла. Це спрощує завдання програміста, але, на жаль, не перекладача.

sgml

Хоча цей формат на сьогодні дещо поступився місцем XML, його ще досить часто використовуються для досить довгих документів. За його допомогою можна створювати цілі книги. Оновлення перекладів таких довгих документів може стати справжнім жахом. diff часто виявляється безпорадним, якщо відступи у початковому тексті після оновлення буде змінено. На щастя, тут у пригоді вам стане po4a.

У поточній версії передбачено підтримку лише DebianDoc і DocBook DTD, але додавання підтримки нових форматі є дуже простим. po4a можна навіть використовувати для невідомих DTD SGML без зміни коду, якщо надати потрібну інформацію за допомогою командного рядка. Див. Locale::Po4a::Sgml(3pm), щоб дізнатися більше.

TeX / LaTeX

Формат LaTeX є основним форматом документації, який використовується у світі вільного програмного забезпечення та для публікацій. Модуль Locale::Po4a::LaTeX(3pm) було перевірено на документації до Python, книзі і декількох презентаціях.

texinfo

У цьому форматі записано усю документацію GNU (наявність такої документації є навіть однією із вимог для отримання статусу офіційного проекту GNU). Підтримка модуля Locale::Po4a::Texinfo(3pm) у po4a усе ще перебуває на початковому етапі. Будь ласка, повідомляйте про вади і ваші запити щодо реалізації функціональних можливостей.

xml

Формат XML є базовим для багатьох форматів документації.

У поточній версії po4a передбачено підтримку DTD DocBook. Докладніше про це на сторінці Locale::Po4a::Docbook(3pm).

інші

Крім того, po4a також може працювати із іншими рідкісними і спеціалізованими форматами, зокрема документацією до параметрів компіляції ядер Linux 2.4+ та діаграмами, які створено за допомогою програми Dia. Додати новий формат часто доволі просто. Основним у цьому є є створення обробника початкового формату. Докладніший опис цього можна знайти у розділі Locale::Po4a::TransTractor(3pm).

Непідтримувані формати¶

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

Графічний огляд¶

Зауважте, що як приклад документа, який слід перекласти, вибрано основний.документ, а відповідний перекладений документ позначено перекладений.документ. Суфіксом назви може бути .pod, .xml або .sgml, залежно від формату документа. Докладний опис кожної із частин схеми наведено у наступних розділах.

                                   основний.документ
                                       |
                                       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, на нову систему. У верхній частині праворуч зображено роботу автора початкового тексту (оновлення документації). У середній частині праворуч зображено послідовність автоматичних дій po4a. Новий тестовий матеріал видобувається з документа і порівнюється із наявним перекладом. Виявляються частини, які не змінилися, — для них використовується наявний переклад. Частини, які зазнали часткових змін також пов'язуються із попереднім перекладом, але із особливою позначкою, яка вказує на те, що переклад має бути оновлено. У нижній частині схеми показано процес побудови форматованого перекладеного документа.

Насправді, з точки зору перекладача, єдиною дією, яку слід виконати вручну є частина, яку позначено написом {редагування вручну}. Так, вибачте, але po4a лише допомагає вам перекладати. Програма не здатна виконати переклад за вас…

Як розпочати переклад?¶

Щоб розпочати новий переклад за допомогою po4a, вам слід виконати такі кроки:

• Видобудьте текст, який має бути перекладено, з початкового документа <основний.документ> до нового шаблону перекладу — файла <переклад.pot> (у форматі gettext). Для цього скористайтеся програмою po4a-gettextize ось так:

    $ po4a-gettextize -f <формат> -m <основний_документ> -p <переклад.pot>
      

  Рядком <формат>, звичайно ж, має бути назва формату, використаного у документі основний.документ. Зрозуміло, дані буде виведено до файла переклад.pot. Будь ласка, зверніться до документації із po4a-gettextize(1), щоб дізнатися більше про можливі параметри команди.

• Виконайте переклад тексту. Для цього вам слід перейменувати файл POT на, наприклад, документація.XX.po (де XX — код мови, якою ви перекладаєте, зі стандарту ISO 639-1, наприклад, uk для української) і внесіть відповідні зміни до файла. Зазвичай, не варто називати файл просто XX.po, щоб уникнути конфлікту назв із файлом перекладів інтерфейсу програми, але ви все ж можете це зробити. Не забудьте оновити заголовок файла PO, оскільки там містяться важливі дані.

  Сам переклад можна виконати у режимах PO Emacs або Vi, у Lokalize (на основі KDE), Gtranslator (на основі GNOME) або будь-якій програми, якій ви надаєте перевагу (наприклад Virtaal).

  Якщо ви хочете дізнатися більше, вам напевне слід звернутися до документації з gettext, яка є частиною пакунка gettext-doc.

Як створити з перекладу файл документації?¶

  $ po4a-translate -f <формат> -m <основний_документ> -p <документ.XX.po> -l <документ_XX>

Як і раніше, <формат> — формат, у якому записано дані документа основний.документ. Втім, цього разу файл PO, вказаний за допомогою параметра -p, є частиною вхідних даних. Це ваш переклад. Результат обробки буде записано до файла XX.документ.

Докладніше про це на сторінці підручника po4a-translate(1).

Як оновлювати переклад po4a?¶

  $ po4a-updatepo -f <формат> -m <новий_основний.документ> -p <старий_документ.XX.po>

(Докладніше про це на сторінці підручника po4a-updatepo(1))

Звичайно ж, нові фрагменти тексту у документі не буде перекладено автоматично у файлі PO під час виконання цієї дії. Вам доведеться оновити вміст файла PO вручну. Крім того, вам слід буде переглянути переклад повідомлень, які було трохи змінено у оригіналі. Щоб переконатися, що ви не пропустите такі повідомлення, їх буде позначено як «неточні» («fuzzy») під час оновлення. Вам слід буде вилучити цю позначку, перш ніж перекладом можна буде скористатися за допомогою po4a-translate. Як і з початковим перекладом, найкраще для цього скористатися вашим улюбленим редактором файлів PO.

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

Як перетворити готові переклади у формат po4a?¶

Ключовим моментом тут є однакова структура перекладеного документа та початкового документа. Це уможливлює встановлення відповідності фрагментів тексту програмами.

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

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

Поганий результат буде отримано, якщо ви скористаєтеся оновленим початковим текстом і застарілим перекладом. Перетворення лишиться можливим, але його буде виконати складніше. Якщо можливо, не робіть так. Фактично, якщо ви не знайдете початковий текст, найкраще знайти когось, хто виконає перетворення на gettext за вас (але, будь ласка, нехай це буду не я ;).

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

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

Якщо у вас є старий основний.документ, який відповідає перекладу XX.документ, перетворення на формат gettext можна виконати безпосередньо до файла PO документ.XX.po без потреби у перекладі вручну файла переклад.pot:

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

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

Будь ласка, зауважте, що навіть якщо усе, здається, працює як слід, у процесі можуть все ж трапитися помилки. Причиною є те, що програми po4a не здатні зрозуміти текст і переконатися, що переклад відповідає оригіналу. Ось чому усі рядки у процесі буде позначено як неточні переклади («fuzzy»). Вам слід ретельно перевірити кожен переклад, перш ніж вилучати ці позначки.

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

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

• Вилучіть усі додаткові частини перекладу, зокрема розділ із іменами і подяками усім учасникам перекладу. Додатки, які описано у наступному розділі, нададуть вам змогу знову додати ці частини пізніше.
• Не вагайтеся редагувати і початковий файл і переклад. Найважливішим для вас є отримання файла PO. Далі ви зможете оновити його дані. Редагування перекладу, звичайно, є бажанішим, якщо доступним є редагування обох документів, оскільки це полегшує роботу, коли перетворення на формат gettext вже буде виконано.
• Якщо потрібно, вилучіть частини з оригіналу, якщо їх не було перекладено. Під час наступної синхронізації файла PO із актуальним документом, ці частини у ньому, звичайно ж, з'являться.
• Якщо ви трохи змінили структуру документа (для об'єднання двох абзаців або поділу одного на два), скасуйте ці зміни. Якщо у оригіналі документа були вади, вам слід повідомити про них авторові. Виправлення цих вад у вашому перекладі буде корисним лише частині спільноти. Більше того, таке виправлення неможливе, якщо використовується система po4a ;)
• Іноді вміст абзаців збігається, але їхні типи є різними. Шлях виправлення цієї помилки залежить від формату документа. У POD і man поширеною причиною подібних проблем є те, що один з рядків починається із пробілу, а інший — ні. У таких форматах абзац із пробілом не можна переносити за рядками, отже він стає абзацом іншого типу. Достатньо вилучити пробіл, і усе запрацює. Також причиною може бути друкарська помилку у назві теґу.

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

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

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

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

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

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

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

Як додати до перекладу додатковий текст (наприклад, ім'я перекладача)?¶

Для кращого розуміння, додатки можна вважати латками, які накладаються на перекладений документ після обробки. Насправді, вони відрізняються від звичайних латок (у них лише один рядок контексту, до якого можна вбудувати формальний вираз Perl, і вони лише додають текст без вилучення фрагментів старого), але за функціональними можливостями додатки збігаються з латками.

Метою створення додатків є додавання таких даних до документа, які не є перекладом початкового документа. Типовим застосуванням додатків є додавання розділу, присвяченого самому перекладу, розділу зі списком учасників перекладу та настановами щодо звітування про вади у перекладі.

Додаток слід оформлювати як окремий файл. У першому рядку заголовка додатка має бути вказано місце у створеному документі, куди слід вставити додаток. Решту файла додатка буде вставлено буквально у визначену позицію остаточного документа.

Синтаксис рядка заголовка для визначення контексту доволі строгий: він має починатися з рядка PO4A-HEADER:. Далі має бути вказано список відокремлених крапкою з комою (;) полів ключ=значення. Усі пробіли БЕРУТЬСЯ ДО УВАГИ. Зауважте, що не можна використовувати символ крапки з комою (;) у значенні, екранування цього символу тут також не допоможе. Якщо потрібно, для зручності читання можна вставляти пробіли ( ) перед записом ключ.

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

Ознайомитися із справжнім вмістом внутрішнього рядка даних перекладеного документа можна за допомогою запуску po4a у діагностичному режимі.

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

Ось можливі ключі заголовка:

mode (обов'язковий)

Це може бути або рядок before, або рядок after.

Якщо вказано режим mode=before, точка вставлення визначається у один крок на основі відповідності вказаному параметру формального виразу position. Ця точка вставлення розташовується безпосередньо перед однозначно встановленим відповідником — внутрішнім рядком даних перекладеного документа.

Якщо вказано режим mode=after, точка вставлення визначається у два кроки за відповідністю форматним виразам, вказаним у параметрі формального виразу position, та параметрами формального виразу beginboundary або endboundary.

Оскільки у розглянутому випадку може бути декілька розділів, скористаємося двокроковим підходом.

     mode=after
    

position (обов'язковий)

Формальний вираз Perl для визначення контексту.

Якщо цьому виразу відповідатиме декілька рядків (або жодного), пошук точки вставлення зазнає невдачі, отже нічого додаватися не буде. Справді, краще повідомити про помилку, ніж вставляти додаток у помилкове місце.

Якщо визначено mode=before, а вказану точка вставлення перебуває безпосередньо перед внутрішнім рядком даних, який точно відповідає параметру position формального виразу.

Якщо визначено режим mode=after, область пошуку точки вставлення звужується до даних після рядка внутрішніх даних, що однозначно відповідає параметру формального виразу position. Точне ж розташування точки вставлення визначається параметром beginboundary або endboundary.

У нашому випадку нам треба пропустити декілька попередніх розділів звуженням пошуку за допомогою рядка заголовка розділу.

     position=Про цей документ
    

(Насправді, тут вам слід скористатися рядком перекладеного заголовка.)

beginboundary (використовується, лише якщо mode=after, і є обов'язковим у цьому випадку)

endboundary (те саме)

Другий формальний вираз Perl потрібен, лише якщо mode=after. Додаток буде розташовано безпосередньо перед або після першого відповідника у внутрішньому рядку даних до параметра формального виразу beginboundary або endboundary, відповідно.

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

   endboundary=</section>
    

або, для позначення початку нового розділу, вказавши:

   beginboundary=<section>
    

У обох випадках, наш додаток буде розташовано після </section> і перед <section>. Перший варіант є кращим, оскільки він працюватиму навіть після реорганізації документа.

Дві форми існують через відмінності у форматах документації. У деяких з них передбачено підтримку позначення кінця розділу (подібно до теґу </section>, яким ми щойно скористалися), а в інших кінець розділу ніяк явно не позначається (зокрема такі проблеми виникають у форматі man). У першому випадку шукати слід на межі, у кінці розділу, так, щоб точка вставлення розташовувалися після знайденої позиції. У другому ж випадку, слід шукати на межі, але на початку наступного розділу, так, щоб точка вставлення перебувала точно перед знайденою позицією.

Це може здатися незрозумілим, але, сподіваємося, наступні приклади зроблять усе зрозумілішим.

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

 PO4A-HEADER: mode=after; position=About this document; endboundary=</section>
 PO4A-HEADER: mode=after; position=About this document; beginboundary=<section>
    

Якщо ви хочете додати щось після такого розділу nroff:

  .SH "AUTHORS"
    

Вам слід вибрати двокроковий підхід встановленням значення mode=after. Далі, вам слід звузити пошук до рядка після AUTHORS за допомогою параметра формального виразу position. Далі, вам потрібно встановити відповідність початку нового розділу (тобто, ^\.SH) за допомогою параметра формального виразу beginboundary. Тобто, слід зробити так:

 PO4A-HEADER:mode=after;position=AUTHORS;beginboundary=\.SH
    

Якщо ви хочете додати щось у розділ (наприклад, після «Copyright Big Dude, 2004») замість додавання цілого розділу, вкажіть для position критерій пошуку відповідного рядка, а для beginboundary вкажіть відповідник будь-якого рядка.

 PO4A-HEADER:mode=after;position=Copyright Big Dude, 2004;beginboundary=^
    

Якщо ви хочете щось додати наприкінці документа, вкажіть для position відповідник будь-якого рядка вашого документа (але лише одного, бо po4a відмовиться виконувати дію, якщо буде знайдено декілька таких рядків), а для endboundary вкажіть рядок, якого немає у документі. Не використовуйте для цього рядка надто прості варіанти, наприклад "EOF", — вкажіть щось, що має набагато менші шанси бути знайденим у документі.

 PO4A-HEADER:mode=after;position=Про цей документ;beginboundary=FakePo4aBoundary
    

Щоб там не було, пам'ятайте, що це формальні вирази. Наприклад, якщо ви хочете встановити відповідність кінцю розділу nroff, який завершується рядком

  .fi

не використовуйте .fi у полі endboundary, оскільки вказаний рядок є формальним виразом, за яким може бути знайдено, наприклад, рядок «the[ fi]le», що, звичайно ж, є небажаним. Правильним значенням для endboundary у цьому випадку буде таке: ^\.fi$.

Якщо додаток опиниться не там, де ви сподівалися, спробуйте додати до рядка команди -vv, щоб отримати додаткові дані щодо того, які дії виконуються для вставляння додатка.

Докладніший приклад

Початковий документ (у форматуванні 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(1) було створено, щоб усунути ці складнощі. Щойно ваш проект буде переведено на нашу систему, вам достатньо буде написати простий файл налаштувань з поясненнями, де зберігаються ваші файли перекладів (PO і POT), де зберігаються початкові документи, у яких форматах зберігаються ці документи, і де слід зберігати переклади документів.

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

Як налаштувати po4a?¶

Ви також можете редагувати початковий код наявних модулів або навіть написати власні модулі. Щоб зробити ці модулі видимими для po4a, скопіюйте їх до каталогу із назвою "/щось/там/lib/Locale/Po4a/", а потім додайте шлях "/щось/тамh/blu" до змінної середовища "PERLIB" або "PERL5LIB". Приклад:

   PERLLIB=$PWD/lib po4a --previous po4a/po4a.cfg

Зауваження: справжня назва каталогу lib не є важливою.

Як все виглядає на загальному плані?¶

Формально, він отримує документ для перекладу і файл PO з перекладами на вході і створює два потоки виведених даних: ще один файл PO (який є результатом видобування придатних до перекладу рядків із вхідного документа) та перекладений документ (тієї самої структури, що і вхідний, але із заміною усіх придатних до перекладу рядків на вміст вхідного файла PO). Ось графічне представлення обробки:

   Вхідний документ --\                             /---> Вихідний документ
                     \      TransTractor::       /       (перекладений)
                      +-->--   parse()  --------+
                     /                           \
 Вхідний PO --------/                             \---> Вихідний PO
                                                         (видобутий)

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

TransTractor::parse() є віртуальною функцією, яка реалізується у кожному модулі. Ось невеличкий приклад того, як це працює. Код обробляє список абзаців, кожен з яких починається з <p>.

  1 sub parse {
  2   PARAGRAPH: while (1) {
  3     $my ($paragraph,$pararef,$line,$lref)=("","","","");
  4     $my $first=1;
  5     while (($line,$lref)=$document->shiftline() && defined($line)) {
  6       if ($line =~ m/<p>/ && !$first--; ) {
  7         $document->unshiftline($line,$lref);
  8
  9         $paragraph =~ s/^<p>//s;
 10         $document->pushline("<p>".$document->translate($paragraph,$pararef));
 11
 12         next PARAGRAPH;
 13       } else {
 14         $paragraph .= $line;
 15         $pararef = $lref unless(length($pararef));
 16       }
 17     }
 18     return; # Не отримали визначений рядок? Кінець файла вхідних даних.
 19   }
 20 }

У рядках 6 і 7 ми бачимо "shiftline()" і "unshiftline()". Ці функції допомагають читати і записувати заголовок внутрішнього потоку вхідних даних основного документа до рядка та його прив'язки. Прив'язка зберігається у рядку "$filename:$linenum". Будь ласка, пам'ятайте, що у Perl передбачено лише одновимірну структур даних для масивів. Отже обробка коду рядка потоку вхідних даних є дещо ускладненою.

У рядку 6 ми бачимо <p> вдруге. Це сигнал щодо наступного абзацу. Отже, ми маємо вставити щойно отриманий рядок назад у початковий документ (рядок 7) і надіслати створений таким чином абзац до виведених даних. Після вилучення початкового <p> з абзацу у рядку 9, ми надсилаємо до виведення об'єднання цього теґу і перекладу решти абзацу.

Ця функція translate() прекрасна. Вона надсилає свій аргумент до вихідного файла PO (видобування) і повертає його переклад, відповідно до вхідного файла PO (переклад). Оскільки вона використовується як частина аргументу pushline(), переклад опиняється у документі, який є результатом обробки.

Хіба це не чудово? Можна створити повноцінний модуль po4a, у якому буде менше за 20 рядків, якщо формат є доволі простим…

Докладніше про це у розділі Locale::Po4a::TransTractor(3pm).

Перетворення на формат gettextization: як це працює?¶

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

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

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

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

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

Додаток: як це працює?¶

Чому слід перекладати кожен абзац окремо?¶

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

Навіть ці переваги не переконують декого у тому, що кожен абзац слід перекладати окремо. Ось декілька тез, які ми можемо висловити у відповідь на заперечення цієї методики:

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

Чому не поділити усе на рівні речень (або навіть дрібніших одиниць)?¶

Абзаци, за означенням, є довшими за речення. Можна сподіватися, що однакові абзаци у двох різних документах матимуть те саме значення (і переклад), незалежно від контексту.

Поділ на частини, менші за речення, дасть дуже погані результати. Пояснення причин є надто довгим, щоб наводити його тут, але зацікавлений читач може звернутися до прикладу, наведеного на сторінці підручника Locale::Maketext::TPJ13(3pm) (яка є частиною документації до Perl). Якщо коротко, у кожної мови є власні правила щодо синтаксису. Не існує способу побудови речення за допомогою збирання перекладів частин речення, які б працювали для усіх відомих мов (навіть для 5 з 10 найрозповсюдженіших).

Чому б просто не додавати оригінал як коментар до перекладу (або якось у інший спосіб)?¶

Саме тому розробник debconf вирішив реалізувати інший підхід, коли переклади розташовуються у тому самому файлі, що і оригінал. Такий підхід є доволі привабливим. Декому може видатися, що це буде добре і для, наприклад, XML. Це б виглядало десь так:

 <section>
  <title lang="en">My title</title>
  <title lang="uk">Мій заголовок</title>

  <para>
   <text lang="en">My text.</text>
   <text lang="uk">Мій текст.</text>
  </para>
 </section>

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

• проблеми із супроводом

  Якщо декілька перекладачі надішлють латку одночасно, буде важко об'єднати латки.

  Як ви зможете виявити зміни у оригіналі, які слід реалізувати у новій версії перекладу? Щоб скористатися diff, вам потрібні будуть значення щодо версії оригіналу, яку було перекладено. Отже, у вашому житті все одно з'явиться файл PO. ;)

• проблеми з кодуванням

  Цей підхід добре працює лише для частини європейських мов, але додавання корейської, української і/або арабської значно ускладнює картину. Можна було б скористатися UTF, але і з ним є певні проблеми.

  Більше того, такі проблеми важко виявити (тобто лише ті, хто знає корейську можуть виявити, що кодування хангилю є помилковим [наприклад, через дії перекладача російською]).

gettext розв'язує усі ці проблеми одночасно.

Але gettext не було створено для такого використання!¶

Як щодо інших засобів перекладу документації, де використовується gettext?¶

poxml

Це програма, яку розроблено KDE для роботи із XML DocBook. Наскільки мені відомо, це була перша програма, яка видобувала рядки для перекладу з документації до файлів PO і вставляла ці рядки назад після перекладу.

Ця програма може працювати лише із форматом XML і лише з певним DTD. Мені не дуже подобається робота зі списками у ній, оскільки використання списків за певних умов призводить до створення величезних msgid. Якщо список дуже великий, перекладати його стає дуже складно.

po-debiandoc

Цю програму створено Денісом Барбьє (Denis Barbier) як певним чином попередницю модуля SGML po4a, який більшою чи меншою мірою зробив цю програму застарілою. Як можна зрозуміти з назви, програма здатна працювати лише з DTD DebianDoc, який є більшою чи меншою мірою застарілим DTD.

Основною перевагою po4a над цими програмами є простора додавання додаткових даних (що важко або неможливо зробити у цих програмах) та можливість перетворення даних до стандартного формату gettext.

Навчання розробників основам створення придатного для перекладу коду¶

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

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

 |       *****************************************************
 |       *           GENERATED FILE, DO NOT EDIT             *
 |       * THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
 |       *****************************************************
 |
 | This file was generated by po4a-translate(1). Do not store it (in VCS,
 | for example), but store the PO file used as source file by po4a-translate.
 |
 | In fact, consider this as a binary, and the PO file as a regular source file:
 | If the PO gets lost, keeping this translation up-to-date will be harder ;)

Так само, звичайні файли PO gettext слід лише скопіювати до каталогу po/. Втім, це не стосується тих файлів, з якими працює po4a. Основним ризиком тут є те, що розробник може замінити наявний переклад інтерфейсу програми перекладом її документації. (Дані обох цих перекладів не можуть зберігатися у одному файлі PO, оскільки програма має встановлювати переклад як файл mo, а переклад документації використовується лише для збирання перекладеної документації під час компіляції програми). Ось чому файли PO, створені модулем po-debiandoc містять такий заголовок:

 #
 #  ADVISES TO DEVELOPERS:
 #    - you do not need to manually edit POT or PO files.
 #    - this file contains the translation of your debconf templates.
 #      Do not replace the translation of your program with this !!
 #        (or your translators will get very upset)
 #
 #  ADVISES TO TRANSLATORS:
 #    If you are not familiar with the PO format, gettext documentation
 #     is worth reading, especially sections dedicated to this format.
 #    For example, run:
 #         info -n '(gettext)PO Files'
 #         info -n '(gettext)Header Entry'
 #
 #    Some information specific to po-debconf are available at
 #            /usr/share/doc/po-debconf/README-trans
 #         or http://www.debian.org/intl/l10n/po-debconf/README-trans
 #

РЕЗЮМЕ щодо переваг заснованого на gettext підходу¶

• Переклади не зберігаються разом із оригіналами, що робить можливим виявлення перекладів, які застаріли.
• Переклади різними мовами зберігаються у різних файлах, тому перекладачі різними мовами не конфліктують між собою під час подання латок до файлів та на рівні кодування даних у файлах.
• На внутрішньому рівні переклад засновано на gettext (але po4a пропонує дуже простий інтерфейс, отже вам не потрібно знати усі тонкощі внутрішньої обробки даних, щоб скористатися ним). Таким чином, ми не винаходили нічого нового, а через широке використання інструментів перекладу gettext можна вважати, що ці інструменти більшою чи меншою мірою вільні від вад.
• Для кінцевого користувача нічого не міняється (окрім факту кращого супроводу перекладів). Остаточний файл документації розповсюджується у звичний спосіб.
• Перекладачам не потрібно вивчати новий синтаксис файлів, а їхня улюблена програма для перекладу (наприклад, режим PO у Emacs, Lokalize чи Gtranslator) легко може бути використана для перекладу.
• У 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), такою комбінацією модуля з програмами для перекладу могли б користуватися навіть професійні перекладачі.