Как помочь с переводом?

Ruslan Popov edited this page May 26, 2016 · 16 revisions
Clone this wiki locally

Основные инструменты для перевода - желание и знание английского. Про остальное сейчас быстренько расскажем.

Исходники документации можно найти в нашем репозитории https://github.com/djbook-ru/django_documentation. Это копия исходников оригинальной документации Django с небольшими изменениями в конфигурации и шаблонах. Для сборки документации используется Sphinx. С его помощью мы создаём файлы перевода (.po) для gettext, которые он использует при создании русской версии документации. Файлы перевода мы обновляем самостоятельно, так что вам необходимо просто их переводить и использовать созданные нами команды для сборки русской версии документации.

Начало

Вам необходимо установить gettext и git. Делаем fork репозитория. Клонируем созданный репозиторий. Не будем это описывать, пускай это будет тестом на профпригодность.

Устанавливаем необходимые пакеты:

$ pip install -r djbook/requirements.txt

Для работы с переводом мы создали CLI приложение. Для сборки русской версии документации выполните:

$ ./translator.py create

В каталоге _build/html создалась HTML версия документации.

Перевод

Перед началом перевода желательно создать топик на форуме http://djbook.ru/forum/forum/20/ и забронировать страницу доки. Файл для перевода лучше выбирать через страницу статистики.

.po файлы находятся в каталоге ’locale/ru/LC_MESSAGES’. Один файл на одну страницу документации. Расположение файла соответствует расположению HTML файла документации. Текст для перевода содержит элементы форматирования reStructuredText, о котором можно почитать в документации Sphinx. Вам не обязательно знать reStructuredText, просто заменяйте английский текст на русский, примеры можно посмотреть в уже переведенных файлах.

Открываем файл для перевода в вашем любимом редакторе .po файлов, переводим и заново собираем документацию. Открываем переведенную страницу и проверяем все ли нормально отображается.

Настоятельно рекомендуем выполнить команду ./translator.py spellcheck. Работает не идеально, но помогает найти опечатки. Если не знаете как исправить термин, можете поискать подходщий в spelling_ignore.txt.

Делаем commit и присылаем pull request.

Советы

Проблемы с ссылками

В оригинале часто используют ссылки следующего вида:

`define and send your own custom signals`_

То есть где-то в исходниках встречается:

.. _define and send your own custom signals: `defining and sending signals`_

указывая настоящее имя ссылки.

Sphinx при переводе сначала подставляет перевод, потом рендерит html. В результате Sphinx будет пробовать получить ссылку с русский названием, которая не определена в документе.

Необходимо явно указать ссылку используя http://sphinx-doc.org/markup/inline.html#ref-role. На странице есть ссылка "Показать исходный текст". В исходном коде находим определение "define and send your own custom signals":

.. _define and send your own custom signals: `defining and sending signals`_

"defining and sending signals" преобразуем в название метки заменяя пробелы на дефисы. Получаем:

:ref:`определять и посылать свои собственные сигналы <defining-and-sending-signals>`

Для ссылок на внешние ресурсы используется немного другой подход:

.. _`official Vary spec`: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.44

"official Vary spec_" преобразуем в:

`official Vary spec <http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.44>`_

Редакторы .po

  • Gtranslator кажется работает и на Windows
  • Poedit альтернатива Gtranslator
  • Ando, его лучше использовать совместно с PocketGit (это платное приложение, но оно стоит своих денег), тогда вы сможете заниматься работой с переводом в дороге с помощью телефона или планшета.