Пользователь
0,0
рейтинг
1 августа 2011 в 11:35

Разработка → Новый инструмент перевода документации PHP: edit.php.net

PHP*

Инструмент: 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. Если вы нашли опечатку или ошибку в статье, пожалуйста напишите мне о них в приватном сообщении.
Александр @Irker
карма
108,5
рейтинг 0,0
Реклама помогает поддерживать и развивать наши сервисы

Подробнее
Спецпроект

Самое читаемое Разработка

Комментарии (23)

  • +1
    Спасибо за инструкцию. Будем переводить.
    • +2
      В итоге удалось восстановить актуальное состояние перевода у 5 математических функций.
      Инструкция рабочая, еще раз спасибо.
  • 0
    Спасибо, уже перевел пару коротких записей. Теперь будет чем заняться в короткие периоды ничегонеделания.
  • 0
    Инструментарий крайне запутанный, плохо работает JavaScript, да и сам демонстрирует недоверие к новым пользователям. Жаль, что не удастся поучаствовать.
    • 0
      Инструмент все еще развивается и улучшается. Если есть идеи и предложения по улучшению — пожалуйста отпишите feature request на bugs.php.net. Там же лучше описать про проблемы в JavaScript, yannick очень не любит баги и старается быстро их исправлять.

      Что в вашем понятии «недоверие к новым пользователям»? Если вы про проверку их работы, прежде чем выкладывать ее на сайт документации, то я с вами категорически не согласен.
      Это не википедия, а документация к языку программирования. Здесь малейшая шутка какого-нибудь легкомысленного человека может привести к потери множества часов множеством людей, читающих документацию. Поэтому вполне логично проверять патчи, никто же не выкидывает их работу?
      • +2
        Мне всё равно до проверки работы — проверяйте, возражений нет, но я не понимаю, зачем системе доступ до моего аккаунта Фейсбука или Гугла. Как правило, я не авторизую никакие приложения, потому как случается всё, что угодно. Просто хочу авторизоваться не через всякие oAuth Твиттера. Мне не нужен обещаемый ящик @php.net и прочие плюшки, просто авторизация через сторонние сервисы меня пугает.

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

        Ладно, я отключил NoScript вообще на всех сайтах, что по сути, самоубийственно с моей широтой сёрфинга до всяких нехорошеньких страниц (не порно, перегруженные японские сайты), надо будет не забывать его включать обратно. Что-то начало грузиться, Файерфокс просто повис и выводил ошибки о долгом выполнении скрипта с предложением завершить его. И версия ведь стабильная, никаких ночных сборок.

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

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

        Вот примерно это всё и заключалось в моём комментарии: «Инструментарий крайне запутанный, плохо работает JavaScript, да и сам демонстрирует недоверие к новым пользователям.»

        Никогда не хулил никого из пантеона богов PHP, но карма, как видно, уже испорчена. И вот реальную в отличие от хабровской одной кнопкой не сбросить.

        Жаль, что не удастся поучаствовать.
        • 0
          Не отчаивайтесь, все еще можно наладить :)
          Авторизация через Facebook/Google введена исключительно для удобства пользователя (и кстати, была введена совсем недавно, так что еще не отлажена толком). Если она вам не нравится, нажимайте на кнопку Anonymous login, и вы уже внутри. И, кстати, почитайте на досуге про схему работы OpenID/OpenAuth — логин/пароль вы вводите на сайте самого провайдера, в данном случае, Facebook/Google, и как пользователь не рискуете ничем, разве что раскроете свой email данному приложению.
          По поводу загрузок: должно работать в Firefox и Google Chrome/Chromium, на Opera лучше полагаться не стоит (в IE не проверял, мне это тяжеловато сделать на linux).
          Если онлайн-редактор вас все равно не устраивает (мне, например, также удобно работать локально), то вторая часть статьи под названием «Альтернатива» была написана специально для вас. Если вы используете Windows, то лучше скачать новую версию TortoiseSVN с сайта разработчика.

          По поводу подписки на список рассылки, процитирую часть соседней статьи:
          Для подписки нужно отправить пустое письмо на doc-ru-subscribe@lists.php.net (для отписки соответственно на doc-ru-unsubscribe@lists.php.net).


          Если все еще будут проблемы — пишите в личку или на email shein @ php.net.
          • 0
            Приложения получают много информации и доступ к нескольким средам публикации и личной переписки, пользователи сайтов социальных сетей порой страдают от подобной скрытой активности — тому есть великое множество примеров, в которых виноваты иной раз вовсе не недобросовестные разработчики, а подбор паролей к аккаунтам администраторов приложений, подмена страниц, скрытое внедрение кода и проч.

            SVN-клиент актуальной версии уже настроен. Повторюсь, робот подписки не отвечает даже на повторные письма, вряд ли подобные задержки вообще возможны.

            Извините, я передумал.
            • 0
              Что ж, жаль. У остальных вроде получилось, в любом случае — удачи вам.
            • 0
              > Приложения получают много информации и доступ к нескольким средам публикации и личной переписке

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

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

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

              И да, интерфес конечно не самый быстрый (Ext.JS — известный тормоз), но у меня за секунд 10 загрузился. Видимо тогда сервер просто накрыло хабраэффектом.
  • 0
    Хороший проект, я уже выложил патч на проверку. Инструмент достаточно интуитивно-понятен и прост. Я думаю этот проект будет полезен многим, как самим участникам(подтянут английский, лучше изучат некоторые аспекты языка), так и тем, кто потом будет пользоваться переводами. + небольшие, но бонусы, должны мотивировать php-кодеров к написанию переводов.
  • 0
    Судя по этому инструменту команда php.net отдает предпочтение JS фреймворку ExtJS :)
    • 0
      Этот инструмент разве не написан одним человеком?
      >> В этом году Yannick Torrès (yannick) создал удобный web-инструмент для перевода документации PHP…
      Если так, то причем тут один он и целая команда php.net?
      • 0
        Ну yannick является частью команды php.net. Кроме того, он основной разработчик, но не единственный, об этом можно прочитать в самом онлайн-редакторе в разделе «О программе» :)
        • 0
          Тогда да.
  • +1
    1. Не хватает предпросмотра страницы в html, как оно будет смотреться в реальности, т.к. найти смысловую ошибку проще, читая форматированную страницу, чем xml-документ.
    2. У меня не работает русская проверка орфографии. Хоть я и включил значок проверки орфографии, но подчеркивает только англ. слова.
    • 0
      1. docs.php.net/manual/ru/
      2. Недоработка, согласен. Можно открыть баг в bugs.php.net в разделе Online Editor Problem.
      • 0
        По-моему, по первому пункту предпросмотр только раз в час, и _после_ проверки модераторами. Я говорю о предпросмотре редактируемого мною xml в данный момент. Чтобы видеть что же в итоге получится. Здается мне, была это полезная фича.
        • 0
          Извиняюсь, не раз в час, а раз в 4 часа, или 4 раза в день. Что-то про цифру 4 )
        • 0
  • 0
    Может, это лично мне неудобно, но я немного споткнулся на создании патча.
    Что я делал:
    1-4. Залогинился, выбрал интересную секцию в разделе «непереведенные файлы», перевёл пять файлов, сохранил их.
    5. Попытался найти контекстное меню для создания патча в основном меню и (как написано в этой статье) в контекстном меню файлов, которые переводил. Там не нашёл, но нашёл в разделе «файлы в прогрессе».

    Напишите, плз, если есть более очевидный вариант как закоммитить патч.

    Ну и не нашёл истории своих правок, а интересно :)
    • 0
      Именно о контекстном меню в «файлы в прогрессе» и говорилось.
      К сожалению, пока только так.
      Впринципе в этом есть свои плюсы — в «файлы в прогрессе» ваши файлы отделены от других, и всегда на ладони.

      Истории правок тоже пока нету. Но если ваш перевод закоммитят, то обязательно укажут ваш никнейм в комментарии к коммиту. Так что ваша работа не потеряется)
  • 0
    Что то не совсем понятно, выбираю слева «непереведенный файлы» дальше в поиске ввожу migration, хочу главную страницу перевести, посвященную обновлению на php7, нахожу в поиске Appendices/migration70.xml, открываю его, там непонятно какой устаревший текст про то что php70 еще в разработке, а как мне увидеть текст текущего оригинала и вывести его в окошко рядом?

Только зарегистрированные пользователи могут оставлять комментарии. Войдите, пожалуйста.