Поддерживаемые форматы

На данный момент этот подход был успешно воплощён для нескольких форматов:

man (зрелый парсер)

Старый добрый формат man-страниц, который используют так много программ. Поддержка po4a приходится здесь очень кстати, ибо этот формат в некоторой степени сложен, и не особо дружелюбен к новичкам.

Модуль Locale::Po4a::Man(3pm) также поддерживает формат mdoc, используемый в BSD man pages (они также довольно распространены в Linux).

AsciiDoc (зрелый парсер)

Этот формат представляет собой легкий формат разметки, предназначенный для облегчения составления документации. Например, он используется для документирования системы git. Эти manpages переведены с помощью po4a.

Подробнее см. в разделе Locale::Po4a::AsciiDoc.

pod (зрелый парсер)

Это формат встроенной документации языка Perl (Perl Online Documentation). Сам язык и его расширения документируются с помощью этого формата, а также и большинство существующих сценариев perl. Это делает проще поддержать документацию близкой к исходному коду, так как они вместе находятся в одном и том же файле. Это делает проще жизнь программиста, но, к сожалению, не жизнь переводчика.

Подробнее см. в разделе Locale::Po4a::Pod.

sgml (зрелый парсер)

Даже если он и заменён XML в наши дни, этот формат всё ещё используется в тех документах, что длиннее нескольких экранов. Он может даже использоваться для целых книг. Обновление переводов таких длинных документов может быть настоящим вызовом. В частности, diff зачастую показывает себя абсолютно бесполезным, когда в исходном тексте изменяются отступы после обновления. К счастью, po4a может с этим помочь.

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

TeX / LaTeX (зрелый парсер)

Формат LaTeX — это основной формат публикаций, используемый в мире Свободного ПО.

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

text (зрелый парсер)

Формат Text является базовым для многих форматов, включающих длинные блоки текста, включая Markdown, fortunes, YAML front matter section, debian/changelog и debian/control.

Поддерживает общий формат, используемый в генераторах статических сайтов, README и других системах документации. Подробности смотрите в разделе Locale::Po4a::Text(3pm).

xml and XHMTL (похоже, зрелый парсер)

Формат XML является базовым для многих форматов документации.

На данный момент, po4a поддерживает DocBook DTD (cм. 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 (похоже, зрелый парсер)

Язык веб-разметки, не путайте WML с WAP, используемым в мобильных телефонах. Этот модуль основан на модуле Xhtml, который сам основан на модуле XmL.

Более подробную информацию смотрите в разделе Locale::Po4a::Wml.

Yaml (похоже, зрелый парсер)

Строгий суперсет JSON. YAML часто используется в качестве системных или конфигурационных проектов. YAML лежит в основе программы Ansible компании Red Hat.

Более подробную информацию см. в разделе Locale::Po4a::Yaml.

RubyDoc (похоже, зрелый парсер)

Формат Ruby Document (RD), первоначально формат документации по умолчанию для Ruby и Ruby-проектов до преобразования в RDoc в 2002 году. Хотя, по-видимому, японская версия справочного руководства по Ruby все еще использует RD.

Более подробную информацию см. в разделе Locale::Po4a::Yaml.

Halibut (похоже, экспериментальный парсер)

Система создания документации, с элементами, похожими на TeX, debiandoc-sgml, TeXinfo и другие, разработанная Саймоном Тэтхемом, разработчиком 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 всё ещё нет поддержки нескольких форматов документации. Поддержку многих из них было бы не так сложно добавить. И это включает не только форматы документации, но и, например, описание пакетов (deb и rpm), вопросы, задаваемые интерактивными сценариями установки пакетов, файлы changelogs для пакетов, и все специализированные форматы файлов, которые используются в программах, такие как сценарии игр или файлы ресурсов wine.

Наглядный обзор сценариев po4a

Следующая схема дает представление о том, как можно использовать каждый сценарий po4a. Здесь master.doc - это пример названия документации, подлежащей переводу; XX.doc - это тот же документ, переведенный на язык XX, а doc.XX.po - это каталог переводов для этого документа на язык XX. Авторы документации в основном будут иметь дело с master.doc (который может быть manpage, XML-документом, файлом asciidoc или подобным); переводчики в основном будут иметь дело с PO-файлом, а конечные пользователи будут видеть только файл XX.doc.

                                   мастер.doc
                                       |
                                       V
      +<----<----+<-----<-----<--------+------->-------->-------+
      :          |                     |                        :
   {перевод}     |         { обновление мастер.doc }            :
      :          |                     |                        :
    XX.doc       |                     V                        V
(необязательно)  |                 мастер.doc ->-------->------>+
      :          |                  (новый)                     |
      V          V                     |                        |
  [po4a-gettextize]   doc.XX.po -->+   |                        |
          |           (старый)     |   |                        |
          |              ^         V   V                        |
          |              |     [po4a-updatepo]                  |
          V              |           |                          V
      перевод.pot        ^           V                          |
          |              |        doc.XX.po                     |
          |              |       (неточный)                     |
     { перевод }         |           |                          |
          |              ^           V                          V
          |              | {ручное редактирование}              |
          |              |           |                          |
          V              |           V                          V
      doc.XX.po --->---->+<---<-- doc.XX.po    дополнение     мастер.doc
     (начальный)                (актуальный) (необязательно) (актуальный)
          :                          |            |             |
          :                          V            |             |
          +----->----->----->------> +            |             |
                                     |            |             |
                                     V            V             V
                                     +------>-----+------<------+
                                                  |
                                                  V
                                           [po4a-translate]
                                                  |
                                                  V
                                                XX.doc
                                             (актуальный)

Эта схема сложна, но на практике только правая часть (включающая po4a-updatepo(1) и po4a-translate(1)) используется после установки и настройки проекта.

В левой части показано, как po4a-gettextize(1) можно использовать для преобразования существующего проекта перевода в инфраструктуру po4a. Этот скрипт берет оригинальный документ и его переведенный аналог и пытается построить соответствующий PO-файл. Такое ручное преобразование довольно громоздко (подробнее см. документацию po4a-gettextize(1)), но оно необходимо только один раз для преобразования существующих переводов. Если у вас нет переводов для преобразования, вы можете забыть об этом и сосредоточиться на нужной части схемы.

В верху правой части, изображены действия автора оригинала — обновление документации. В середине правой части показывает автоматические действия, производимые po4a-updatepo(1). Новые материалы извлекаются и сравниваются с существующим переводом. Для тех частей, которые не были изменены используется уже существующий перевод, а те части, которые были изменены частично соединяются с уже существующим переводом, но с пометкой «неточно» (fuzzy), указывающей, что перевод должен быть обновлён. Новые или сильно изменённые части оказываются непереведёнными.

Затем, в разделе ручное редактирование описываются действия переводчиков, которые изменяют файлы PO, чтобы обеспечить перевод каждой оригинальной строки и абзаца. Это может быть сделано с помощью специального редактора, такого как GNOME Translation Editor, KDE's Lokalize или poedit, или с помощью онлайн-платформы локализации, такой как weblate или pootle. Результатом перевода является набор PO-файлов, по одному на каждый язык. Более подробную информацию см. в документации gettext.

В нижней части рисунка показано, как po4a-translate(1) создает переведенный исходный документ из исходного документа master.doc и каталога переводов doc.XX.po, который был обновлен переводчиками. Структура документа используется повторно, а оригинальное содержание заменяется его переведенным аналогом. По желанию можно использовать дополнение, чтобы добавить к переводу дополнительный текст. Это часто используется для добавления имени переводчика в окончательный документ. Подробности см. ниже.

Как уже отмечалось, программа po4a(1) объединяет результаты отдельных сценариев, обновляя PO-файлы и переведенный документ за один вызов. Основополагающая логика остается прежней.

Начало нового перевода

Если вы используете po4a(1), то для начала перевода не требуется никаких специальных шагов. Вам просто нужно перечислить языки в конфигурационном файле, и недостающие PO-файлы будут созданы автоматически. Естественно, переводчик должен будет затем предоставить переводы для каждого содержимого, используемого в ваших документах. po4a(1) также создает файл POT, то есть файл шаблона PO. Потенциальные переводчики могут перевести ваш проект на новый язык, переименовав этот файл и предоставив переводы на своем языке.

Если вы предпочитаете использовать отдельные скрипты по отдельности, то для создания файла POT следует использовать po4a-gettextize(1) следующим образом. Затем этот файл можно скопировать в XX.po, чтобы инициировать новый перевод.

  $ po4a-gettextize --format <формат> --master <мастер.doc> --po <переводы.pot>

Мастер-документ используется на входе, а файл POT является выходом этого процесса.

Интеграция изменений в исходный документ

Для этого следует использовать скрипт po4a-updatepo(1) (подробности см. в документации к нему):

  $ po4a-updatepo --format <формат> --master <новый_мастер.doc> --po <старый_doc.XX.po>

Мастер-документ используется на входе, а файл PO обновляется: он используется как на входе, так и на выходе.

Генерация переведённого документа

Когда вы закончите с переводом, вы захотите получить переведённую документацию и распространять её своим пользователям вместе с оригиналом. Для этого используйте программу po4a-translate(1) следующим образом:

  $ po4a-translate --format <формат> --master <мастер.doc> --po <doc.XX.po> --localized <XX.doc>

Мастер-документ и PO файлы используются на входе, а локализованный файл является выходом этого процесса.

Использование дополнений для добавления дополнительного текста к переводам

Добавление нового текста в перевод - это, пожалуй, единственное, что в долгосрочной перспективе проще, когда вы переводите файлы вручную :). Это происходит, когда вы хотите добавить в переведенный документ дополнительный раздел, не соответствующий какому-либо содержанию в оригинальном документе. Классический вариант использования - отдать должное команде переводчиков и указать, как сообщать о проблемах, связанных с переводом.

В po4a необходимо указать файлы addendum, которые концептуально можно рассматривать как патчи, накладываемые на локализованный документ после обработки. Каждое дополнение должно быть представлено в виде отдельного файла, формат которого, однако, сильно отличается от классических патчей. Первая строка - это строка заголовка, определяющая точку вставки дополнения (с, к сожалению, загадочным синтаксисом - см. ниже), в то время как остальная часть файла добавляется дословно в определенную позицию.

Строка заголовка должна начинаться со строки PO4A-HEADER:, за которой следует список полей key=value, разделенных запятой.

Например, следующий заголовок объявляет о дополнении, которое должно быть помещено в самый конец перевода.

 PO4A-HEADER: mode=eof

Things are more complex when you want to add your extra content in the middle of the document. The following header declares an addendum that must be placed after the XML section containing the string "About this document" in translation.

 PO4A-HEADER: position=Об этом документе; mode=after; endboundary=</section>

In practice, when trying to apply an addendum, po4a searches for the first line matching the "position" argument (this can be a regexp). Do not forget that po4a considers the translated document here. This documentation is in English, but your line should probably read as follows if you intend your addendum to apply to the French translation of the document.

 PO4A-HEADER: position=À propos de ce document; mode=after; endboundary=</section>

Once the "position" is found in the target document, po4a searches for the next line after the "position" that matches the provided "endboundary". The addendum is added right after that line (because we provided an endboundary, i.e. a boundary ending the current section).

The exact same effect could be obtained with the following header, that is equivalent:

 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 to place 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">.

You can also set the insertion mode to the value "before", with a similar semantic: combining "mode=before" with an "endboundary" will put the addendum just after the matched boundary, that the last potential boundary line before the "position". Combining "mode=before" with an "beginboundary" will put the addendum just before the matched boundary, that the last potential boundary line before the "position".

  Mode   | Boundary kind |     Used boundary      | Insertion point compared to the boundary
 ========|===============|========================|=========================================
 'before'| 'endboundary' | last before 'position' | Right after the selected boundary
 'before'|'beginboundary'| last before 'position' | Right before the selected boundary
 'after' | 'endboundary' | first after 'position' | Right after the selected boundary
 'after' |'beginboundary'| first after 'position' | Right before the selected boundary
 'eof'   |   (none)      |  n/a                   | End of file

Советы и хитрости при использовании дополнений

• Запомните, что это регулярные выражения. Например, если вы хотите сопоставить конец секции nroff, которая заканчивается строкой ".fi", то не используйте ".fi" как endboundary, ибо в данном случае также будет сопоставлена строка "the[ fi]le", что, очевидно, не то, что вы ожидаете. Правильный endboundary в этом случае будет: "^\.fi$".
• White spaces ARE important in the content of the "position" and boundaries. So the two following lines are different. The second one will only be found if there is enough trailing spaces in the translated document.

   PO4A-HEADER: position=Об этом документе; mode=after; beginboundary=<section>
   PO4A-HEADER: position=Об этом документе ; mode=after; beginboundary=<section>
      

• Хотя и можно считать, что этот контекстный поиск, грубо говоря, перебирает текст перевода построчно, но на самом деле он работает со строками во внутреннем представлении данных документов. Этой строкой может быть, например, текст целого абзаца, разбитый на несколько фактических строк или один XML-тег сам по себе. Непосредственная точка вставки дополнения должна быть до или после такой строки во внутреннем представлении и не может быть вставлена в середину оной.
• Pass the -vv argument to po4a to understand how the addenda are added to the translation. It may also help to run po4a in debug mode to see the actual internal data string when your addendum does not apply.

Примеры дополнений

• Если вы хотите добавить что-то после следующего раздела nroff (формат man-страниц):

    .SH "АВТОРЫ"
      

  Вам следует выбрать подход с двумя регулярными выражениями, т.е. задать mode=after. Затем сузьте поиск до строк идущих после АВТОРЫ с помощью регулярного выражения в аргументе position. После этого вы должны сопоставить начало следующей секции (например, с помощью ^\.SH) в аргументе beginboundary. Короче говоря:

   PO4A-HEADER: mode=after; position=АВТОРЫ; beginboundary=\. SH
      

• Если вы хотите добавить что-то сразу после конкретной строки (например, после «Copyright Большая Шишка»), используйте значение position, соответствующее этой строке, задайте mode=after, а beginboundary — значение, соответствие любой строке.

   PO4A-HEADER:mode=after;position=Copyright Большая Шишка, 2004;beginboundary=^
      

• Если вы хотите добавить что-то в конец документа, то присвойте position регулярное выражение, сопоставляемое любой строке вашего документа (но только одна строке; po4a выдаст ошибку, если она будет не уникальна), и задайте endboundary не соответствующее ни чему. Лучше не использовать здесь простые строки, например "EOF", а отдать предпочтение тем, у которых меньше шансов оказаться в вашем документе.

   PO4A-HEADER:mode=after;position=О программе;beginboundary=FakePo4aBoundary
      

Более подробный пример

Исходный документ (формат POD):

 |=head1 NAME
 |
 |dummy - a dummy program
 |
 |=head1 AUTHOR
 |
 |Me <me@example.com>

Тогда следующее дополнение обеспечит добавление раздела о переводчике (на русском) в конец файла.

 |PO4A-HEADER:mode=after;position=АВТОР;beginboundary=^=head
 |
 |=head1 ПЕРЕВОД
 |
 |Я <me@example.ru>
 |

Чтобы поместить своё дополнение перед «АВТОР», используйте следующий заголовок:

 PO4A-HEADER:mode=after;position=ИМЯ;beginboundary=^=head1

Это работает, так как следующая сопоставляемая beginboundary /^=head1/ строка после раздела «NAME» (переведённого как «ИМЯ» на русский) и начинает раздел с перечислением авторов. Таким образом, дополнение будет помещено между этими двумя разделами. Заметьте, что если в дальнейшем какой-либо другой раздел будет добавлен между разделами «ИМЯ» и «АВТОР», то данный пример будет работать не корректно, ибо дополнение будет вставляться перед этим новым разделом.

Чтобы избежать этого, можете использовать аналогичный заголовок с mode=before:

 PO4A-HEADER:mode=before;position=^=head1 АВТОР

Как вы произносите po4a?

I personally vocalize it as pouah <https://en.wiktionary.org/wiki/pouah>, which is a French onomatopoetic that we use in place of yuck :) I may have a strange sense of humor :)

Как насчёт других инструментов перевода документации, использующих gettext?

There are a few of them. Here is a possibly incomplete list, and more tools are coming at the horizon.

poxml

Это инструмент, разработанный командой KDE для работы с DocBook XML. На сколько я знаю, это была первая программа, которая извлекала переводимые строки из документации в PO-файлы и подставляла их обратно после перевода.

Она может обрабатывать только XML и только с определённым DTD. Мне не очень нравится, как она обрабатывает списки, которые представляются одним большим msgid. Когда список становится большим, весь этот кусок становится сложно переработать.

po-debiandoc

Эта программа, созданная Денисом Барбье, является своего рода предшественником модуля SGML в po4a, который более или менее делает её устаревшей. Как становится ясно из названия, она обрабатывает только DTD DebianDoc, который также относительно устарел.

xml2po.py

Used by the GIMP Documentation Team since 2004, works quite well even if, as the name suggests, only with XML files and needs specially configured makefiles.

Sphinx

The Sphinx Documentation Project also uses gettext extensively to manage its translations. Unfortunately, it works only for a few text formats, rest and markdown, although it is perhaps the only tool that does this managing the whole translation process.

Основные преимущества po4a перед оными — это простота добавления дополнительного содержипого (по крайней мере там это реализовано ещё хуже) и возможность проведения геттекстизации.

РЕЗЮМЕ преимуществ подхода, основанного на gettext

• Переводы хранятся отдельно от оригиналов, что позволяет определить, устарели ли первые.
• Переводы на разные языки хранятся в отдельных файлах, что не даёт разноязычным переводчикам мешать друг другу, как при отправке ими патчей, так и на уровне кодировок файлов.
• Внутренне устройство основано на gettext (но po4a предлагает простой интерфейс, так что вам не нужно понимать его внутреннее устройство, чтобы просто пользоваться им). Таким образом, нам не приходится заново изобретать колесо, а, так как gettext широко используется, мы можем считать, что в нём остаётся относительно мало программных ошибок.
• Для конечного пользователя ничего не меняется (помимо того факта, что, надо надеяться, перевод будет лучше поддерживаться). Полученный файл документации распространяется точно так же.
• Переводчикам не нужно изучать новый синтаксис файлов, и их любимого редактора PO-файлов (например, PO-режим Emacs, Lokalize или Gtranslator) будет вполне достаточно.
• gettext предлагает простой способ получить статистику о том, что готово, что должно быть проверено и обновлено, а что ещё предстоит сделать. Некоторые примеры можно найти по следующим ссылкам:

   - https://docs.kde.org/stable5/en/kdesdk/lokalize/project-view.html
   - http://www.debian.org/intl/l10n/
      

Но не всё так радужно, и этот подход также имеет некоторые недостатки, с которыми нам приходится смириться.

• Дополнения… странные на первый взгляд.
• Вы не можете приспособить переведённый текст к своим предпочтениям, например, разделить какой-то абзац здесь-то или объединили два в один там-то. Но в некотором смысле, если есть проблема в оригинале, об этом должно быть сообщено, как об ошибке.
• Даже при том, что интерфейс является простым, po4a остаётся новым инструментом, который людям придётся изучать.

  Одна моя мечта состоит в том, чтобы каким-то образом интегрировать po4a в Gtranslator или Lokalize. Тогда при открытии файла документации, строки автоматически извлекались бы, а когда он сохранялся, переведённый файл и PO-файл мог ли бы записываться на диск. Если бы нам удалось сделать модуль MS Word (TM) (или, по крайней мере, RTF), то даже профессиональные переводчики могли бы использовать po4a.