И снова о переводе документации 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!
Если вечерний билд сломался после утреннего коммита одного файла, то, по большей части, все просто — идешь и выверяешь. Но если коммитов было штук двадцать, а количество файлов измеряется парой сотен, то проще повеситься, потому как и приаттаченый лог и режим диагностики далеко не всегда добавляют понимания, в каком месте проблема. А проблема легко может быть на стороне основной английской ветки и тогда вообще туши свет.

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

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

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

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

Выводы


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

Ссылки


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

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

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

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

UPD Создали канал в слаке. Кому интересно пообщаться — заходите.
Share post

Comments 30

    +2

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

      +6
      Позвольте считать ваше спасибо адресованным всем прошлым, существующим и будущим переводчикам. И отдельным пунктом великому анонимосу — благодаря ему в документации гораздо меньше опечаток и неточностей, чем могло бы быть. Да, создавать патчи с исправлениями можно без регистрации и смс :)
        0
        Вот они наши герои! Спасибо Вам!
      +1
      Не совсем понятно зачем?!
        +3
        Как любой другой перевод, затем, что есть люди, и их много, кому удобней, понятней и приятней читать на родном языке.
          0
          Русскоязычная документация нужна в первую очередь начинающим программистам.
          К сожалению, тут php.net имеет довольно скудную и не совсем правильную документацию для начинающих.
            +2
            На текущий момент, русская документация актуальна и соответствует английской. Не совсем понял, что вы имели в виду
              –3
              Я имел ввиду, что документация для начинающих неправильная. Т.е. дело не в том, что переведено неправильно, переведено все хорошо. Дело в том, что сама структура и сам этот учебник ненагляден.

              Нужно что-то такое:
              PHP начинающим:
              - Что такое?
              - Как работает? (азы клиент-серверной архитектуры)
              - Как установить? (простейшие инструкции)
              - Как написать Привет миру? (азы языка)
              - Как написать форму обратной связи (показать клиент-серверный пример, смешивание php+html, глобальные переменные, валидацию параметров и функции)
              - Как написать конвертер температуры (чтение из CSV, циклы, отображение таблицы, запись в файл)
              - Счетчик посещений (работа с cookie, MySQL, GD)

              Это все практические примеры, с которыми сталкиваются все программисты. Каждая инструкция в коде должна быть кликабельна, со ссылкой на полный мануал.
                  0
                  Это оно, только оно построено не в стиле для начинающих.
                  Учебник для начинающих обычно построен ввиде пошагового руководства (он имеет линейную структуру изучения).
                  Даже если зайти сюда, то в большинстве случаев новичок понятия не имеет что такое DOCUMENT_ROOT.
                    0
                    Мне кажется, что вы немного путаете два понятия — документация и обучение.
                    Цель документации не научить программировать, а предоставить понятную, непротиворечивую информацию о языке, его особенностях, функциях и т.д.
                    То, о чем пишите вы, это обучение. Курсов, учебников, тематических форумов по PHP в сети — огромное количество.
                      0
                      У вас прямо в заголовке написано «Простой учебник» php.net/manual/ru/tutorial.php

                      Я не путаю понятия документация и обучение. Я считаю их неразделимыми. Цель документации как раз и состоит в обучении.
                      Человек обращается к документации для того, чтобы изучить, как работает та или иная функция языка. Новичок же обращается к документацию с целью освоения программирования на PHP. Это как раз именно то место, где нужно показывать и объяснять правильный подход к разработке, философию и методологию.
            +1
            Не совсем понятно зачем?!

            Помимо всего прочего это еще и хорошая тренировка навыков переводчика.
            К тому же отличный способ поддержать интеллектуальный тонус.

            0
            Напишите про процесс написания документации. Я бы поучаствовал, благо времени свободного полно.
              0
              Если вы про перевод, то в конце поста ссылка на статью на хабре, где довольно подробно расписан процесс. Любые вопросы можете писать в личку, в группу рассылки, либо мне на почту rjhdby ат php дот net. Если именно про дополнение базовой английской ветки, то это совсем друга тема — постараюсь написать обзорную статью как будет время.
              +4
              Спасибо, что подняли упавший флаг :) Когда-то проходил через все эти же грабли, эх, давно это было.
                0
                Так возвращайтесь :)
                0

                А реальное ли переехать с переводом на более удобный сервис, например transifex?

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

                    Он действительно платный, но для open source проектов доступен полный функционал бесплатно.

                  0

                  Слышал, что есть системы автоматизированного перевода. Т.е. переводишь предложение в файле, а система сама ищет вхождение этого предложения во всех файлах и переводит его.
                  Отличная задумка!

                    0
                    Не сказал бы, что отличная. Во-первых, одно и то же предложение, в зависимости от контекста, может переводиться по разному. Во-вторых, очень бы не хотелось взяв в перевод очередную страницу увидеть там невнятную кашу из двух языков. Ну и в-третьих, специфика локализации PHP такова, что такой подход породит достаточно много проблем.
                    • UFO just landed and posted this here
                        0

                        Типа того. Пробовал её когда пытался доку по постгресу переводить.

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

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

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

                          А можно попробовать в упрощенном варианте поработать 1-ой десятой землекопа, но через github? Насоздавать там issues и народ и я в том числе будет помогать в силу возможностей?

                          А вы зная уже весь процесс будете проталкивать изменения дальше в систему?
                            0
                            С git'ом экспериментировал lex111, попробуйте ему написать (если сам в тему не призовётся).
                            Я то по старинке, через онлайн-редактор.

                          Only users with full accounts can post comments. Log in, please.