Оригинал англоязычной документации находится по адресу https://github.com/laravel/docs.
Перевод документации на русский находится на гитхабе по адресу https://github.com/LaravelRUS/docs . Апдейт перевода осуществляется пулл-реквестами в этот репозиторий.
Редактирование репозитория с переводом может происходить в двух вариантах - внесение незначительных изменений и обновление перевода файла до актуального.
Внесение мелких изменений
Если вы заметили опечатку, некрасивый перевод, неподходящее употребление термина - вы можете просто отредактировать файл прямо на гитхабе. Не нужно уметь пользоваться git , гитхаб сам сделает пулл-реквест. Если же вы заметили, что в русской документации отсутствует фича, которая есть в документации англоязычной, вам нужно использовать другой вариант работы.
Обновление перевода до актуального
Формат файла перевода
Файлы русскоязычной документации имеют определенный формат. В начале каждого файла должна быть конструкция следующего вида (обратите внимание, что в середине - пустая строка):
git a49894e56c3ac8b837ba7d8687d94f6010cb1808
---
где a49894e56c3ac8b837ba7d8687d94f6010cb1808
- полный номер коммита в англоязычной документации, последнего актуального на момент редактирования для данного файла. Это нужно для того, чтобы понимать, что именно переведено, а что еще нет - чтобы следующий переводчик не просматривал глазами весь файл в поисках изменений, а просто внес то, что ему покажет git diff
Итак, последовательность действий при переводе документации следующая.
Настройка git difftool
Если вы этого не сделали, установите себе инструмент для визуального сравнения разных версий текста. Их существует огромное множество, кросплатформенный бесплатный вариант - KDiff3 http://sourceforge.net/projects/kdiff3/
После установки, отредактируйте глобальный файл .gitconfig
, который находится в папке пользователя (для Windows это C:\Users\(username)
) . Добавьте туда следующие строки:
[diff]
tool = kdiff3
[merge]
tool = kdiff3
[mergetool "kdiff3"]
path = C:/Program Files/KDiff3/kdiff3.exe
keepBackup = false
trustExitCode = false
где path - это путь до исполняемого файла kdiff3.
Если у вас стоит другая diff-программа, например Araxis Merge или DiffMerge, то погуглите, как её настроить для гита - '(program name) difftool gitconfig'
Получение текста для перевода
Склонируйте репозиторий оригинальной документации
git clone https://github.com/laravel/docs.git original_docs
cd original_docs
git checkout master
или, если он уже у вас есть, обновите нужную вам ветку
original_docs> git checkout master
original_docs> git reset HEAD --hard
original_docs> git pull origin master
На странице Прогресс перевода посмотрите, какой файл нуждается в переводе и скопируйте соответствующую команду git difftool xxxxxxx xxxxxxx file.md
, чтобы узнать, что именно нужно переводить
original_docs> git difftool a06af42 bc291ef controllers.md
Git захочет запустить внешнюю diff-программу, настроенную на предыдущем шаге, соглашайтесь.
В появившейся программе справа будет старый файл, а слева - новый, цветом отмечены расхождения в версиях.
Внесите необходимые изменения в файл перевода. Изменения нужно внести все ,чтобы переведенный файл полностью соответствовал оригинальному. Нельзя останавливаться на середине и пушить изменения - следующий человек может подумать, что файл уже переведён полностью.
Финальные шаги
Обязательно измените в начале переводимого файла полный номер коммита. Этот номер можно взять на той же странице прогресса перевода в столбце "Текущий оригинал".
Закоммитьте изменения и пошлите пулл-реквест из гитхаба. Старайтесь делать изменение только одного файла во время одного коммита.