MkDocs translations with gettext PO files and Read the Docs hosting

[kattni]

I'm super excited to share my first open source project: MkDocs PO I18n! I designed tooling to handle translations of MkDocs documentation, using PO files, and hosted on Read the Docs. This project came out of a proof-of-concept I'm working on for another open source project to consider switching the documentation from Sphinx to MkDocs. One set of documentation is available in several languages, so translations using the existing workflow were a necessary feature if the switch were going to happen. It initially seemed like we weren't going to be able to move forward with the switch, based on this lengthy discussion. Ultimately, I ended up writing a viable solution.

Installation

It is currently installable from the GitHub repo.

Basic details

I am using tools from the Translate Toolkit, built into four custom Python scripts:

• The build_pot_translations script generates the PO template files from the Markdown documentation, using md2po with the --pot flag.
• The build_po_translations script uses pot2po in a temp directory to build the language-specific PO files from the PO template files for each provided language.
• The build_md_translations script uses po2md in a temp directory to temporarily generate translated Markdown in each provided language, and mkdocs build to build the site for each language from the translated Markdown.
• The live_serve script defaults to English, but accepts any single language code. This live-serves uses mkdocs serve to serve a copy of the site locally in your primary documentation language. This script uses a temp directory to serve the site with the appropriate configuration files.

Available options for each tool

• build_md_translations
  • You must supply at least one language code to build that language. You can optionally supply multiple language codes, separated by spaces, to build in more than one language at the same time.
  • --output/-o: Allows you to specify the build output directory. Defaults to /_build/html/ in your project directory.
  • --build-with-errors/-e: You can optionally supply this flag to allow building with errors. The build defaults to building with --strict, which will cause it to fail on any warnings or errors.
  • --source-code/-s: Allows you to provide a source code directory to include in the build. Necessary if you are using mkdocstring to include class documentation. This flag can be provided more than once to include more than one source code directory.
• build_po_translations
  • You must supply at least one language code to build that language. You can optionally supply multiple language codes, separated by spaces, to build in more than one language at the same time.
• live_serve
  • If your primary documentation language is English, you do not need to provide a language code. If the primary language is something else, you need to provide the language code.
  • watch_directory: Include a directory or multiple directories to watch for changes; adding directory names here will mean making changes in those directories while live-serving the site will trigger an automatic rebuild with those changes. You can supply multiple directories, separated by spaces.
  • --build-with-errors/-e: You can optionally supply this flag to allow building with errors. The build defaults to building with --strict, which will cause it to fail on any warnings or errors.
  • --source-code/-s: Allows you to provide a source code directory to include in the build. Necessary if you are using mkdocstring to include class documentation. This flag can be provided more than once to include more than one source code directory.

Configuration and set up

MkDocs is configured using a base config.yml file inherited by a series of mkdocs.language-code.yml files (e.g. English is mkdocs.en.yml, French is mkdocs.fr.yml, etc.) stored in the /docs/ directory. The language code files are minimal, but include the language-specific configuration options. The config.yml file has all shared configuration. Documentation is stored in the /docs/en/ (or whatever primary language code) directory.

You will generate the PO template files first, followed by the various language PO files.

If you intend to publish to Read the Docs, you'll need to push a .readthedocs.yaml file to your repo, set up the parent project on RTD in your primary language connected to your documentation repo, and add translation projects for each desired translation.

Push your content and configuration files to your repo. RTD will build the documentation with any updates.

It's straightforward to use this workflow with CI for automatically updating the translations when you update your content.

Write-up, documentation, and source code

I've written a blog post on how to use it: https://kattni.com/mkdocs-po-i18n-mkdocs-translations-with-po-files-and-read-the-docs

I've also published documentation for it to RTD: https://mkdocs-po-i18n.readthedocs.io/en/latest/

You can find the project here: https://github.com/kattni/mkdocs-po-i18n/

Thank you for reading!