Add support for localization

[adorilson]

It would be wonderful if each student can to read the documentation (in a first moment, and the source-code comments in a second moment) in your own idiom, not only English.

[rffontenelle]

Maintainer, in order to internationalize this project's documentation, which my tests indicate to be the whole site, it only takes the following tasks:

How to add support to localization

1. Fix internationalization of docs/_templates/gumroad.html file, replacing text with {{ _('text') }}; otherwise, "Donate" and other texts in this file would not be available for translation
2. Generate translation template (.pot) files by running make gettext from docs/; all pot files will be stored in _build/gettext/
3. Generate translation (.po) file for desired language by running sphinx-intl update -p _build/gettext -l <lang>, where <lang> is one of the supported languages.
4. Add the recently generated language to languages = line in docs/conf.py, and translation can now be updated by running make gettext Run sphinx-intl update whenever it is needed to update translation of all languages locally.

See Internationalization and Options for internationalization in Sphinx documentation for more info.

Optional: internationalize literalincludes too

The source code and its comments that are currently being included via literalinclude in the .rst files can be made available for translation by adding gettext_additional_targets = ['literal-block'] to docs/conf.py (See documentation). The good thing about this is that the translator can translate comments of the source file that are displayed in the documentation. The downside of this configuration is that the whole code—not only the comments—shows up as a single string for translation. In this case, the translator would have to be careful to not translate things that shouldn't be translated.

Using translation platform to ease translation task

Consider using a web translation platform, which truly eases translator job — allows the translator to focus on translating task, not in figuring things out how to run po update commands. If this is the chosen path, I recommend Weblate as it provides GitHub webhooks for continuous localization, a very nice web translation interface, and it is free for free software projects.

[grantjenks]

Localization support is already present in Sphinx. I’m open to a pull request with translations but I am only fluent in English.