Translate! build your docs on any language

The Markdown-I18n Extension

By default, mkdocs has no translation engine.

We added the Markdown-I18n as a translation engine. Running the docs with this extension enabled in the configuration file (mkdocs.yml), the "locales/messages.pot " file will be generated/updated. And if there is one, the specified language in the extension load will charge the translations in the "locales/language/LC_MESSAGES/messages.po".

You can load this extension with this sample code:

markdown_extensions:
  - markdown_i18n:
      i18n_lang:  es_ES
      i18n_dir:   locales

This will specify:

• The language as "es_ES"
• The default directory as "locales/ "

Steps to translate

We are using the sample code of the last section as the configuration file.

The default language doesn't need to be specified.

Running build or serve using the configuration file with the extension will generate/update the locales/messages.pot, that has all the translatable strings.

You may use "msgmerge -U locales/messages.pot locales/es_ES/LC_MESSAGES/messages.po" to update the translated strings file.

Then edit the pofile (locales/es_ES/LC_MESSAGES/messages.po) using any editor. The Edit date must be updated.

It's recommended to use poedit as it's user-friendly

When you are done translating, build again using the configuration file with the extension and it'll load the translated strings.

The translate.sh

We've done a script to make it easier to translate. As you should see if you open it, it does the steps of the section above.

It also deletes the old pot file to avoid cache problems, and runs the test after editing the pofile.