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

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

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

Исходники документации можно найти в нашем репозитории 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 (это платное приложение, но оно стоит своих денег), тогда вы сможете заниматься работой с переводом в дороге с помощью телефона или планшета.
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.