Russian Translation Guidelines

Введение

Данный документ описывает порядок и правила перевода, а также используемые инструменты. В настоящий момент переведно всё. Все разделы находятся в состоянии постоянной доработки и актуализации:

• Полное руководство по Yii.
• Системные сообщения фреймворка.
• Страничка проверки требований.
• Пример разработки блога.

Начало работы

Общая схема работы над переводом выглядит так:

• выбор раздела для перевода
• перевод с оглядкой на правила
• добавление/обновление файла в репозитории
• синхронизация версий по мере обновления оригинала

Перед началом работы необходимо выгрузить содержимое репозитория. Оригинал документации будет доступен по адресу ../yiidoc/guide/source, русская ветка, соответственно — по адресу ../yiidoc/guide/ru. Весь раздел с руководством доступен по локальному адресу http://localhost/yiidoc/index.php.

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

Файлы перевода должны быть сконвертированы в UTF-8 формат для корректного отображения.

Перевод

Общие правила

Ниже приведены общие правила, которых необходимо придерживаться, работая над переводом документации:

1. повествование в соответствии с оригиналом ведется от первого лица мноножественного числа (мы);
2. многие термины не имеют однозначного и широко распространенного перевода на русский язык, поэтому, если в тексте встречается такой термин, в скобках возле первого упоминания необходимо указать английский вариант; (список используемых вариантов перевода терминов см. ниже);
3. если кажется, что при переводе какая-то часть текста теряет смысл и вы не уверены в том, как ее правильно перевести, заключайте эту часть текста в * (внешне шрифт станет наклонным). Это позволит при вычитке/корректуре обратить на эту часть текста особое внимание;
4. при переводе избегайте фактических ошибок!
5. в тексте встречаются ссылки на внешние источники, если ссылка ведет на статью, определение термина и т.п., то при наличии русского варианта на этом же ресурсе или ином авторитетном ресурсе, даем ссылку на русский вариант. Например http://en.wikipedia.org/wiki/Captcha => http://ru.wikipedia.org/wiki/Captcha
6. комментарии в коде переводятся, если не искажают первоначального смысла; временные комментарии в тексте желательно использовать только локально! иначе есть вероятность попадания в релиз;
7. после перевода раздела при необходимости скорректируйте его название в содержании ТОС;
8. добавление собственных комментариев-дополнений возможно, но не приветствуется поскольку во избежание хаоса оригинал должен быть один. В случае такой необходимости в конце комментария нужно добавить "(прим. пер.)";
9. после проведения общей правки документа настоятельно рекомендуется самостоятельно вносить исправления только грамматических, а также фактических ошибок, имеющих отношение только к данному разделу. В остальных случаях необходимо вынести предложение по исправлению, улучшению на обсуждение и в случае необходимости централизованно внести коррективы во все разделы документа.

Структура документа

При переводе необходимо правильно именовать структурные единицы документы. Следуем структуре, приведенной ниже:

• Глава 1
  • Раздел 1
  • Раздел 2
    • Подраздел 1
  • ...
  • Раздел N
• Глава 2
• ...
• Глава N

Применительно к Полному руководству, структура будет выглядеть следующим образом:

• Начало
  • Обзор
  • Что такое Yii
  • Установка
  • Создание первого Yii-приложения
    • Соединение с базой данных
    • Создание операций CRUD
• Основы
• Работа с формами
• Работа с БД
• Кэширование
• Расширение Yii
• Специальные темы

Перевод специальных сообщений

Перевод специальных сообщений в документации типа > Note: и пр. при переводе оформляются следующим образом: > Note|перевод 'note': .... .

Таким образом для русского языка будет выглядеть так: > Note|Примечание: В примерах этого раздела используются модели формы...

• Tip => Подсказка
• Note => Примечание
• Info => Информация

Перевод рисунков

Рисунки к документации содержатся в подпапке images, в случае наличия исходников, переводятся и сохраняются в формате png. Подписи к рисункам оформляются следующим образом: ![Страница авторизации](login1.png)

Иллюстрации к примерам с использованием testdrive не переводим, пока не переведен сам пример.

Грамматика

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

Список терминов

• action — действие.
• active record — без перевода.
• attach handler — «назначить обработчик».
• attribute of the model — атрибут модели.
• camel case — без перевода.
• customization — (тонкая) настройка //Ранее встречался перевод "кастомизация", желательно этот вариант по возможности не использовать.
• column — столбец (если речь про БД).
• content — содержимое.
• controller — контроллер.
• debug (mode) — отладочный (режим) (см. production mode).
• eager loading — метод жадной загрузки/жадная загрузка (см. lazy loading).
• PHP extension — расширение PHP.
• field (of the table) — поле (или атрибут) таблицы.
• framework — фреймворк.
• front-controller — фронт-контроллер.
• getter — геттер.
• (event) handler — обработчик (события).
• hash — хэш.
• helper - помощник.
• id — идентификатор.
• instance — экземпляр.
• lazy loading — отложенная загрузка (загрузим как понадобится и не раньше).
• method — метод (объекта) //Внимание! У объета/класса нет функций, есть только методы.
• model — модель, модель данных.
• model form — модель формы.
• parameter — параметр (у метода или функции, никак не у класса).
• to parse — обрабатывать, если контекст непонятен — парсить.
• placeholder — маркер.
• production (mode) — производственный (режим) (см. debug mode).
• property — свойство (объекта).
• to render — рендерить, формировать.
• related, relation — связанный, связь.
• resolve request — предварительная обработка запроса.
• route — маршрут.
• row (of the table) — строка (таблицы).
• setter — сеттер.
• tabular input — табличный ввод.
• to validate — проверять.
• valid — корректный.
• validator — валидатор.
• validator class — класс валидатора.
• view — представление.
• query builder — конструктор запросов.

Работа с репозиторием

Для переводов используется основной репозитарий. Изменения предлагаются в виде pull-request, как это описано в «Git workflow for Yii contributors».

Поддержка актуальности перевода

Поскольку периодически в оригинал вносятся изменения, то необходимо следить за актуальностью перевода и своевременно вносить правки.

Для того, чтобы немного упростить данную задачу есть несколько инструментов, а именно build message и build translations report.

Для использования необходимо перейти в директорию build и затем в консоли набрать:

build message ../framework/messages/config.php
build message ../requirements/messages/config.php

build translations report --sourcePath="../docs/guide" --translationPath="../docs/guide/ru" --title="Russian guide translation report" > report_guide_ru.html

build translations report --sourcePath="../docs/blog" --translationPath="../docs/blog/ru" --title="Russian blog translation report" > report_blog_ru.html

build translations report --sourcePath="../framework/views" --translationPath="../framework/views/ru" --title="Russian framework views translation report" > report_views_ru.html

Это даст нам:

1. Обновлённые сообщения фреймворка и страницы проверки требований (полученные файлы нужно просмотреть и обновить).
2. Три отчёта report_guide_ru.html, report_blog_ru.html, report_views_ru.html. В репозиторий их включать не следует.