Инструмент: edit.php.net

В этом году Yannick Torrès (yannick) создал удобный web-инструмент для перевода документации PHP. edit.php.net позволяет каждому легко и быстро переводить любую страницу.
Данная статья является техническим продолжением статьи "Команде переводчиков документации PHP требуется помощь".
UPD: Сайт может лагать из-за хабраэффекта.

---

На каждой странице мануала есть ссылка для ее редактирования в edit.php.net.

Перейдя по ней мы попадем на страницу аутентификации, где сразу же не задумываясь выбираем для перевода язык Russian.

Затем советуем сразу авторизоваться под своим google или facebook аккаунтом, это позволит вам работать над переводом под одним логином с разных компьютеров. (Иначе создается временный аккаунт Anonymous #xxxx). Для этого справа сначала подтверждаете свой аккаунт в google или facebook, а затем жмете Use this credentials и Anonymous Login.

Перед вами домашний экран сайта со всякими пусть и не сильно, но полезными виджетами. Слева — боковое меню, которое в процессе работы можно скрыть, чтобы не мешало. Большинство пунктов меню интуитивно понятны. Мы же опишем вам примерный цикл перевода файлов в edit.php.net:

1) Выбираете, что переводить: Непереведенные файлы или необновленные файлы. Или же можете выбрать файлы на проверку из раздела “файлы на вычитку”.
2) Как только вы начали переводить какой-то файл, то он перемещается в “файлы в прогрессе” и закрепляется за вами. Если вы редактируете необновленный файл, то вам также отображается его английская версия и изменения в ней по сравнению со старой версией.

В начале каждого файла с законченным переводом необходимы три специальных тега

<!-- EN-Revision: 301114 Maintainer: someone Status: ready -->
<!-- Reviewed: no -->
<!-- $Revision: 311957 $ -->

В первом теге указывается ревизия оригинального английского файла на момент перевода, статус перевода, а также никнейм человека, который будет сопровождать перевод этого файла в дальнейшем (это к сожалению не ваш никнейм, а SVN аккаунт ответственного участника ru-doc).
Пример: в английском файле стоит тег <!-- $Revision: 111111 $ -->, в русский файл добавляете тег <!-- EN-Revision: 111111 Maintainer: someone Status: ready -->.

Второй тег указывает, что данному файлу не помешает дополнительная вычитка — всегда полезно посмотреть на перевод нескольким людям. Если вы проверили “файл на вычитку”, то можете проставить данному тегу значение Reviewed: yes. (т.е. <!-- Reviewed: no --> если никто не перепроверял перевод, и <!-- Reviewed: yes -->, если перепроверял)

Последний тег — технический, в него будет проставлена ревизия переведенного файла.
Т.е. достаточно чтобы он просто был, например вообще без числа <!-- $Revision: $ -->.

3) Когда перевод или проверка файла закончены — в контекстном меню файла можно создать “патч” на проверку. UPD: Патч нужно делать обязательно — именно он сигнализирует нам, что вы закончили перевод файлов!


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

Советы:
— Сохраняйтесь почаще, всякое бывает и жалко будет терять свой труд.
— Группируйте файлы в патчи по смыслу. Например, если вы перевели несколько файлов документации к какому-нибудь расширению, то имеет смысл добавить их в один патч с указанием имени этого расширения.

Заранее прошу учесть, что нас пока мало и мы занимаемся переводом в свое личное время. Если будет наплыв добровольцев, то возможны задержки с проверкой ваших патчей.

Альтернатива

Изначально не было edit.php.net, а был svn репозиторий. Вернее не был, а есть. По сути edit.php.net так же работает с этим репозиторием. Многим удобнее работать напрямую с SVN и пользоваться инструментом docbook.

Итак, онлайн-редактор вам неудобен, у вас есть собственный крутой редактор или IDE, в котором ваша производительность просто зашкаливает. Ну или просто интернет не всегда доступен, в любом случае, рассмотрим вариант локальной работы через svn.

Вам понадобится любой XML-редактор, svn-клиент и php, работающий из командной строки (также известный как php cli).

Я опишу установку для Ubuntu 11.04, для остальных платформ подгоняйте соответственно.

Итак, для работы с документацией удобно использовать так называемый разреженный (sparsed) репозиторий, объединяющий в себе 3 репозитория сразу:

• doc-base (системные скрипты для сборки перевода)
• en (оригинальная версия документации на английском языке)
• ru (перевод документации на русском языке)

$   svn co https://svn.php.net/repository/phpdoc/modules/doc-ru/ phpdoc-ru

Эта команда выгрузит все нужные нам файлы в папку phpdoc-ru (кстати, через веб удобно просматривать по похожей ссылке, svn.php.net/viewvc/phpdoc/modules/doc-ru в которой заменен repository на viewvc).

По завершении выгрузки уже можно работать с полученными файлами. Схема работы такая же как и в онлайн-редакторе:

1) Выбираете себе файл для перевода
2) Проверяете, что он уже не занят кем-либо ( doc.php.net/trantools/revcheck_extended_ru.html и в разделе “файлы в прогрессе” на edit.php.net )
3) Переводите и оформляете перевод как положено (3 системных тега сверху, уровень отступа должен быть в 1 пробел — никаких табов)

Важно! После окончания перевода необходимо убедиться в том, что вы ничего не поломали, т.е. собрать билд. Это делается следующей командой:

$ php doc-base/configure.php --with-lang=ru

В случае успеха в конце должен получиться вывод All good. Saving .manual.xml… done.
(Также в конце может вылететь Segmentation fault, если вы используете PHP < 5.3.7 — здесь нет ничего страшного, это побочный эффект оптимизации скорости работы скрипта сборки. Выброс сегфолта можно отключить, но это приведет к немного более долгой работе скрипта сборки — список опций скрипта сборки можно увидеть с помощью команды

$ php doc-base/configure.php --help

Если команда выведет что-то вроде Don’t worry, Happ shittens, значит, вы допустили ошибку и нужно ее исправить. Например, это может быть незакрытый тег или неизвестная xml-сущность типа &error;. Расширенный режим сообщения об ошибках можно включить добавив опцию --enable-xml-details. Учтите, что в этом режиме сборка может использовать намного больше памяти.

Отправка патча

Итак, вы успешно перевели текст и собрали билд. Так как у вас нет svn-аккаунта, то закоммитить сами свою работу вы не сможете, нужно создать патч и отправить его в список рассылки. Это довольно легко.
Патч создается следующей командой (желательно выполнять ее в папке русского репозитория, т.е. phpdoc-ru/ru в нашем примере).

$ svn diff > good-patch-name.patch.txt

где good-patch-name — это понятное имя патча, описывающее что именно вы перевели. Обратите также внимание на расширение txt — список рассылки не примет ваш патч, если вы укажете другое расширение.
После этого нужно написать письмо в список рассылки и прикрепить к нему созданный патч. Все! :)

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

$ svn up

которая также должна запускаться из корня репозитория (phpdoc-ru).

Послесловие

Статью подготовили: conf, irker. Если вы нашли опечатку или ошибку в статье, пожалуйста напишите мне о них в приватном сообщении.

Upd: Чат переводчиков в slack