Перевод посредством сравнения версий

[maksimr]

По мотивам maksimr/docs.angularjs.ru#1 (comment)

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

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

Варианты решения:

Ручной:

Смотреть на оф. репозиторий(официальный репозиторий) и ручками составить
файл где будут перечислены файлы с переводом и соответствующие
им номера коммитов с офф. репозитория.

Например:

guide:
name: bootstrap.ngdoc
hash: f24cf4b
date: 2013-05-03

Где f24cf4b58f3c2e56df188738356b21e6c898ff0c(Кнопка History)
hash файла bootstrap.ngdoc с которого мы делали
перевод.

Это позволит нам:

1. Если узнать что файл изменился, если изменился hash (в оф. репозитории)
2. Посмотреть diff между коммитом, с которого мы делали перевод и последним

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

Автоматический:

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

Второе что пришло на ум, чтобы не править исходники сделать под-модулем основной репозиторий
и от туда брать hash-и файлов документации.

Минус:

1. Надо затратить время и сделать это :)
2. Придется править исходники сборки, так как теперь у нас будет две версии файлов, оригиналы и перевод, что может привести к конфликтам при мердже с офф репозиторием. (~)
3. Где лучше запускать этот скрипт? Подходящее место как мне кажется для этого сборка документации на heroku,
   но тут проблема что нам придется пушить этот файл на гитхаб, что инициирует сборку на travis-е, который в свою очередь снова запустит билд на heroku %).

В общем надо подумать...

[tamtakoe]

???????? ???? ?? ????? ?????????, ?.?. ????? ??? ?????? ?????? ?????????
???: ???????, ???... :-)

??? ?????? ??????? ??? ??????? ????? ? ?? ???? ???? ??????? ??? ??????.
????? ?????? ??? ? ????? ?????????? ?? ???????????? ???????????, ????????
??????? ?? ????? ? ??????????????? ???????. ? ???????? ?????????? ? ??????
? ??? ????? ????? ? ??? ???????, ???? ???? ?????????? ???? ????????
?????????.

? ?????????????? ??????? ????? ???????? ??????????, ??????? ???? ?????????
??????????? ??????????? ? ?????? ?????? ?????? ?? ??????? ?? ?????? ??????,
??????? ? ???? ????????? ????????. ???? ???????? ? ?????? ????? ??????????,
?? ????? ???????? ???????. ?????????????? ???????, ????? ???????? ?? ? ????
????????? ???????? ????? ???????????.

??????? ??? ?????? ????, ??????? ????? ???????????????? ??? ????? ??
?????????. ????? ??????? ???????? ? ????? ?????????? ??? ?????? ?
?????-?????? ??????????, ????? ???? ??? ??????? ?? ???????? ?????? ?
????????????? ????????)

3 ??? 2013 ?., 0:39 ???????????? Maksim Ryzhikov
[email protected]???????:

?? ??????? maksimr/docs.angularjs.ru#1maksimr/docs.angularjs.ru#1 (comment)

???? ????????? ??? ??????? ????? ?????????, ?? ??????????.

?????? ????????????? ????????? ????????, ???? ? ??????????? ???????????
?????
????????? ???????????, ?????????? ? ??????, ?????? ????? ?????? ???
??????????
????? ????????.

???????? ???????:

??????:

???????? ?? ??. ???????????(??????????? ???????????) ? ??????? ?????????
???? ??? ????? ??????????? ????? ? ????????? ? ???????????????
?? ?????? ???????? ? ???. ???????????.

????????:

guide:
name: bootstrap.ngdoc
hash: f24cf4bhttps://github.com/maksimr/angular-doc/commit/f24cf4b58f3c2e56df188738356b21e6c898ff0c
date: 2013-05-03

??? f24cf4b58f3c2e56df188738356b21e6c898ff0chttps://github.com/angular/angular.js/blob/master/docs/content/guide/bootstrap.ngdoc(??????
History)
hash ????? bootstrap.ngdoc ? ???????? ?? ??????
???????.

??? ???????? ???:

1. ???? ?????? ??? ???? ?????????, ???? ????????? hash (? ??.
   ???????????)
2. ?????????? diff ????? ????????, ? ???????? ?? ?????? ??????? ?
   ?????????

????? ????????, ?????????? ?????? ???????????? ???? ???????????? ?
??????? ??
????????? ? ??. ???????????.

??????????????:

???? ???????? ??? ??? ????? ????????????????.
?????? ??? ???????? ?? ??, ???????? ???? ????? ? ????????? ???????? ??
??????????.
??????? hook(pre-commit) ??? ??????, ??????? ????? ????????? ?? ??????
??????? ????????????, ???????? ???? ?????????,
???????? ??????????????? ?? ?????????? ?????, ? ???????? ?? ????? ????
????????????.

?????? ??? ?????? ?? ??, ????? ?? ??????? ????????? ??????? ???-???????
???????? ???????????
? ?? ???? ????? hash-? ?????? ????????????.

?????:

1. ???? ????????? ????? ? ??????? ??? :)
2. ???????? ??????? ????????? ??????, ??? ??? ?????? ? ??? ????? ???
   ?????? ??????, ????????? ? ???????, ??? ????? ???????? ? ?????????? ???
   ?????? ? ??? ????????????. (~)
3. ??? ????? ????????? ???? ??????? ?????????? ????? ??? ??? ???????
   ??? ????? ?????? ???????????? ?? heroku, ?? ??? ???????? ??? ??? ????????
   ?????? ???? ???? ?? ??????, ??? ?????????? ?????? ?? travis-?, ??????? ?
   ???? ??????? ????? ???????? ???? ?? heroku %).

? ????? ???? ????????...

Reply to this email directly or view it on GitHubhttps://github.com//issues/5
.

[maksimr]

OMG! Только я вижу вопросики '???...', много вопросиков?)
@tamtakoe

[davetoxa]

Я тоже вижу вопросами)

[sevaorlov]

да, одни вопросы

[maksimr]

@vsorlov
@davetoxa
Вы текст issue видите как вопросы или комментарий @tamtakoe ?)

[tamtakoe]

Ого! Я и сам свой текст теперь вижу как вопросики))) Видимо из-за того, что из ГМейла отправил. Продублирую так:

Проблема, как мне кажется, пока не столь актуальна, т.к. нужно для начала просто перевести все: учебник, АПИ... :-)

При ручном способе все намного проще и не надо даже никаких дат писать. Можно просто раз в месяц проходится по официальному репозиторию, смотреть коммиты за месяц и актуализировать перевод. В процессе погружения в статью и так будет видно в чем отличия, даже если пропустить пару коммитов оригинала.

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

[sevaorlov]

А нельзя из ngdoc вынести локализацию в отдельные файлы, например .properties? Чтобы отделить суть от локализованных текстов. Можно придумать что-то такое и предложить в официальном репозитории, они же должны быть заинтересованы в переводе их документации на другие языки.

[tamtakoe]

Наверное это к переводу АПИ относится, т.к. в руководстве только доки. Нужно подумать, будет ли удобно следить за обновлениями в официальном репозитории в этом случае.

[maksimr]

@vsorlov У них спрашивали про перевод на другие языки в google group. Там они ответили что как только стабилизирует английскую версию займутся этим (переводами).

[tamtakoe]

Обновился Ангуляр, попытался добавить в документацию новые функции и сразу отгреб кучу проблем.

Документация по API, а она, в основном, и меняется, слита вместе с кодом библиотек. Пока поправил только документирующие комментарии, не трогая кода, но по хорошему нужно обновлять все файлы сайта. Хотя бы для того, чтобы примеры поддерживали новую версию. И тут проблема: новый файл заменит переводы старого. Соответственно, нужно сделать так, чтобы при слитии сканировалось описание в ngdoc и, если есть отличия, то новый английский блок ngdoc копировался бы после переведенного (с экранированием тегов разметки, чтобы не было двух одинаковых по смыслу блока). Ну а потом нужно просто проходиться по документации и переводить изменения.

[maksimr]

Тепрь так не сделать :)
Сравниваться то будут русский и английский текст ..
На выходных начну пилить реализацию скрипта для сравнения ..

[githubjeka]

ИМХО: ветки официальной документации, которые со старыми версиями по-барабану. Всегда читаю последнюю.
Я за то, чтобы была одна версия у документации. Как поступить с новыми или старыми фишками? Легко - добавлять примечание в скобках (доступно с v1.2.6) или устарело (удалено) v1.2.6 . Смотреть, чтобы это соблюдалось при принятии пулла. Править документацию только руками, с автоматикой будет проблем больше, если это не официальная автоматика для перевода.

P.S. Не нужно копировать в один в один офф. документацию. Часто читая официальную пытаюсь найти описание нюансов, а они просто проигнорированы. В русской документации эти нюансы взяты из других источников и описаны. Это огромный плюс.

[maksimr]

@githubjeka согласен