po4a

НАЗВАНИЕ

po4a - платформа для перевода документации и других материалов

Введение

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

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

Почему именно po4a?

Философия свободного программного обеспечения (ПО) состоит в том, чтобы сделать технологии по-настоящему доступными всем. Но лицензирование — это не единственное, о чём стоит задуматься: непереведённое свободное ПО бесполезно для неанглоговорящих пользователей. И нам предстоит ещё кое-какая работа, чтобы сделать его доступным по-настоящему для всех.

Эта ситуация хорошо понятна большинству проектов, и все сейчас убеждены в необходимости переводить все. Тем не менее, фактические переводы представляют собой огромную работу многих людей, которая осложняется небольшими техническими трудностями.

К счастью, у ПО с открытым исходным кодом достаточно хорошие переводы, которые удобно поддерживать благодаря инструментам из пакета gettext. Они извлекают строки для перевода из программ, и предоставляют их переводчикам в единообразном формате (называемом PO-файлы, или translation catalogs, каталоги переводов).Целая экосистема различных инструментов выросла вокруг оных, дабы помочь переводчикам собственно переводить эти PO-файлы. Результат их работы затем используется библиотекой gettext во время исполнения программы, чтобы отображать переведённые сообщения пользователю.

Что касается документации, то здесь ситуация все еще несколько неутешительна. Поначалу перевод документации может показаться проще, чем перевод программы, поскольку кажется, что нужно просто скопировать исходный файл документации и начать переводить содержимое. Однако, когда в исходную документацию вносятся изменения, отслеживание этих изменений быстро превращается в кошмар для переводчиков. Если выполнять эту задачу вручную, она становится неприятной и чреватой ошибками.

Устаревшие переводы часто хуже, чем отсутствие перевода вообще. Конечные пользователи могут быть обмануты документацией, описывающей старое поведение программы. Более того, они не могут напрямую взаимодействовать с сопровождающими, поскольку те не говорят по-английски. Кроме того, сопровождающий не может устранить проблему, поскольку не знает всех языков, на которые переведена документация. Эти трудности, часто вызванные плохим инструментарием, могут подорвать мотивацию добровольных переводчиков, что еще больше усугубляет проблему.

Цель проекта po4a - облегчить работу переводчиков документации. В частности, он делает переводы документации поддерживаемыми.

Идея заключается в повторном использовании и адаптации подхода gettext к этой области. Как и в gettext, тексты извлекаются из оригинальных мест и представляются переводчикам в виде каталогов переводов PO. Переводчики могут использовать классические инструменты gettext для контроля за выполнением работы, сотрудничества и организации команд. po4a затем вставляет переводы непосредственно в структуру документации для создания переведенных исходных файлов, которые можно обрабатывать и распространять так же, как и английские файлы. Любой абзац, который не переведен, остается на английском языке в итоговом документе, гарантируя, что конечные пользователи никогда не увидят в документации устаревший перевод.

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

Полный список достоинств и недостатков этого подхода перечислен в разделе « Часто задаваемые вопросы» ниже в этом документе.

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

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

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 был построен на основе четырех скриптов, каждый из которых выполнял определенную задачу. po4a-gettextize(1) помогает загружать переводы и, по желанию, конвертировать существующие проекты переводов в po4a. po4a-updatepo(1) отражает изменения в оригинальной документации в соответствующих po-файлах. po4a-translate(1) создает переведенный исходный файл из исходного файла и соответствующего PO-файла. Кроме того, po4a-normalize(1) в основном полезен для отладки парсеров po4a, так как он создает непереведенный документ из исходного. Это облегчает поиск ошибок, вносимых процессом синтаксического анализа.

Most projects only require the features of po4a-updatepo(1) and po4a-translate(1), but these scripts proved to be cumbersome and error prone to use. If the documentation to translate is split over several source files, it is difficult to keep the PO files up to date and build the documentation files correctly. As an answer, a all-in-one tool was provided: po4a(1). This tool takes a configuration file describing the structure of the translation project: the location of the PO files, the list of files to translate, and the options to use, and it fully automates the process. When you invoke po4a(1), it both updates the PO files and regenerate the translation files that need to. If everything is already up to date, po4a(1) does not change any file.

В остальной части этого раздела приводится обзор использования интерфейса скриптов po4a. Большинство пользователей, вероятно, предпочтут использовать инструмент "все в одном", который описан в документации po4a(1).

Наглядный обзор сценариев 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 <[email protected]>

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

 |PO4A-HEADER:mode=after;position=АВТОР;beginboundary=^=head
 |
 |=head1 ПЕРЕВОД
 |
 |Я <[email protected]>
 |

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

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

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

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

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

Как это работает?

В этой главе даётся краткий обзор внутренних компонентов po4a так, чтобы вы могли чувствовать себя увереннее, если вы захотите помочь нам сопровождать и улучшать его. Это также может помочь вам понять, почему он не делаете того, что вы ожидали, и как решить ваши проблемы.

Архитектура po4a объектно-ориентирована. Общим предком всех классов-парсеров po4a является Locale::Po4a::TransTractor(3pm). Своё странное имя он получил оттого, что он одновременно отвечает и за перевод документа и извлечение строк.

Если точнее, TransTractor берёт документ для перевода плюс PO-файл с переводами, кои являются его входными данными, и производит два отдельных набора выходных данных: другой PO-файл (как результат извлечения переводимых строк из входного документа) и переведённый документ (с той же структурой, что и входной, но со всеми переводимыми строками заменёнными содержимым входного PO-файла). Ниже приведено графическое представление этого процесса:

   Входной документ -\                            /---> Выходной документ
                      \      TransTractor::      /       (переведённый)
                      +-->--   parse()  --------+
                     /                           \
   Входной PO ------/                             \---> Выходной PO
                                                         (извлечённый)

Эта маленькая косточка и является ядром всей архитектуры po4a. Если вы уберёте входной PO и выходной документ, вы получите po4a-gettextize. Если предоставите оба набора входных данных и проигнорируете выходной PO, вы получите po4a-translate. po4a вызывает TransTractor дважды и вызывает msgmerge -U между оными вызовами, дабы это было комплексное решение с одним файлом настроек. См. подробности в Locale::Po4a::TransTractor(3pm).

Проекты с открытым исходным кодом, использующие po4a

Here is a very partial list of projects that use po4a in production for their documentation. If you want to add your project to the list, just drop us an email (or a Merge Request).

•: adduser (man): инструмент по управлению пользователями и группами.

•: apt (man, docbook): менеджер пакетов Debian.

•: aptitude (docbook, svg): консольный менеджер пакетов для Debian

•: F-Droid website <https://gitlab.com/fdroid/fdroid-website> (markdown): устанавливаемый каталог свободных и открытых приложений (Free and Open Source Software) для платформы Android.

•: git <https://github.com/jnavila/git-manpages-l10n> (asciidoc): распределённая система контроля изменений исходного кода.

•: Linux manpages <https://salsa.debian.org/manpages-l10n-team/manpages-l10n> (man) This project provides an infrastructure for translating many manpages to different languages, ready for integration into several major distributions (Arch Linux, Debian and derivatives, Fedora).

•: Stellarium <https://github.com/Stellarium/stellarium> (HTML): a free open source planetarium for your computer. po4a is used to translate the sky culture descriptions.

•: Other item to sort out: <https://gitlab.com/fdroid/fdroid-website/> <https://github.com/fsfe/reuse-docs/pull/61>

Часто задаваемые вопросы

Как вы произносите 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.

СМОТРИТЕ ТАКЖЕ

•: The documentation of the all-in-one tool that you should use: po4a(1).

•: Документация отдельных сценариев po4a: po4a-gettextize(1), po4a-normalizeupdatepo(1), po4a-translate(1), po4a(7- normalize(1).

•: The additional helping scripts: 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).

•: The implementation of the core infrastructure: Locale::Po4a::TransTractor(3pm) (particularly important to understand the code organization), Locale::Po4a::Chooser(3pm), Locale::Po4a::Po(3pm), Locale::Po4a::Common(3pm). Please also check the CONTRIBUTING.md file in the source tree.

АВТОРЫ

 Денис Барбье (Denis Barbier) <barbier,linuxfr.org>
 Мартин Кенсон (Martin Quinson) (mquinson#debian.org)

2023-01-03

НАЗВАНИЕ

Введение

Почему именно po4a?

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

Использование po4a

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

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

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

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

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

Как это работает?

Проекты с открытым исходным кодом, использующие po4a

Часто задаваемые вопросы

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

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

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

СМОТРИТЕ ТАКЖЕ

АВТОРЫ

Recommended readings

Questions & Answers