[Из песочницы] И снова о переводе документации PHP
Предыстория
Когда года два назад мне понадобилось прочитать описание одной из функций, я открыл гугл, вбил имя этой функции и по ссылке перешел на русское описание на сайте 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!
Если вечерний билд сломался после утреннего коммита одного файла, то, по большей части, все просто — идешь и выверяешь. Но если коммитов было штук двадцать, а количество файлов измеряется парой сотен, то проще повеситься, потому как и приаттаченый лог и режим диагностики далеко не всегда добавляют понимания, в каком месте проблема. А проблема легко может быть на стороне основной английской ветки и тогда вообще туши свет.
И стер с лица земли его творенье — Легко, непринужденно, с вдохновеньем.©
Вандалы. Да. К счастью, не так много как могло бы быть, но периодически приходится вычищать конюшни от разного, начиная от простого «х*й х*й Х*й тут был Вася» и кончая подмененными ссылками на фишинговые сайты.
Ты что, финский усвоил?
Термины — та еще головная боль. Для многих англоязычных терминов банально отсутствуют аналоги в русском языке. А если дело касается описания узко-специализированного расширения, для которого в принципе не существует адекватного описания даже на английском, то становится совсем грустно. Порою на перевод одной небольшой страницы уходит в разы больше времени, чем на десяток объемных простыней текста про широко используемые вещи. С другой стороны узнаешь много нового.
Выводы
- Русской документацией по PHP пользоваться можно. Она на 100% актуальна и в обозримой перспективе такой и останется.
- Если, вдруг, после этой публикации понабегут желающие помогать, то даже можно ожидать увеличения переведенных статей.
Ссылки
Онлайн редактор
Инструкция по использованию онлайн редактора за авторством Irker
Группа рассылки
P.S.: Если интересно, то могу в целом рассказать о том, как устроен процесс написания документации PHP, что в нем хорошо, а что не очень.
