Skip to content

How to create a multilingual website or documentation project with MkDocs, material, and Langly?

How to create a multilingual website or documentation project with MkDocs, Material, and Langly Designed by Freepik

For anyone who wants to create a multilingual website, MkDocs in combination with the Material theme and the Langly plugin offers an excellent solution. This article describes in detail how to create an international website or documentation project with MkDocs, Material and Langly. The instructions cover the preparation of the project, the installation of MkDocs and Material and the subsequent translation of the content with Langly.

Prerequisites

In order to follow these instructions, some prerequisites are required. In principle, different ways are possible, but to keep everything as simple as possible, the steps shown here are carried out in Visual Studio Code.

  • A GitHub account to publish the web project later.
  • Python and Git must be installed on the system
  • Visual Studio Code and the required extensions for working with Python
  • A DeepL-Free or higher account.

Here we go

Warning

Before we start, I would like to urge you to pay special attention to the point DeepL-Api-Key provide and protect. It is important that the auth_key.json file in the .gitignore is excluded in order to protect the Api key and ensure the security of your data.

Create GitHub repository

As the website or documentation is to be published on the Internet (GH pages) later, a GitHub repository is required. You can create this via the GitHub website, which is recommended, as this also allows you to create a .gitignore, which is also absolutely necessary for this HowTo.

Click on New in the GitHub dashboard and the fun begins.

  1. Enter any Repository-Name.
  2. Under Add .gitignore please select Python.
  3. And click on Create Repository.

All other fields are optional for this example but should of course be adapted to your own requirements.

Clone repository

To clone the previously created repository, navigate to source code management in VS Code and then to Clone repository. After selecting the repository with the name previously created on GitHub, the repository is cloned into the selected working directory.

Set up a virtual Python environment

If Python is installed on the system and the PATH variable is set, setting up the venv is very simple. You just press the F1 in VS Code and select Python: Create environment... from.

In the following dialog, select Venv and then the interpreter path of the installed or preferred Python version.

Boom! There's a venv.

Visual Studio Code normally activates the venv automatically when a Python file is opened, but in our case the venv is first required for the installation of MkDocs and material and there is no Python file in the project directory.

So navigate via the integrated terminal in the project root directory to the .venv and then to the Scripts and activatethere.

A (.venv) should now appear in front of the path in the terminal.

Further and more detailed information can be found on this website: Python Environments in VS Code

Venv activate

Set up MkDocs

To install MkDocs, execute the following command in the terminal.

pip install mkdocs

After all dependencies have been installed, we still need to create the project. To do this, the following command is executed in the terminal.

mkdocs new .

Now comes the test. To do this, we execute the serve again.

mkdocs serve

If everything went well, the MkDocs homepage should appear in the browser at http://127.0.0.1:8000/.

MkDocs

Set up material theme

To install the material theme, execute the following command in the terminal.

pip install mkdocs-material

After installation, the material theme must be activated in the mkdocs.yml To do this, the following entry is added to the file.

site_name: <Your Site Name>
theme:
  name: 'material'

The material theme should then also be activated with the next mkdocs serve.

Material Theme

Set up Langly plugin

Now install the Langly plugin. To do this, execute the following command in the terminal.

pip install mkdocs-material-langly

After installation, the Langly plugin must be activated and set up in the mkdocs.yml. To do this, the source and targets values must be filled in with the desired languages. The source language is the language in which the website or documentation is created, while the target languages are the languages into which the website or documentation is to be translated.

Warning

It is important that the Langly plugin is listed last in the order of the plugins.

plugins:
  - search
  - langly:
      lang_switch: true
      source:
          name: English
          lang: en
      targets:
        - name: Deutsch
          lang: de
        - name: Español
          lang: es
        - name: Français
          lang: fr
        - name: Italiano
          lang: it

The languages selected here are only examples and can of course be adapted to your own project.

Provide and protect DeepL api key

The DeepL API key is now required. This can be obtained by creating a DeepL free account. As soon as the api key has been generated, a file with the name auth_key.json is created in the main directory of the project and the api key is entered there.

{
    "deepl": "DEEPL-API-KEY"
}

Warning

Please exclude the Api key in the .gitignore and protect it in every possible way from being uploaded to the Internet.

To achieve this, a new line is added to the end of the .gitignore. As we have already created it when creating the repository at GitHub, it can now be easily opened and edited.

auth_key.json

Start translation

Now we are basically ready to start translating. To achieve this, the content to be translated in the Markdown files is simply masked and the Langly plugin takes care of the rest. The masking is done by enclosing the text to be translated with [[ and ]].

Let's just try it out on the index.md, which is located in the docs directory in the project.

This looks like this at the moment.

# Welcome to MkDocs

For full documentation visit [mkdocs.org](https://www.mkdocs.org).

## Commands

* `mkdocs new [dir-name]` - Create a new project.
* `mkdocs serve` - Start the live-reloading docs server.
* `mkdocs build` - Build the documentation site.
* `mkdocs -h` - Print help message and exit.

## Project layout

    mkdocs.yml    # The configuration file.
    docs/
        index.md  # The documentation homepage.
        ...       # Other markdown pages, images and other files.

Simple masking is completely sufficient. Focus on the specific texts that need to be translated and avoid excessive masking. This means that you should only enclose the relevant parts of the text with the masking characters [[ and ]] to enable a more precise translation. If there are several sentences, the entire section should of course be masked so that DeepL can better understand the context.

In our example, this would make the most sense.

# [[Welcome to MkDocs]]

[[For full documentation visit]] [mkdocs.org](https://www.mkdocs.org).

## [[Commands]]

* `mkdocs new [dir-name]` - [[Create a new project.]]
* `mkdocs serve` - [[Start the live-reloading docs server.]]
* `mkdocs build` - [[Build the documentation site.]]
* `mkdocs -h` - [[Print help message and exit.]]

## [[Project layout]]

    mkdocs.yml    # [[The configuration file.]]
    docs/
        index.md  # [[The documentation homepage.]]
        ...       # [[Other markdown pages, images and other files.]]

The next time mkdocs serve is executed, all masked texts are automatically translated, the delimiters are removed and the source and target languages are displayed correctly on the page. The language menu then allows you to navigate to the individual language versions.

As long as serve is activated, all translations are displayed as drafts in order to reduce access to the translation api. If serve, build or gh-dploy are called again, the translations are continued and the drafts are removed.

Manually refine the translation

If the automatic translation is insufficient or certain characters or formatting have not been translated correctly, it is possible to edit the corresponding JSON files in the locales directory in the main directory of the project.

The content of the index.json of the German language version now looks like this.

{
    "Welcome to MkDocs": {
        "__active__": true,
        "de": "Willkommen bei MkDocs"
    },
    "For full documentation visit": {
        "__active__": true,
        "de": "Die vollst\u00e4ndige Dokumentation finden Sie unter"
    },
    "Create a new project.": {
        "__active__": true,
        "de": "Erstellen Sie ein neues Projekt."
    },
    "Start the live-reloading docs server.": {
        "__active__": true,
        "de": "Starten Sie den live-reloadenden Doku-Server."
    },
    "Build the documentation site.": {
        "__active__": true,
        "de": "Erstellen Sie die Dokumentationsseite."
    },
    "Print help message and exit.": {
        "__active__": true,
        "de": "Hilfemeldung drucken und beenden."
    },
    "Project layout": {
        "__active__": true,
        "de": "Projekt-Layout"
    },
    "The configuration file.": {
        "__active__": true,
        "de": "Die Konfigurationsdatei."
    },
    "The documentation homepage.": {
        "__active__": true,
        "de": "Die Homepage der Dokumentation."
    },
    "Other markdown pages, images and other files.": {
        "__active__": true,
        "de": "Andere Markdown-Seiten, Bilder und andere Dateien."
    }
}

Each data record contains the language key as an attribute name, while the translated text is displayed as a value in the subordinate de attribute. As long as the language key remains constant, Langly will always use the text of the de in this example. If the language key is accidentally changed, Langly can no longer carry out the assignment correctly, which results in the translation being carried out again and the manipulated data record being removed.

The __active__ is used by Langly to determine whether the data set is still required and removes it the next time it is executed.

Conclusion

From this point on, you can follow the documentation and HowTo's from MkDocs or Material to further expand your website. The Langly plugin will automatically translate the masked texts.

That's all there is to it. Have fun creating your multilingual website or documentation with MkDocs, Material and Langly.

Good luck!