Предыстория

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

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

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

Для начала про то, как дела обстоят сейчас.

Проектом занимаются полтора землекопа в режиме актуализации измененных страниц и вычитки. Что-то новое переводится крайне редко из-за банального отсутствия времени и… усталости наверное.

Сейчас переведено 7.147 файлов из 12.992. По количеству это 55%, но по объему 67.6%. Круче русской локализации только японцы(63%), испанцы(65.5%) и французы(77.3%).



Но что более важно, 100% переведенных страниц актуальны.

Что было два года назад.

Лучше всего ситуацию описывает ответ на мой вопрос в группе рассылки одного из основных мантейнеров Irker:

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

По факту же состояние локализации выглядело как-то так



Уж извините, не догадался наделать скриншотов в тот момент.

На этом, пожалуй, с отчетом о проделанной работе я закончу и перейду рассказу о проблемах.

С чем пришлось столкнуться

Спасение утопающих — дело рук самих утопающих

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

Это потом я уже узнал, что самый простой путь — написать в группу рассылки (совершенно чудовищный способ общения в 2016+ году), но на тот момент пришлось играть в детектива и по никам переводчиков искать их почтовые адреса и слать письма. Из всех отправленных писем ответ пришел только от Irker, и, по хорошему, как раз с этого момента все заверте…

Бег с препятствиями за ушедшим паровозом.

Прежде чем начинать переводить новые страницы, логично было для начала привести в порядок устаревшие. Ибо грош цена документации, если треть ее не соответствует действительности. Примерно 700 страниц ждали, когда их приведут в порядок. Плюс к этому как раз шел процесс обновления английской ветки для соответствия PHP 7, так что количество их прибывало и прибывало.

Это было про паровоз, а сейчас про препятствия.

Самая жуть состояла в том, что половину из этих страниц кто-то уже пытался актуализировать. Зачастую делал это не до конца, либо довольно криво, либо после актуализации основная страница еще несколько раз менялась. В общем тот еще адок.

А давайте поправим скриптом отступы во всех документах?

Пару раз была ситуация, когда в английской ветке скриптом что-то правили сразу по всем документам. Обычно рядышком выкладывали инструкции по автоматической актуализации для переводчиков, но по факту все равно потом приходилось выверять по 100-200 страниц вручную. Sad but true.

Я что-то нажала и оно все сломалось

Одно из самых неприятных событий — получить в рассылке письмо:

The ru build of the PHP Manual is broken, so it does not validate or build. Please fix it! ;)
Attached is the full log
Love, The docs.php.net server
…
Eyh man. No worries. Happ shittens. Try again after fixing the errors above.
=============> Something happenend when snapshotting ru
Failed completely
=============> Please have a look!

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

И стер с лица земли его творенье — Легко, непринужденно, с вдохновеньем.©

Вандалы. Да. К счастью, не так много как могло бы быть, но периодически приходится вычищать конюшни от разного, начиная от простого «х*й х*й Х*й тут был Вася» и кончая подмененными ссылками на фишинговые сайты.

Ты что, финский усвоил?

Термины — та еще головная боль. Для многих англоязычных терминов банально отсутствуют аналоги в русском языке. А если дело касается описания узко-специализированного расширения, для которого в принципе не существует адекватного описания даже на английском, то становится совсем грустно. Порою на перевод одной небольшой страницы уходит в разы больше времени, чем на десяток объемных простыней текста про широко используемые вещи. С другой стороны узнаешь много нового.

Выводы

1. Русской документацией по PHP пользоваться можно. Она на 100% актуальна и в обозримой перспективе такой и останется.
2. Если, вдруг, после этой публикации понабегут желающие помогать, то даже можно ожидать увеличения переведенных статей.

Ссылки

Онлайн редактор
Инструкция по использованию онлайн редактора за авторством Irker
Группа рассылки

P.S.: Если интересно, то могу в целом рассказать о том, как устроен процесс написания документации PHP, что в нем хорошо, а что не очень.

По просьбе единицы из полутора землекопов, lex111, я там половинка :)

Не так давно на GitHub я создал Git-репозиторий документации (напомню, она использует svn, для интересующихся есть чеклист по миграции на git), где все желающие могут подписаться на обновления (кнопка Watch), тогда в вашей ленте будут показываться уведомления о новых коммитах в документации, либо отметить звёздочкой (кнопка Star), если вам нравится текущее качество документации :). Так что, присоединяйтесь к улучшению и дальнейшему развитию документации, узнаете много нового и полезного!