Configuration¶

Always put mdpo plugin in mkdocs.yml file after other plugins which could edit the content of your files:

- plugins
  - search
  - include-markdown
  - mdpo
  - minify

Languages¶

languages (list)*¶

Languages to translate your files into. Commonly defined as ISO 639 codes.

default_language (str)¶

Original language of your files. If not defined, the first language found in languages will be used.

Layout¶

locale_dir (str)¶

Directory where the PO translation files will be placed. If not defined, the root of your documentation (docs_dir setting) will be used, which will not allow you to use the command mkdocs serve. The default layout would be something like:

plugins:
  - mdpo:
      languages:
        - en
        - es
        - fr

📁 docs
├── 📁 es
│   └── 📄 index.md.po
├── 📁 fr
│   └── 📄 index.md.po
└── 📄 index.md

The problem with this layout is that doesn't allow you to use the command mkdocs serve.

The recommended practice is to organize your docs/ directory in multiple subdirectories, one for documentation files, other for translation files, other for theme overrides...

docs_dir: docs/src

plugins:
  - mdpo:
      languages:
        - en
        - es
        - fr
      locale_dir: ../locale

📁 docs
├── 📁 locale
│   ├── 📁 es
│   │   └── 📄 index.md.po
│   └── 📁 fr
│       └── 📄 index.md.po
└── 📁 src
    └── 📄 index.md

lc_messages (bool or str)¶

In the world of program translation is common the creation of a LC_MESSAGES/ folder inside the language directory. If you need it you can set this setting as true, but if you want another folder name, you can pass a string, or even a relative path to create more than one folder between the language directory and their content:

plugins:
  - mdpo:
      languages:
        - en
        - es
        - fr
      locale_dir: locale
      lc_messages: true

📁 docs
├── 📁 locale
│   ├── 📁 es
│   │   └── 📁 LC_MESSAGES
|   │       └── 📄 index.md.po
|   └── 📁 fr
|       └── 📁 LC_MESSAGES
│           └── 📄 index.md.po
└── 📄 index.md

plugins:
  - mdpo:
      languages:
        - en
        - es
        - fr
      locale_dir: locales
      lc_messages: my-own/subdir

📁 docs
├── 📁 locales
│   ├── 📁 es
│   │   └── 📁 my-own
|   │       └── 📁 subdir
|   |           └── 📄 index.md.po
|   └── 📁 fr
|       └── 📁 my-own
│           └── 📁 subdir
|               └── 📄 index.md.po
└── 📄 index.md

dest_filename_template (str)¶

Template for destination file name inside site/ directory. This is a valid Jinja2 template string that will be used to define where should be placed the generated translated file inside the site/ directory.

The default value is {{language}}/{{file.dest_path}}, being file the original documentation file and language the language of the translation.

The context for the template includes:

• language: Translation language for the file.
• file: The original Markdown file object inside your documentation directory.
• All the configuration settings of the plugin such as languages, default_language, lc_messages, locale_dir, dest_filename_template itself...

Content¶

translate (list[str])¶

Configuration settings to translate. Currently only the next settings are supported:

• site_name
• site_description

cross_language_search (bool)¶

It configures if the search plugin of the theme will search through all languages. By default is enabled. You can disable it to restrict the search to the active language.

The support for this feature currently includes the mkdocs-material theme, the Mkdocs theme, the Readthedocs theme and all themes which are using the builtin Mkdocs search plugin.

min_translated_messages (str or int)¶

Minimum number or percentage of messages in all files to include the translated pages for a language. An information message will be displayed if a language does not reach the minimum translation requirements.

Specify as a string ending with % like 55% for percentages of total messages or as an integer like 76 to determine the minimum number of translated messages required to include a language.

plugins:
  - mdpo:
      languages:
        - en
        - es
      min_translated_messages: 95%

plugins:
  - mdpo:
      languages:
        - en
        - es
      min_translated_messages: 50

exclude (list[str])¶

Exclude certain files from being translated, still creating copies of original ones in target languages. Accepts relative paths to files from docs_dir (documentation directory).

This setting is useful if you want, for example, to exclude a changelog file from being translated:

plugins:
  - mdpo:
      languages:
        - en
        - es
        - fr
      locale_dir: locale
      exclude:
        - changelog.md

📁 docs
├── 📁 locale
│   ├── 📁 es
│   │   └── 📄 index.md.po
|   └── 📁 fr
|       └── 📄 index.md.po
├── 📄 changelog.md
└── 📄 index.md

ignore_extensions (list[str])¶

File extensions that are ignored from being added to site directory, defaults to ['.po', '.pot', '.mo'].

ignore_msgids (list[str])¶

You can ignore certain messages from being dumped into PO files adding them to this list.