PO4A

Section: Інструменти Po4a (7)
Updated: 2024-01-29
Index Return to Main Contents

НАЗВА

po4a — набір інструментів для перекладу документації та інших матеріалів

Вступ

po4a («PO for anything» або «PO для усього») спрощує супровід перекладу документації з використанням класичних інструментів gettext Основною перевагою po4a є відокремлення придатного до перекладу вмісту документа від його структури.

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

Чому po4a?

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

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

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

Regarding documentation, however, the situation still somewhat disappointing. At first translating documentation may seem to be easier than translating a program as it would seem that you just have to copy the documentation source file and start translating the content. However, when the original documentation is modified, keeping track of the modifications quickly turns into a nightmare for the translators. If done manually, this task is unpleasant and error-prone.

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

Метою проєкту po4a є спрощення роботи для перекладачів документації. Зокрема, цей проєкт робить переклади документації придатними до супроводу.

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

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

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

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

У поточній версії цей підхід успішно реалізовано для декількох типів документів із текстовим форматуванням:

man (надійний обробник): Старий добрий формат сторінок підручника, який використовується у багатьох програмах. Підтримка у po4a тут дуже доречна, оскільки цей формат доволі складний у використанні і не дуже зручний для недосвідчених користувачів.
У модулі Locale::Po4a::Man(3pm) також передбачена підтримка формату mdoc, який використовується у сторінках підручника BSD (їх також доволі часто використовують у Linux).
AsciiDoc (надійний обробник): Цей формат є спрощеним форматом розмітки, призначенням якого є спростити написання документації. Його, наприклад, використано для документування системи git. Такі сторінки підручників перекладено за допомогою po4a.
Див. Locale::Po4a::AsciiDoc, щоб дізнатися більше.
pod (надійний обробник): Це формат інтернет-документації до Perl (Perl Online Documentation). За його допомогою документовано саму мову і її розширення, а також більшість із наявних скриптів Perl. Він спрощує синхронізацію документації із кодом, оскільки і документація, і код є частиною одного файла. Це спрощує завдання програміста, але, на жаль, не перекладача, доки ви не скористаєтеся po4a.
Див. Locale::Po4a::Pod, щоб дізнатися більше.
sgml (надійний обробник): Хоча цей формат на сьогодні дещо поступився місцем XML, його ще досить часто використовуються для досить довгих документів. За його допомогою можна створювати цілі книги. Оновлення перекладів таких довгих документів може стати справжнім жахом. diff часто виявляється безпорадним, якщо відступи у початковому тексті після оновлення буде змінено. На щастя, тут у пригоді вам стане po4a.
У поточній версії передбачено підтримку лише DebianDoc і DocBook DTD, але додавання підтримки нових форматі є дуже простим. po4a можна навіть використовувати для невідомих DTD SGML без зміни коду, якщо надати потрібну інформацію за допомогою командного рядка. Див. Locale::Po4a::Sgml(3pm), щоб дізнатися більше.
TeX / LaTeX (надійний обробник): Формат LaTeX є основним форматом документації, який використовується у світі вільного програмного забезпечення та для публікацій.
Модуль Locale::Po4a::LaTeX(3pm) було перевірено на документації до Python, книзі і декількох презентаціях.
text (надійний обробник): Текстовий формат є базовим форматом для багатьох інших форматів, у яких ви маєте справу зі довгими блоками тексту, зокрема Markdown, fortune-и, розділ титульних елементів YAML, debian/changelog та debian/control.
Цей формат є типовим для генераторів статичних сайтів, файлів README та інших систем документації. Див. Locale::Po4a::Text(3pm), щоб дізнатися більше.
xml і XHMTL (ймовірно, надійний обробник): Формат XML є базовим для багатьох форматів документації.
У поточній версії po4a передбачено підтримку DocBook DTD (докладніше про це див. Locale::Po4a::Docbook(3pm)) та XHTML.
BibTex (ймовірно, надійний обробник): Формат BibTex використовують разом із LaTex для форматування списку посилань (бібліографій).
Див. Locale::Po4a::BibTex, щоб дізнатися більше.
Docbook (ймовірно, надійний обробник): Заснована на XML мова розмітки, у якій використовують семантичні теґи для опису документів.
Див. Locale::Po4a:Docbook, щоб дізнатися більше.
Guide XML (ймовірно, надійний обробник): Формат документації XML. Цей модуль розроблявся спеціально для того, щоб допомогти із підтримкою та супроводом перекладів документації Gentoo Linux, принаймні до березня 2016 року (дані засновано на даних Wayback Machine). З того часу Gentoo перейшла на формат XML DevBook.
Див. Locale::Po4a:Guide, щоб дізнатися більше.
Wml (ймовірно, надійний обробник): Мова розмітки інтернету (Web Markup Language), не плутати з WML із WAP, яку використовують для стільникового зв'язку. Роботу цього модуля засновано на роботі модуля Xhtml, який сам є надбудовою над модулем XML.
Див. Locale::Po4a::Wml, щоб дізнатися більше.
Yaml (ймовірно, надійний обробник): Строго обмежена надбудова над JSON. YAML часто використовують для проєктів систем або налаштувань. YAML є частиною ядра Ansible від Red Hat.
Див. Locale::Po4a::Yaml, щоб дізнатися більше.
RubyDoc (ймовірно, надійний обробник): Формат документів Ruby (RD), розроблено як типовий формат документації до Ruby і проєктів на Ruby до переходу на RDoc у 2002 році. Втім, принаймні японська версія підручника-довідника з Ruby усе ще використовує RD.
Див. Locale::Po4a::RubyDoc, щоб дізнатися більше.
Halibut (ймовірно, експериментальний обробник): Система створення документації із елементами, подібними до TeX, debiandoc-sgml, TeXinfo та інших систем. Розроблено Саймоном Тетгемом (Simon Tatham), розробником PuTTY.
Див. Locale::Po4a:Halibut, щоб дізнатися більше.
Ini (ймовірно, експериментальний обробник): Формат файлів налаштувань, який став популярним завдяки MS-DOS.
Див. Locale::Po4a::Ini, щоб дізнатися більше.
texinfo (дуже експериментальний обробник): У цьому форматі записано усю документацію GNU (наявність такої документації є навіть однією із вимог для отримання статусу офіційного проєкту GNU). Підтримка модуля Locale::Po4a::Texinfo(3pm) у po4a усе ще перебуває на початковому етапі. Будь ласка, повідомляйте про вади та ваші запити щодо реалізації функціональних можливостей.
Інші підтримувані формати: Крім того, po4a також може працювати із іншими рідкісними і спеціалізованими форматами, зокрема документацією до параметрів компіляції ядер Linux 2.4+ (Locale::Po4a::KernelHelp) та діаграмами, які створено за допомогою програми Dia (Locale::Po4a:Dia). Додати новий формат часто доволі просто. Основним у цьому є є створення обробника початкового формату. Докладніший опис цього можна знайти у розділі Locale::Po4a::TransTractor(3pm).
Непідтримувані формати: На жаль, у po4a досі не реалізовано підтримку декількох форматів документації. Підтримку багатьох з них могло б бути доволі просто реалізовано у po4a. Це стосується і форматів, які не є форматами документації, зокрема описів пакунків (deb і rpm), питань у скриптах встановлення пакунків, журналів змін пакунків та усіх спеціалізованих форматів файлів, які використовуються програмами, зокрема сценаріїв ігор та файлів ресурсів wine.

Користування po4a

The easiest way to use this tool in your project is to write a configuration file for the po4a program, and only interact with this program. Please refer to its documentation, in po4a(1). The rest of this section provides more details for the advanced users of po4a wanting to deepen their understanding.

Detailed schema of the po4a workflow

Make sure to read po4a(1) before this overly detailed section to get a simplified overview of the po4a workflow. Come back here when you want to get the full scary picture, with almost all details.

In the following schema, master.doc is an example name for the documentation to be translated; XX.doc is the same document translated in the language XX while doc.XX.po is the translation catalog for that document in the XX language. Documentation authors will mostly be concerned with master.doc (which can be a manpage, an XML document, an AsciidDoc file, etc); the translators will be mostly concerned with the PO file, while the end users will only see the XX.doc file.

Transitions with square brackets such as "[po4a updates po]" represent the execution of a po4a tool while transitions with curly brackets such as "{ update of master.doc }" represent a manual modification of the project's files.

                                   master.doc
                                       |
                                       V
     +<-----<----+<-----<-----<--------+------->-------->-------+
     :           |                     |                        :
{translation}    |         { update of master.doc }             :
     :           |                     |                        :
   XX.doc        |                     V                        V
 (optional)      |                 master.doc ->-------->------>+
     :           |                   (new)                      |
     V           V                     |                        |
  [po4a-gettextize]   doc.XX.po -->+   |                        |
          |            (old)       |   |                        |
          |              ^         V   V                        |
          |              |   [po4a updates po]                  |
          V              |           |                          V
   translation.pot       ^           V                          |
          |              |        doc.XX.po                     |
          |              |         (fuzzy)                      |
   { translation }       |           |                          |
          |              ^           V                          V
          |              |     {manual editing}                 |
          |              |           |                          |
          V              |           V                          V
      doc.XX.po --->---->+<---<-- doc.XX.po    addendum     master.doc
      (initial)                 (up-to-date)  (optional)   (up-to-date)
          :                          |            |             |
          :                          V            |             |
          +----->----->----->------> +            |             |
                                     |            |             |
                                     V            V             V
                                     +------>-----+------<------+
                                                  |
                                                  V
                                     [po4a updates translations]
                                                  |
                                                  V
                                                XX.doc
                                             (up-to-date)

Again, this schema is overly complicated. Check on po4a(1) for a simplified overview.

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

On the top right part, the action of the original author is depicted, updating the documentation. The middle right part depicts the automatic updates of translation files: the new material is extracted and compared against the exiting translation. The previous translation is used for the parts that didn't change, while partially modified parts are connected to the previous translation with a ``fuzzy'' marker indicating that the translation must be updated. New or heavily modified material is left untranslated.

Далі, пункт редагування вручну показує роботу перекладачів, які вносять зміни до файлів PO, перекладаючи усі початкові рядки або абзаци. Переклад можна здійснювати або за допомогою спеціалізованого редактора, зокрема Редактора перекладів GNOME або Lokalize з KDE або poedit, чи інтегрувати до платформи інтернет-перекладу, зокрема weblate або pootle. Результатом перекладу є набір файлів PO, по одному на кожну мову перекладу. Докладніший опис можна знайти у документації до gettext.

The bottom part of the figure shows how po4a creates a translated source document from the master.doc original document and the doc.XX.po translation catalog that was updated by the translators. The structure of the document is reused, while the original content is replaced by its translated counterpart. Optionally, an addendum can be used to add some extra text to the translation. This is often used to add the name of the translator to the final document. See below for details.

Upon invocation, po4a updates both the translation files and the translated documentation files automatically.

Starting a new translation project

If you start from scratch, you just have to write a configuration file for po4a, and you are set. The relevant templates are created for the missing files, allowing your contributors to translate your project to their language. Please refer to po4a(1) for a quick start tutorial and for all details.

If you have an existing translation, i.e. a documentation file that was translated manually, you can integrate its content in your po4a workflow using po4a-gettextize. This task is a bit cumbersome (as described in the tool's manpage), but once your project is converted to po4a workflow, everything will be updated automatically.

Updating the translations and documents

Once setup, invoking po4a is enough to update both the translation PO files and translated documents. You may pass the "--no-translations" to po4a to not update the translations (thus only updating the PO files) or "--no-update" to not update the PO files (thus only updating the translations). This roughly corresponds to the individual po4a-updatepo and po4a-translate scripts which are now deprecated (see ``Why are the individual scripts deprecated'' in the FAQ below).

Використання додатків для вставляння додаткового тексту до перекладів

Додавання нового тексту до перекладу є, ймовірно, єдиною дією, яку простіше виконувати, якщо ви перекладаєте файли вручну :). Додавання може знадобитися, якщо вам потрібно додати до перекладеного документа додатковий розділ, який не відповідає жодного з розділів у початковому документі. Класичним випадком є додавання подяк команді перекладачів та вставляння нотатки щодо того, як повідомляти про вади, які пов'язано із перекладом.

У інфраструктурі 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>

Here, po4a searches for the first line matching "<section"> after the line matching "About this document" in the translation, and add the addendum before that line since we provided a beginboundary, i.e. a boundary marking the beginning of the next section. So this header line requires placing the addendum after the section containing "About this document", and instruct po4a that a section starts with a line containing the "<section"> tag. This is equivalent to the previous example because what you really want is to add this addendum either after "/section"> or before "<section">.

Ви також можете встановити режим вставляння у значення "before", використовуючи подібну семантику "mode=before" з "endboundary" призведе до вставляння додатка одразу після відповідної межі, який є останнім потенційним обмежувальним рядком перед "position". Поєднання "mode=before" із "beginboundary" призведе до вставляння додатка одразу перед відповідною межею, яка є останнім потенційним обмежувальним рядком перед "position".

  Режим  |    Тип межі   |     Використана межа     | Точка вставляння відносно межі
 ========|===============|==========================|=======================================
 'before'| 'endboundary' | остання перед 'position' | Одразу після вибраної межі
 'before'|'beginboundary'| остання перед 'position' | Одразу перед вибраною межею
 'after' | 'endboundary' | перша після 'position'   | Одразу після вибраної межі
 'after' |'beginboundary'| перша після 'position'   | Одразу перед вибраною межею
 'eof'   |   (немає)     |  н/д                   | Кінець файла

Підказки і настанови щодо додатків

•

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

•

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

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

•

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

•

Щоб зрозуміти, як програма вставляє додаток у переклад, передайте po4a аргумент -vv. Також може бути корисним запуск po4a у режимі діагностики, щоб переглянути справжні внутрішні дані, якщо програма відмовляється вставляти ваш додаток.

Приклади додатків

•

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

  .SH "AUTHORS"

You should select a two-step approach by setting mode=after. Then you should narrow down search to the line after AUTHORS with the position argument regex. Then, you should match the beginning of the next section (i.e., ^\.SH) with the beginboundary argument regex. That is to say:

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

•

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

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

•

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

 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 АВТОР

Як усе це працює?

This chapter gives you a brief overview of the po4a internals, so that you may feel more confident to help us to maintain and to improve it. It may also help you to understand why it does not do what you expected, and how to solve your problems.

TransTractors and project architecture

At the core of the po4a project, the Locale::Po4a::TransTractor(3pm) class is the common ancestor to all po4a parsers. This strange name comes from the fact that it is at the same time in charge of translating document and extracting strings.

More formally, it takes a document to translate plus a PO file containing the translations to use as input while producing two separate outputs: Another PO file (resulting of the extraction of translatable strings from the input document), and a translated document (with the same structure as the input one, but with all translatable strings replaced with content of the input PO). Here is a graphical representation of this:

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

This little bone is the core of all the po4a architecture. If you provide both input and disregard the output PO, you get po4a-translate. If you disregard the output document instead, you get po4a-updatepo. The po4a uses a first TransTractor to get an up-to-date output POT file (disregarding the output documents), calls msgmerge -U to update the translation PO files on disk, and builds a second TransTractor with these updated PO files to update the output documents. In short, po4a provides one-stop solution to update what needs to be, using a single configuration file.

po4a-gettextize also uses two TransTractors, but another way: It builds one TransTractor per language, and then build a new PO file using the msgids of the original document as msgids, and the msgids of the translated document as msgstrs. Much care is needed to ensure that the strings matched this way actually match, as described in po4a-gettextize(1).

Format-specific parsers

All po4a format parsers are implemented on top of the TransTractor. Some of them are very simple, such as the Text, Markdown and AsciiDoc ones. They load the lines one by one using "TransTractor::shiftline()", accumulate the paragraphs' content or whatever. Once a string is completely parsed, the parser uses "TransTractor::translate()" to (1) add this string to the output PO file and (2) get the translation from the input PO file. The parser then pushes the result to the output file using "TransTractor::pushline()".

Some other parsers are more complex because they rely on an external parser to analyze the input document. The Xml, HTML, SGML and Pod parsers are built on top of SAX parsers. They declare callbacks to events such as ``I found a new title which content is the following'' to update the output document and output POT files according to the input content using "TransTractor::translate()" and "TransTractor::pushline()". The Yaml parser is similar but different: it serializes a data structure produced by the YAML::Tiny parser. This is why the Yaml module of po4a fails to declare the reference lines: the location of each string in the input file is not kept by the parser, so we can only provide ``$filename:1'' as a string location. The SAX-oriented parsers use globals and other tricks to save the file name and line numbers of references.

One specific issues arises from file encodings and BOM markers. Simple parsers can forget about this issue, that is handled by "TransTractor::read()" (used internally to get the lines of an input document), but the modules relying on an external parser must ensure that all files are read with an appropriate PerlIO decoding layer. The easiest is to open the file yourself, and provide an filehandle or directly the full string to your external parser. Check on "Pod::read()" and "Pod::parse()" for an example. The content read by the TransTractor is ignored, but a fresh filehandle is passed to the external parser. The important part is the "<:encoding($charset)" mode that is passed to the open() perl function.

Po objects

The Locale::Po4a::Po(3pm) class is in charge of loading and using PO and POT files. Basically, you can read a file, add entries, get translations with the gettext() method, write the PO into a file. More advanced features such as merging a PO file against a POT file or validating a file are delegated to msgmerge and msgfmt respectively.

Contributing to po4a

Even if you have never contributed to any Open Source project in the past, you are welcome: we are willing to help and mentor you here. po4a is best maintained by its users nowadays. As we lack manpower, we try to make the project welcoming by improving the doc and the automatic tests to make you confident in contributing to the project. Please refer to the CONTRIBUTING.md file for more details.

Проєкти із відкритим кодом, у яких використовується po4a

Це лише частина списку проєктів, у яких використовується po4a для роботи з документацією. Якщо хочете додати ваш проєкт до списку, просто надішліть ваше прохання електронною поштою (або створіть запит щодо об'єднання у сховищі з кодом).

•: adduser (man): інструмент для керування записами користувачів і груп.
•: apt (man, docbook): програма для керування пакунками Debian.
•: aptitude (docbook, svg): програма для керування пакунками у терміналі Debian
•: F-Droid website <https://gitlab.com/fdroid/fdroid-website> (markdown): installable catalog of FOSS (Free and Open Source Software) applications for the Android platform.
•: git <https://github.com/jnavila/git-manpages-l10n> (asciidoc): розподілена система керування версіями для стеження за змінами у початковому коді програм і документації.
•: Сторінки підручника Linux <https://salsa.debian.org/manpages-l10n-team/manpages-l10n> (man)
Цей проєкт надає інфраструктуру для перекладу багатьох сторінок підручника різними мовами. Результати інтегруються до декількох основних дистрибутивів (Arch Linux, Debian і похідні, Fedora).
•: Stellarium <https://github.com/Stellarium/stellarium> (HTML): вільний планетарій з відкритим кодом для вашого комп'ютера. po4a використовується для перекладу описів картин зоряного неба.
•: Jamulus <https://jamulus.io/> (markdown, yaml, HTML): a FOSS application for online jamming in real time. The website documentation is maintained in multiple languages using po4a.
•: Інші пункти для упорядковування: <https://gitlab.com/fdroid/fdroid-website/> <https://github.com/fsfe/reuse-docs/pull/61>

Поширені питання

Як вимовляти po4a?

Особисто автор вимовляє це як pouah <https://en.wiktionary.org/wiki/pouah>, — французький аналог нашого «пхе!» :) Можливо, в автора дивне почуття гумору :)

Why are the individual scripts deprecated?

Indeed, po4a-updatepo and po4a-translate are deprecated in flavor of po4a. The reason is that while po4a can be used as a drop-in replacement to these scripts, there is quite a lot of code duplication here. Individual scripts last around 150 lines of codes while the po4a program lasts 1200 lines, so they do a lot in addition of the common internals. The code duplication results in bugs occuring in both versions and needing two fixes. One example of such duplication are the bugs #1022216 in Debian and the issue #442 in GitHub that had the exact same fix, but one in po4a and the other po4a-updatepo.

In the long run, I would like to drop the individual scripts and only maintain one version of this code. The sure thing is that the individual scripts will not get improved anymore, so only po4a will get the new features. That being said, there is no deprecation urgency. I plan to keep the individual scripts as long as possible, and at least until 2030. If your project still use po4a-updatepo and po4a-translate in 2030, you may have a problem.

We may also remove the deprecation of these scripts at some point, if a refactoring reduces the code duplication to zero. If you have an idea (or better: a patch), your help is welcome.

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

Їх декілька. Нижче наведено неповний список. Існують плани щодо впровадження у декількох інших програмах.

poxml: Це програма, яку розроблено KDE для роботи із XML DocBook. Наскільки мені відомо, це була перша програма, яка видобувала рядки для перекладу з документації до файлів PO і вставляла ці рядки назад після перекладу.
Ця програма може працювати лише із форматом XML і лише з певним DTD. Мені не дуже подобається робота зі списками у ній, оскільки використання списків за певних умов призводить до створення величезних msgid. Якщо список дуже великий, перекладати його стає дуже складно.
po-debiandoc: Цю програму створено Денісом Барбьє (Denis Barbier) як певним чином попередницю модуля SGML po4a, який більшою чи меншою мірою зробив цю програму застарілою. Як можна зрозуміти з назви, програма здатна працювати лише з DTD DebianDoc, який є більшою чи меншою мірою застарілим DTD.
xml2po.py: Використовують у команді з документування GIMP з 2004 року. Працює доволі добре, незважаючи на те, що, як зрозуміло з назви, працює лише з файлами XML і потребує спеціально налаштованиих файлів make.
Sphinx: У проєкті з документування Sphinx також широко використовують gettext для керування перекладами. На жаль, це працює лише для декількох текстових форматів, rest та markdown, хоча, можливо, це єдиний інструмент, який може керувати усім процесом перекладу.

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

РЕЗЮМЕ щодо переваг заснованого на 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/

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

•: Addenda are somewhat strange at the first glance.
•: Ви не можете адаптувати перекладений текст згідно до власних уподобань, зокрема поділити абзац на два або з'єднати два абзаци. Втім, у певному сенсі, потреба у таких змінах означає ваду у початковому тексті, — про неї усе одно довелося б повідомити авторові тексту.
•: Навіть із простим інтерфейсом, цей інструмент залишатиметься новим, таким, роботі з яким слід навчатися.
Однією з моїх мрій є інтеграція po4a до Gtranslator або Lokalize. При відкритті файла документації програма автоматично б видобувала рядки для перекладу, а перекладений файл і файл po записувала б на диск. Якщо б нам вдалося створити модуль MS Word™ (принаймні модуль для RTF), такою комбінацією модуля з програмами для перекладу могли б користуватися навіть професійні перекладачі.

ТАКОЖ ПЕРЕГЛЯНЬТЕ

•: Документація до універсального інструмента, яким вам слід користуватися: po4a(1).
•: Документація до окремих скриптів po4a: po4a-gettextize(1), po4a-updatepo(1), po4a-translate(1), po4a-normalize(1).
•: Додаткові допоміжні скрипти: msguntypot(1), po4a-display-man(1), po4a-display-pod(1).
•: Обробники для усіх форматів, зокрема для перегляду параметрів, які приймає кожен з них: Locale::Po4a::AsciiDoc(3pm) Locale::Po4a::Dia(3pm), Locale::Po4a::Guide(3pm), Locale::Po4a::Ini(3pm), Locale::Po4a::KernelHelp(3pm), Locale::Po4a::Man(3pm), Locale::Po4a::RubyDoc(3pm), Locale::Po4a::Texinfo(3pm), Locale::Po4a::Text(3pm), Locale::Po4a::Xhtml(3pm), Locale::Po4a::Yaml(3pm), Locale::Po4a::BibTeX(3pm), Locale::Po4a::Docbook(3pm), Locale::Po4a::Halibut(3pm), Locale::Po4a::LaTeX(3pm), Locale::Po4a::Pod(3pm), Locale::Po4a::Sgml(3pm), Locale::Po4a::TeX(3pm), Locale::Po4a::Wml(3pm), Locale::Po4a::Xml(3pm).
•: Реалізація базової інфраструктури: Locale::Po4a::TransTractor(3pm) (частково важливо розуміти організацію коду), Locale::Po4a::Chooser(3pm), Locale::Po4a::Po(3pm), Locale::Po4a::Common(3pm). Будь ласка, ознайомтеся також із файлом CONTRIBUTING.md у дереві початкового коду.

АВТОРИ

 Denis Barbier <barbier,linuxfr.org>
 Martin Quinson (mquinson#debian.org)

Index

НАЗВА

Вступ

Чому po4a?

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

Користування po4a

Detailed schema of the po4a workflow
Starting a new translation project
Updating the translations and documents
Використання додатків для вставляння додаткового тексту до перекладів

Як усе це працює?

TransTractors and project architecture
Format-specific parsers
Po objects
Contributing to po4a

Проєкти із відкритим кодом, у яких використовується po4a

Поширені питання

Як вимовляти po4a?
Why are the individual scripts deprecated?
Як щодо інших засобів перекладу документації, де використовується gettext?
РЕЗЮМЕ щодо переваг заснованого на gettext підходу

ТАКОЖ ПЕРЕГЛЯНЬТЕ

АВТОРИ

This document was created by using the manual pages.
Time: 00:28:49 GMT, January 29, 2024

po4av0.70

PO4A

НАЗВА

Вступ

Чому po4a?

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

Користування po4a

Detailed schema of the po4a workflow

Starting a new translation project

Updating the translations and documents

Використання додатків для вставляння додаткового тексту до перекладів

Як усе це працює?

TransTractors and project architecture

Format-specific parsers

Po objects

Contributing to po4a

Проєкти із відкритим кодом, у яких використовується po4a

Поширені питання

Як вимовляти po4a?

Why are the individual scripts deprecated?

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

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

ТАКОЖ ПЕРЕГЛЯНЬТЕ

АВТОРИ

Index

po4a^v0.70