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

Оригинал англоязычной документации находится по адресу 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-программу, настроенную на предыдущем шаге, соглашайтесь.

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

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

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

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

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

Соглашения о терминах

A

  • action — метод контроллера
  • alias — псевдоним

B

  • (http) basic authentication — http-аутентификация
  • binding — связывание

C

  • callback — функция обратного вызова, анонимная функция, или просто функция
  • Composer — не переводить, когда с большой буквы

D

  • dependency injection — внедрение зависимостей
  • deploying — развёртывание

F

  • facade — фасад

G

  • guards — гварды

H

  • helper — хелпер

I

  • instance — экземпляр

J

  • job dispatching — постановка задачи в очередь
  • jobs — задачи в очереди

M

  • middleware — посредник
  • migration — миграция
  • module bundler — сборщик модулей

Q

  • queue — очередь

R

  • redirect — редирект
  • render — отображение
  • render a view — отображение шаблона
  • request — запрос
  • resolver — обработчик
  • response — ответ
  • route — роут

S

  • service - сервис
  • service container — сервис-контейнер
  • service provider — сервис-провайдер
  • signature — сигнатура
  • source control — система контроля версий
  • stateful — с сохранением состояния
  • stateless — без сохранения состояния

T

  • throttling — органичение числа попыток
  • throw an exception — бросить исключение
  • trait — трейт
  • truth test — проверка на истинность
  • type-hint — ???
«Type hinting» — это контроль типов. «type-hint» в контексте Laravel это, как правило, означает подачу в аргументы какого-либо класса. Т.е., например, «First, let's look at accessing the session via a Request instance, which can be type-hinted on a controller method» — это что-то вроде «Один из методов доступа к сессиям — при помощи экземпляра класса Request, который можно указать в качестве аргумента метода контроллера». Если подобное обыгрывание невозможно, то можно type-hint оставить непереведённым.

U

  • unit-test — юнит-тест

V

  • view — шаблон
  • view composer — вью-композер