Translate our docs to other languages

[sfmig]

I had a go during our hackathon at translating our docs --> work on this branch smg/docs-language

References:

• this blog post
• the sphinx docs

How to build the documentation in another language

1. From the docs folder, run make clean html
2. Run make gettext
   ----> generates .pot files under build/gettext/
3. Run sphinx-intl update -p build/gettext -l de
   ----> generate .po files under locales/de/LC_MESSAGES
4. mv locales source
   ---> From the docs, I am not sure why locales is not created under
   source by default, but otherwise it won't pick up the translations
   in the .po files.
5. Add translations to messages in .po files using the translate.py script
   python translate.py <language-code> <po-files-directory>
6. Build the html files form the translations
   make -e SPHINXOPTS="-D language='de'" html

Some observations

• Some default sphinx bits get translated automatically which is nice.
  • For example, Search --> Suche.
• In principle, the main bits of text need to be translated manually but this can be automated. I had a go at using a wrapper around google translate API (following this gist) in the translate.py script.
• With the steps specified above we overwrite our build dir, but ideally we generate it separately directory (like _build). This seems very possible from the references above, just needs a bit of digging.
• An even nicer implementation is to eventually treat different languages as different versions of the docs.
• Once this is polished, it would be nice if we wrap the sphinx commands in make.