вторник, 22 декабря 2009 г.

Легкий перевод страниц руководства с помощью po4a

Страницы руководства (man'ы) переводить тяжело. Ещё тяжелее поддерживать перевод в актуальном состоянии. Тяжело потому, что нужно изучать разметку по шаблону groff_man и при переводе нужно выискивать среди директив и управляющих последовательностей сам текст, который нужно перевести. Можно, конечно, сконвертировать страницу руководства в текстовый формат, перевести, а потом проставить разметку по аналогии с исходным текстом. Но представьте объём и муторность работы! Проделав всё это хотя бы раз с одним большим переводом, вы решите больше не заниматься этой неблагодарной работой.

Примерно год назад я тоже попробовал сконвертировать несколько текстовых переводов в формат man вручную. Я попробовал, ужаснулся и решил больше этим не заниматься, а стал просто выкладывать переводы в wiki-систему: http://manpages.ylsoftware.com. Всё это время я надеялся на то, что когда-нибудь они кому-то пригодятся, если повезёт, то кто-нибудь возьмётся сконвертировать их в подобающий формат, отправит разработчикам соответствующих программ или ментейнерам и мои переводы попадут в дистрибутивы.

Несколько месяцев назад я даже написал на PHP простенький конвертер из wiki-формата в man, но разметка некоторых кусков wiki-формата оставалась по-прежнему недоступной регэкспам конвертера и переводы всё-же необходимо было доводить до готовности вручную. Ещё один минус такого подхода заключается в том, что перевод не соответствует оригинальной странице руководства из дистрибутива и поддерживать его актуальность по-прежнему тяжело.

Но теперь я нашёл великолепный пакет, с помощью которого можно с легкостью переводить и поддерживать актуальность переводов страниц руководства. Это пакет po4a - Portable Object For Anything. Он имеется в составе дистрибутива Debian и я считаю очень странным то, что о нём нет ни одного упоминания на русском языке (а англоговорящим людям этот пакет и не нужен). Поставим пакет:
# aptitude install po4a
Этот пакет позволяет переводить тексты в следующих форматах:
$ po4a-gettextize --help-format
Список допустимых форматов:
- dia: несжатые диаграммы Dia.
- docbook: Docbook XML.
- guide: формат документации Gentoo Linux xml.
- ini: формат .INI.
- kernelhelp: описание каждого параметра компиляции ядра.
- latex: формат LaTeX.
- man: формат страниц руководства.
- pod: формат документации языка Perl.
- sgml: форматы debiandoc или docbook DTD.
- texinfo: формат страницы info.
- tex: обобщенные документы TeX (смотрите также latex).
- text: простой текстовый документ.
- wml: WML documents.
- xhtml: документы XHTML.
- xml: обобщенные документы XML (смотрите также docbook).
Перевод обычных файлов HTML не поддерживается, они обязательно должны быть приведены к формату XHTML.

Приступим к созданию проекта перевода страниц руководства. Перво-наперво поставим пакет, страницы из которого мы будем переводить:
# aptitude install pppoe
Теперь создадим каталог для проекта перевода:
$ mkdir pppoe
Скопируем страницы руководства из системы в этот каталог и распакуем их:
$ cd pppoe
$ dpkg -L pppoe | grep man | xargs -I {} cp {} .
$ gunzip *
Теперь напишем файл конфигурации проекта po4a.conf:
[po4a_langs] ru
[po4a_paths] pppoe.pot ru:pppoe.ru.po
[type: man] pppoe.8 ru:pppoe.ru.8 add_ru:pppoe.ru.8.add
[type: man] pppoe-connect.8 ru:pppoe-connect.ru.8 add_ru:pppoe-connect.ru.8.add
[type: man] pppoe-start.8 ru:pppoe-start.ru.8 add_ru:pppoe-start.ru.8.add
[type: man] pppoe-stop.8 ru:pppoe-stop.ru.8 add_ru:pppoe-stop.ru.8.add
[type: man] pppoe-status.8 ru:pppoe-status.ru.8 add_ru:pppoe-status.ru.8.add
[type: man] pppoe-sniff.8 ru:pppoe-sniff.ru.8 add_ru:pppoe-sniff.ru.8.add
[type: man] pppoe-server.8 ru:pppoe-server.ru.8 add_ru:pppoe-server.ru.8.add
[type: man] pppoe-relay.8 ru:pppoe-relay.ru.8 add_ru:pppoe-relay.ru.8.add
[type: man] pppoe-setup.8 ru:pppoe-setup.ru.8 add_ru:pppoe-setup.ru.8.add
Первая строка перечисляет список кодов языков, на которые будем осуществлять перевод. Можно переводить на несколько языков сразу, но мы укажем только русский язык.

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

В последующих строках указываются формат переводимого документа, сам документ. С префиксами ru указываются файлы с переводами на русский язык. С префиксами add_ru указываются аддендум-файлы - файлы с дополнительным текстом, который нужно вставить в перевод (например, информация об авторах перевода).

Например, в моём случае аддендумы были двух видов. Файлы pppoe-relay.ru.8.add, pppoe.ru.8.add, pppoe-server.ru.8.add, pppoe-sniff.ru.8.add выглядят так:
PO4A-HEADER:mode=after;position=АВТОРЫ;beginboundary=\.SH

.SH "АВТОР ПЕРЕВОДА"
Перевод на русский язык выполнил Владимир Ступин <wheelof@gmail.com>.
А файлы pppoe-connect.ru.8.add, pppoe-setup.ru.8.add, pppoe-start.ru.8.add, pppoe-status.ru.8.add, pppoe-stop.ru.8.add выглядят так:
PO4A-HEADER:mode=after;position=АВТОР;beginboundary=\.SH

.SH "АВТОР ПЕРЕВОДА"
Перевод на русский язык выполнил Владимир Ступин <wheelof@gmail.com>.
Аддендумы, фактически, написаны по образу и подобию примеров из страниц руководства po4a. Они предписывают вставить текст после текста "АВТОРЫ" или "АВТОР", разметка которого выполнена с помощью шаблона ".SH". Подробнее о разметке страниц руководства можно прочитать на странице руководства groff_man(7). Некоторое время назад я начал её перевод и в последующем постараюсь довести его до конца.

Теперь главное, выполняем компиляцию проекта:
$ po4a po4a.conf
В каталоге проекта появятся файлы pppoe.pot и pppoe.ru.po. Файл po теперь можно переводить с помощью любого редактора po-файлов. Например, я использую poedit. Вам может понравиться gtranslator или kbabel.

В переводимом тексте встречается разметка, которая однако намного проще разметки groff_man и легко редактируется вручную. Например, текст B<pppoe> означает разметку жирным шрифтом будет выглядеть так: pppoe, текст I<pppoe> означает разметку курсивным шрифтом и будет выглядеть так: pppoe. Знаки больше и меньше имеют вид E<gt> и E<lt>. Например, текст E<gt>htmlE<lt> будет выглядеть на печати следующим образом: <html>. Другие способы разметки я не встречал.

После перевода файла po, можно скомпилировать проект снова. Для оригинальных страниц, у которых переведено более 80% текста, будут созданы страницы-переводы. Впрочем, принудительно посмотреть незаконченный перевод можно и вручную:
$ po4a-translate -f man -m pppoe.8 -p pppoe.ru.po -l pppoe.ru.8 -a pppoe.ru.8.add -k 0
man ./pppoe.ru.8
Не всегда разметка исходных страниц руководства бывает идеальной, а потому для успешной компиляции проекта бывает нужно отредактировать исходную страницу. Иногда встречаются неэкранированные знаки минуса или точки, иногда - неправильные теги разметки текста, например вместо \fB может встретиться \fb. На этот случай нужно вооружиться groff_man(7) и исправить неправильные участки страницы руководства.

Также, в процессе перевода, может пригодиться знание пакета gettext. Например, мне очень пригодилась команда msgmerge для слияния нескольких po-файлов в один.

Пример этого и других переведённых проектов можно взять из svn-репозитория: https://man-ylsoftware.svn.sourceforge.net/svnroot/man-ylsoftware/

Если кто-то заинтересован в том, чтобы помочь мне в оформлении переводов, можете зарегистрироваться на сайте http://www.transifex.net/projects/p/manpages-ylsoftware-ru/ и попроситься в команду перевода на русский. Укажите в профиле адрес своей электронной почты - я свяжусь с вами и мы поговорим о том, каким образом вы можете помочь проекту.

В рамках проекта планируется следующая деятельность: перевод страниц руководства из различных пакетов, сбор готовых переводов из интернета с последующим конвертированием переводов в формат проекта po4a, актуализация имеющихся переводов, помощь в конвертировании готовых переводов в формат страниц руководства. Проект на сайте transifex.net и svn-репозиторий на sourceforge планирует приобщить к своему дистрибутиву русское сообщество Fedora. Можете предлагать другие способы взаимодействия и прочую посильную помощь. Удачных и лёгких переводов!

Дополнение. Чтобы получить po-файл для одной страницы руководства, можно воспользоваться следующей командой:
$ po4a-gettextize -f man -m apt-cache.8 -p apt-cache.ru.po
Если нужно получить новую версию po-файла, то можно указать уже имеющийся po-файл с переводом старой версии:
$ po4a-gettextize -f man -m apt-cache.8 -l apt-cache.ru.po.old -p apt-cache.ru.po.new
Обновлено: 28 ноября 2010 года.