Appendices

A little about gettext

If you are not a developer but rather a documentation or localization specialist (like I am), you probably do not need to know about gettext in detail. It is enough to know some general facts:

• Gettext uses a message-as-key approach: there are no string resource identifiers in the source code, gettext uses the natural language strings inside the source code as keys for looking up translations. If no translation is available, gettext returns the original string.

  In my experience with Sphinx, the source language does not have to be English. I translated documentation from Russian to English, and everything worked perfectly.

• Gettext is not specific for Python, as it is used in C, C++ development etc. Every time you work with .po files it almost certainly means that gettext is behind the scenes.

• Gettext supports plural forms. We do not cover this feature in our guide, but it’s nice to know about the possibility.

Useful links

Sphinx documentation:

• Sphinx Getting Started: https://www.sphinx-doc.org/en/master/usage/quickstart.html

• Internationalization with sphinx-intl: https://www.sphinx-doc.org/en/master/usage/advanced/intl.html

• Options for internationalization: https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-internationalization

• Filename format for language-specific figures: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-figure_language_filename

• Ifconfig: https://www.sphinx-doc.org/en/master/usage/extensions/ifconfig.html

• Sphinx-build: https://www.sphinx-doc.org/en/master/man/sphinx-build.html

• Jinja templates in Sphinx: https://www.sphinx-doc.org/en/master/templating.html

Readthedocs documentation:

• Getting Started with Sphinx: https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html

• Manage Translations for Sphinx projects: https://docs.readthedocs.io/en/stable/guides/manage-translations-sphinx.html

Transifex documentation:

• Transifex organizations, projects and resources: https://help.transifex.com/en/articles/6656105-introduction-to-projects-and-resources

• GitHub integration: https://help.transifex.com/en/articles/6265125-github-via-transifex-ui

• Transifex Editor: https://help.transifex.com/en/articles/6318216-translating-with-the-web-editor

GitHub Pages documentation:

• https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages

Other:

• Miniconda commands: http://miniconda.geekwriter.ru/en/conda-commands.html

• Alabaster template sidebar: https://alabaster.readthedocs.io/en/latest/installation.html

Demo project files

Here you can find all the archives that are offered for download in the sections of this guide:

• Create virtual environment: requirements.txt

• Add content: index.rst and easter-egg.rst

• Add images: logo.png and egg.png; conf.py and easter-egg.rst

• Install and configure sphinx-intl: conf.py

• Translate text in .po files: translation lists, translated .po files

• Add language-specific images: egg.ru.png and egg.pt_BR.png

• Add conditional content with ifconfig: conf.py and index.rst

• Update translation: updated index.po for Russian and Portuguese

• Add language switcher: switcher.html and conf.py, start page files (index.html and images)

You can also find the demo project on Github.