Как помочь с переводом?
Основные инструменты для перевода - желание и знание английского. Про остальное сейчас быстренько расскажем.
Исходники документации можно найти в нашем репозитории 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>`_
- Gtranslator кажется работает и на Windows
- Poedit альтернатива Gtranslator
- Ando, его лучше использовать совместно с PocketGit (это платное приложение, но оно стоит своих денег), тогда вы сможете заниматься работой с переводом в дороге с помощью телефона или планшета.