Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
maksimr opened this issue May 2, 2013 · 13 comments
Open
Assignees

Comments

@maksimr
Copy link
Collaborator

maksimr commented May 2, 2013

По мотивам 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
Copy link
Collaborator

tamtakoe commented May 2, 2013

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

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

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

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

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
Copy link
Collaborator Author

maksimr commented May 2, 2013

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

@davetoxa
Copy link

davetoxa commented May 3, 2013

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

@sevaorlov
Copy link
Collaborator

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

@maksimr
Copy link
Collaborator Author

maksimr commented May 3, 2013

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

@tamtakoe
Copy link
Collaborator

tamtakoe commented May 3, 2013

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

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

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

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

@sevaorlov
Copy link
Collaborator

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

@tamtakoe
Copy link
Collaborator

tamtakoe commented May 4, 2013

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

@maksimr
Copy link
Collaborator Author

maksimr commented May 4, 2013

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

@tamtakoe
Copy link
Collaborator

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

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

@maksimr
Copy link
Collaborator Author

maksimr commented May 24, 2013

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

@githubjeka
Copy link
Contributor

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

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

@maksimr
Copy link
Collaborator Author

maksimr commented Feb 6, 2014

@githubjeka согласен

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

5 participants