Как правильно переводить документацию Laravel

21 января slider23

Оригинал документации - 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 , чтобы узнать, что именно нужно переводить

original_docs> git difftool a06af42 bc291ef controllers.md

Git захочет запустить внешнюю diff-программу, настроенную на предыдущем шаге, соглашайтесь

В появившейся проге справа будет старый файл, а слева - новый, цветом отмечены расхождения в версиях.

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

Финальные шаги

Обязательно измените в начале переводимого файла полный номер коммита. Этот номер можно взять на той же странице прогресса перевода в столбце "Текущий оригинал".

Закоммитьте изменения и пошлите пулл-реквест из гитхаба. Старайтесь делать изменение только одного файла во время одного коммита.