Sphinx provides a internationalization (i18n) feature. If you translate some sphinx document without using the i18n feature, you need to rewrite original document source files. But this approach has three problems:

1. You must be careful to maintain reStructuredText structure.
2. It's hard to divide translation tasks for a number of volunteer translators.
3. It's hard to pursue the upstream document source that is frequently updated.

And so, sphinx i18n feature will support our translation. Since Sphinx supports extracting/injecting gettext format translation catalog, you can use helpful tools/services easily that provide translation support features like a translation memory, recommending similar translation, glossary and auto-translation. By using such translation support services, document translation with Sphinx can be carried out as follows:

1. You can translate for each paragraphs (Sphinx will output gettext msgid for paragraphs).
2. You can translate more than one person at the same time.
3. You can use helpful translation support features.

If you use such a service, volunteers are more likely to participate in the translation. Sphinx-users.jp team built a translation flow with using sphinx and the transifex service. In addition, we have automated the entire process using the drone.io service.

As a result of this, (A) translation source entries on the transifex will be updated automatically when original documentation is changed. (B) translated document page will be updated when each entries is translated on the transifex. In this session, I'll explain 3 things; (1) entier process to translate sphinx docs. (2) automation mechanism for the process. (3) tips, tricks and traps for wrinting docs and translating.

Outline:

• Self introduction (2 min)

• Sphinx introduction (2 min)

  • What is Sphinx?
  • Sphinx examples

• How do you translate Sphinx documentation? (5 min)

  • Rewriting source files
  • ...

• Sphinx i18n feature (5 min)

  • make pot files by using "make gettext"
  • translate pot files into po files
  • build a translated document by using translated gettext catalogs

• Automated translation process with several services (10 min)

  • github push web hook invoke drone.io
  • drone.io executes "make gettext" and uploads pot files to transifex
  • transifex translation
  • transifex invoke web hook drone.io
  • drone.io executes "make html" with using po files and deploy html files

• tips, tricks, traps (10 min)

References:

• http://sphinx-doc.org/intl.html
• http://docs.sphinx-users.jp/intl.html
• https://drone.io/bitbucket.org/shimizukawa/sphinx-doc13