Setting up multi-language installations

[koen-yesplan]

As requested by @squidfunk, this recipe describes how to set up a multi-language installation using Material for MkDocs. It's not exactly rocket science, but may serve as a guide for people who have to start from scratch.

For this recipe, we use three languages: Dutch (NL), English (EN) and French (FR). If you're building a simple site, only the first few sections of this recipe will be relevant to you. The other sections deal with more complex issues that pop up when creating multi-language sites: content shared between languages and managing URLs.

General Principle

Multi-language documentation is actually created using three separate MkDocs builds, one for each language. This has some consequences for the setup:

• Three configuration files
• Three folders for markdown files in the docs/ folder
• Three folders for the HTML in the output folder generated/
• Optional: in the includes/ folder, three files for the URLs used in the markdown.

Shared files - such as the logo, favicon and stylesheets - are stored in the overrides/assets/ folder.

One small disadvantage is that you cannot use the mkdocs serve command to serve your site locally with all three languages. MkDocs can only serve one language at the time.

File Structure

The project directory has the following structure:

.
├─ config/
│    ├─ en/
│    │  └─ mkdocs.yml
│    ├─ fr/
│    │  └─ mkdocs.yml
│    └─ nl/
│        └─ mkdocs.yml
│
├─ generated/
│    ├─ en/
│    ├─ fr/
│    └─ nl/
│
├─ includes/
│    ├─ developers/
│    │   └─ api.md
│    │
│    ├─ urls-en.md
│    ├─ urls-fr.md
│    └─ urls-nl.md
│
├─ docs/
│    ├─ en/
│    │   ├─ index.md 
│    │   └─ developers.md
│    ├─ fr/
│    │   ├─ index.md 
│    │   └─ developers.md
│    └─ nl/
│        ├─ index.md 
│        └─ developers.md
│
└─ overrides/
     ├─ assets/
     │   ├─ images/
     │   │    ├─ favicon.ico
     │   │    └─ logo.svg
     │   │
     │   └─ stylesheets/
     │        └─ yesplan.css
     │
     └─ partials/
              └─ header.html

Configuration Files

In the three configuration files, you can set options for the separate languages. Below, you will find slimmed-down examples for English and Dutch. We use many more extensions and plugins, but they are irrelevant for the recipe.

Some things to bear in mind:

• It is hard to maintain the same CSS or images in three locations (docs/en/, docs/fr/ and docs/nl/). Therefore, the logo, favicon and CSS are shared by all the languages and have been moved to the overrides/assets/ folder. This configuration deviates from the main Material for MkDocs documentation.
• The language key is used for:
  • The value of the lang attribute in the html tag
  • The buttons "Previous", "Next" etc. (see Changing the language)
  • The language selection in the header (see below)
  • Conditions that check the site's current language, for instance to show an announcement in the correct language (see below).
• For the navigation, you should simply add the path starting from the folder set in the docs_dir key. So in this case, use index.md and not docs/en/index.md.

English

site_name: 'Manual'
docs_dir: '../../docs/en'                           # Where to find the English markdown files
site_dir: '../../generated/en'                      # Where to put the English HTML files

theme:
    name: material
    custom_dir: '../../overrides/'                  # This is where the customization of the theme lives
    logo: assets/images/logo.svg                    # The logo is shared by all languages
    favicon: assets/images/favicon.ico              # The favicon is shared by all languages
    language: en                                    # The build's language

extra_css:
  - assets/stylesheets/yesplan.css                  # CSS is shared by all languages

extra:                                              # Language Selection
  alternate:  

      # Switch to English
    - name: English
      link: /en/
      lang: en

    # Switch to Dutch
    - name: Nederlands
      link: /nl/
      lang: nl

    # Switch to French
    - name: Français
      link: /fr/
      lang: fr

plugins:
  - search:                                         
      lang: en                                      # Set language for search

nav:
- Welcome: index.md

Dutch

site_name: 'Handleiding'
docs_dir: '../../docs/nl'                           # Where to find the English markdown files
site_dir: '../../generated/nl'                      # Where to put the English HTML files

theme:
    name: material
    custom_dir: '../../overrides/'                  # This is where the customization of the theme lives
    logo: assets/images/logo.svg                    # The logo is shared by all languages
    favicon: assets/images/favicon.ico              # The favicon is shared by all languages
    language: nl                                    # The build's language

extra_css:
  - assets/stylesheets/yesplan.css                  # CSS is shared by all languages

extra:
  alternate:                                        # Language Selection

     # Switch to English
    - name: English
      link: /en/
      lang: en

    # Switch to Dutch
    - name: Nederlands
      link: /nl/
      lang: nl

    # Switch to French
    - name: Français
      link: /fr/
      lang: fr


plugins:
  - search:                                         
      lang: nl                                      # Set language for search

nav:
- Welkom: index.md

Language Selection

Material for MkDocs offers a nice solution out of the box from version 7.0.0 onwards: see Site Language Selector for more information. The examples above use the native Material for Mkdocs selector.

You can also extend the theme and use a condition like the one for announcements to build your own selector. In that case, be very careful when upgrading mkdocs-material, since the code you are overriding may change over time.

Language Detection

What if you want to use announcements? They are set globally by extending the theme, but you want your announcement to appear in the correct language, right? In that case you can detect the language using a condition:

{% block announce %}
{% if config.theme.language == 'nl' %}
Welkom!
{% elif config.theme.language == 'en' %}
Welcome!
{% else %}
Bienvenue !
{% endif %}
{% endblock %}

Putting it all together

Creating the HTML for these files is now simply a matter of executing three commands. If you are in the root of your project:

mkdocs build -f config/en/mkdocs.yml
mkdocs build -f config/fr/mkdocs.yml
mkdocs build -f config/nl/mkdocs.yml

You can then push the generated files to a web server. In the past, we used ant to execute the tasks, but we now use Docker.

Shared Content

Sometimes, content may be shared across all languages. For instance, our documentation for developers is always in English and should appear in the sections for all three languages: English, French and Dutch. However, I don't want to maintain the same content in three places, since this will certainly lead to errors.

Simple

If this documentation does not contain URLs to other language-specific files (e.g. /en/what-is-an-event.md), you can simply use Snippets.

For instance, in the docs/en/, docs/fr/ and docs/nl/ folder, you can add a file developers.md with the following contents:

--8<-- "../../includes/developers/api.md"

This will include the one file in all three languages. You only have to maintain the file includes/developers/api.md and it will appear correctly in all languages. Note that the path you use for the snippet is relative to the mkdocs config file.

Not That Simple

In our case, the situation was a bit more complex. The shared content for developers contained many links to documentation in the different languages, e.g. to refer to concepts, actions, interfaces etc. If we included one file with hard-coded URLs, these links would always refer to one single language.

This was solved by using reference links in a separate file and including it with snippets (see "Managing URLs" below).

For English, the file developers.md would look like this:

--8<-- "../../includes/developers/api.md"

--8<-- "../../includes/urls-en.md

But for Dutch, you include a different URL file:

--8<-- "../../includes/developers/api.md"

--8<-- "../../includes/urls-nl.md

That way, you only have to maintain one file (api.md), but you can still use different URLs for every language.

Managing URLs (Optional)

More languages means more URLS: currently, our documentation has about 600 URLs across all languages. This is quite complex:

• If you change a (sub)heading, you also change the anchor to that heading, resulting in a broken link. But does that link already exist in the documentation?
• URLs are confusing for translators. Should they also change the URL when translating? What should the new URL be then? And if you receive the translated files, you have to make sure that every URL in every translated file or section is correct.

Needless to say, URLs are a nightmare to maintain, and there is no ideal solution.

Setup for URLS

I decided to use reference links in the markdown, e.g. [Go home][1]. At the bottom of every markdown file, I include a file containing all the keys, e.g. --8<-- "../../includes/urls-en.md". See Snippets for more information on this feature.

For English, the URLs file looks like this:

[1]: /en/
[2]: /en/contact-yesplan/

And for Dutch, the URLs file may look like this:

[1]: /nl/
[2]: /nl/contact-met-yesplan/

• Advantages

  • Every language has its own file.
  • Only one place to maintain all URLs for each language.
  • In the markdown, the URLs are replaced by keys that are the same across all languages.
  • Translators don't have to translate URLs, leading to fewer errors.
  • This is part of the solution for shared content with different links (see above).

• Disadvantages

  • When maintaining the documentation, you don't see what hyperlinks refer to. You always have to go to the URLs file.
  • You have to use absolute links, bypassing the tests MkDocs executes when building the documentation.

Testing the URL Files

I wrote a Perl script to run some tests and create a markdown file containing all the links. I'm not a programmer, so I think that anyone with basic programming skills can do this. I'm not sharing the script here because it is very specific to our setup.

The file checks the following things for every language:

• Do the markdown files in the docs/ folder contain empty keys, e.g. [Some link][]?
• Do the markdown files in the docs/ folder contain "orphan" keys that are not in the URLs files?
• Do the URL files contain any "childless" keys that are not in the markdown files?
• Does a URL file contain duplicate keys?
• Does a URL file contain duplicate URLs?

There is also one test across languages:

• Is there a difference in key frequency between languages? For instance, if the key [1] appears three times for English, but only once for Dutch, there may be a problem with the translation.

Testing the URLs

Once all this is checked, the script creates a markdown file for each language in the docs/ folder.

For English, the file docs/en/test-links.md may look like this:

# Check Links EN

- [1][1]
- [2][2]

--8<-- "../../includes/urls-en.md"

When the documentation has been built in Docker or on our development server, I browse to that page and run a link checker:

• Since the file contains all the site's links for that language, I check all links with one push of the button.
• I use the Chrome extension Check My Links. It detects broken links (error 404), but also broken links to anchors inside pages (code 200 but still a warning).
• Since the text for the hyperlink contains the key, I immediately know which one to check.

These test files are excluded from the build for the production server.

[squidfunk]

Wow, this is just amazing! Thanks for sharing! I'll see how I can integrate parts of your suggestions into the docs!

[Andre601]

Or just add a note in a comment of that code block like
# <your-site> is the URL you use for your site

[koen-yesplan]

Or simply use /en/, /fr/ and /nl/ for this recipe?

• Using an explicit URL won't work for an installation in a local Docker environment or on a staging server
• You will want to test the language selector at some point before it's on the production server

[squidfunk]

We can change the example to relative links, if everything works as expected. PR welcome!

[Andre601]

How does it look like when I use site_url? Do I add the language at the end (https://example.com/en)?

[koen-yesplan]

It depends on your setup, I guess.

• If you have a separate (sub)domain for the documentation, you can simply add the language at the end: https://www.mymanual.net/en/ or https://manual.example.com/en/
• However, if you place documentation at some deeper level of your corporate website, this will have to be reflected in your url, e.g. https://example.com/manual/en/ or https://example.com/en/manual/. I have no experience at all with handling documentation this way and it doesn't seem straightforward.

@squidfunk I wouldn't use relative links in the manual, since they assume that there are different folders for the languages at the root of the site. I don't know whether this will be the case for everyone, so we better use a general example like you did. However, I have changed the examples above to relative links.

[ChrisBlankDe]

great concept and thanks for sharing!
I've set it up similarly for myself.
what i don't quite understand here is where language independent images would be stored which should be included in the markdown files.

[koen-yesplan]

Thank you.

Almost all of our images are language-dependent and are stored in the /docs/nl/, /docs/en/or /docs/fr/ folder, so we don't really have that issue.

But I just tried it out locally, and I can display our logo on a markdown page using

• ![](/assets/images/logo.svg) (absolute URL)
• ![](assets/images/logo.svg) (relative URL, from the index page)

So my answer would be: store it in the /overrides/assets/images/ folder and use the URL structure I just mentioned. But we don't use it on our production server, so maybe you should test it some more...

[ChrisBlankDe]

i didn't have the idea to store this in overrides/assets/images/. actually i'm a proponent of separating design (template) and content from each other. but this just works too well. :)
thank you.

[squidfunk]

I, personally, find this idea absolutely amazing and conceptually clean, so again, thanks @koen-yesplan for sharing it!

• Assets that are independent of language are template assets and stored in overrides
• Assets that are language-dependent are content assets and stored in <lang>/docs

[EveryDayRains]

Hm,I have some problems, else go to / then there will be a 404 error. How to fix this? Make another sample documentation for /. Or what?

[ChrisBlankDe]

I've created a simple index site which redirect to the default language.

<html>
<head>
	<title>Redirect</title>
	<meta http-equiv="refresh" content="0; url=/en/" />
	<style>
		.centralizedContainer {height: 100%;width: 100%;display: flex;position: fixed;align-items: center;justify-content: center;font-size: 200%;}
	</style>
</head>
<body>
	<div class="centralizedContainer">
		<div><a href="/en/">Redirect</a> to landing page.</div>
	</div>
</body>
</html>

[EveryDayRains]

thx

[avently]

After following the help post here I spent some hours but couldn't fix some issues (almost everything was working good). But after that I found this lib: https://github.com/ultrabug/mkdocs-static-i18n
It fixes aaaaaaalllllll issues I had. Works brilliant. Hope other users will notice it.

[samzong]

Hi @avently thanks for it. https://github.com/ultrabug/mkdocs-static-i18n is a good lib for it, but it seems that can not work with monorepo

Hopefully others will see this message.

[niccokunzmann]

I have a look at the catalog of translation plugins. I chose mkdocs-mdpo because that works ok with Weblate at the moment.

[EveryDayRains]

How can I make the announcement black visible only on the English version?
It is displayed everywhere, but on the English version it still comes out

[koen-yesplan]

Did you find a solution for this?

I'm by no means an expert, but on my installation, the conditional statement is inside the announce block.

{% block announce %}
{% if config.theme.language == 'en' %}
test
{% endif %}
{% endblock %}

However, this means that the announcement appears in every language, even if there is no text, which is not a solution for your case.

[botkero]

Thanks for this help, but there are some things that are not clear to me here.
What exactly do you put in ../../? If I copy your template, then I get an error first.
ERROR - Config value: site_url. Error: The URL isn't valid, it should include the http:// (schema)

One small disadvantage is that you cannot use the mkdocs serve command to serve your site locally with all three languages. MkDocs can > only serve one language at the time.

I don't quite understand it either. Why can't I test this locally? And why would it work if I push it to gitlab/github?
I have the feeling that the setup guide is missing some essential elements. Or I am just too stupid.

[koen-yesplan]

What exactly do you put in ../../? If I copy your template, then I get an error first.

I can only produce that error if I add site_url: / to my configuration file, so my first question would be: does your mkdocs.yml file contain that setting?

Why can't I test this locally?

Because the mkdocs serve command expects one mkdocs file. The sample setup above contains three such files (one for each language), so you can't serve them all at the same time. You can serve French, Dutch and English separately locally, but not at the same time. In other words, you can test the three languages separately, but you won't see the full site where you can navigate from one language to another.

And why would it work if I push it to gitlab/github?

We put the generated HTML files on a web server using Docker (and build it locally to test), so I can't help you there, sorry.
I assume that GitHub Pages requires one mkdocs file? If that is the case, you may want to take a look at https://github.com/ultrabug/mkdocs-static-i18n, as suggested above

[botkero]

Thank you for such a quick reply. I did not expect that.

This my yml file:

site_name: 'manual'
docs_dir: '../../docs/en/'
site_url: '../../generated/en'

theme:
  name: material
  logo: ../../favicon.ico
  favicon: ../../favicon.ico
  language: en
  
  features:
    # - navigation.expand
    - navigation.indexes
    - navigation.sections
    - navigation.tabs
    - navigation.top
    # - navigation.instant
    - navigation.tracking
  palette: 
    # Palette toggle for light mode
    - scheme: default
      toggle:
        icon: material/brightness-3 
        name: Switch to dark mode

    # Palette toggle for dark mode
    - scheme: slate
      toggle:
        icon: material/brightness-7
        name: Switch to light mode

# mermaid support
markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

plugins:
  - search:
      lang: en
  - git-revision-date-localized

extra:
  alternate:
    - name: English
      link: /en/
      lang: en
    - name: Deutsch
      link: /de/
      lang: de

nav:
 - Welcome: index.md

But probably, as you suggedsted, I will look into other approaches.
Thanks anyway!

[z3thon]

I am trying to set up my website using GitHub pages and I've followed this guide to get the languages working.
What I can't figure out is after I re-do my entire file tree and re-build the site files inside of the generated folder when I try to compile my site it says I have to have a yml file in my base file tree.

So I can't figure out how to make the site load by following the information that was submitted here.

How do you get around the site needing the yml file to be in the most top level folder and instead have it direct to the yml files that are inside of the config folder?

Also, after setting everything up, even if I manually navigate to my /en/ folder (https://lztek-io.github.io/SightlineDocs/en/) the whole site just falls apart.
Is this possible to do while hosting via GitHub pages?

https://lztek-io.github.io/SightlineDocs

Thanks!

[z3thon]

I think I understand what's going on now.

You are using the mkdocs engine to build the site files and content but once it is built you are taking those files and folders and pasting them into a static apache server.

I am using a server platform where each time someone visits the site the server "boots up" and serves the most updated version of all the site files to the end user.

You are building the site files after you create everything and then you are using those site files to be used as a basic html webpage?

Because once the site is built. The html files can run on a standard webserver like apache. Correct?

[z3thon]

Everything makes so much more sense.

[koen-yesplan]

You are using the mkdocs engine to build the site files and content but once it is built you are taking those files and folders and pasting them into a static apache server.

Yes, indeed. We use scripts to automate all of it, but that's the gist of it, yes.

Everything makes so much more sense.

I'm glad that we go this cleared up. 😅

[z3thon]

This also explains why people can't "test it live" because if you're running an engine on it in real time and the engine is recompiling the site as you build it to show you the outcome this is impossible when you use the build -f method.

The site engine will auto-correct and re-build the site files as you make your site if it's all based on the root mkdocs.yml

Because this is 3 dynamic sites being compiled each time you change the site data and markdown files you have to re-build the site again for each language.

Hmmmm. As much as I like the file and folder layout that you have created much more than the i18n alternative I am seeing why people are drawn to the i18n plugin.

They can live test their website as they build it in a compiler that's rebuilding the site files as you make changes and update the markdown docs.

[koen-yesplan]

As I said above, it all depends on what you need and on your workflow.

• I still use mkdocs serve -f config/nl/mkdocs.yml when I write and when I'm tinkering with layout. So I use "dynamic compiling" daily on my local machine.
• Documentation only ends up on our internal server using Pull Requests and a thorough review.
• Then it is all translated by an external agency.
• To really test the complete site with all languages, I run Docker locally.
• If it all looks good and the test are ok, I push and check it on the internal server again.
• And only then is it pushed to a production server.

In that scenario, there is hardly any need for dynamic compiling: only in the first step, and only when I'm writing my documentation in the source language. I truly really understand that people have other needs, but then https://github.com/ultrabug/mkdocs-static-i18n is a viable alternative, and it also seems to support folder-based doc structures.

[ajh123]

Currently

Simple

If this documentation does not contain URLs to other language-specific files (e.g. /en/what-is-an-event.md), you can simply use Snippets.

For instance, in the docs/en/, docs/fr/ and docs/nl/ folder, you can add a file developers.md with the following contents:

--8<-- "../../includes/developers/api.md"

This will include the one file in all three languages. You only have to maintain the file includes/developers/api.md and it will appear correctly in all languages. Note that the path you use for the snippet is relative to the mkdocs config file.

What I want to do.
Let's say I have a folder called developers inside docs/en/, docs/fr/ and docs/nl/ how could I include the entire ../../includes/developers/ folder without having to create each file for each language and include it, like above.

My real situation:
I have a Community folder which I would like to include inside each language's docs without having to do the above solution for each file. Currently the number of files inside the Community is small, so it is manageable doing the Simple method, however the number of files will grow and creating a linking subfile per language would be an unmanageable task.

Would a symlink work? But would it work with git?

[tibitoth]

Very interesting but can we reuse config sections between language specific mkdocs.yml files?

[squidfunk]

Yes, by using configuration inheritance.

[tibitoth]

I want to add some helpful insights into this topic because I recently went through this multi language setup in this repository: https://github.com/bmeviauac01/datadriven

1. Place the mkdocs.yml config files into the repository's root folder instead of a config folder so relative paths works better.

2. Distinguish language configs in file names eg.: mkdocs.hu.yml, mkdocs.en.yml

3. Docker run command should specify config file parameter but in this case you should specify also the default CMD as well:

   docker run -it --rm -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material:9.0.12 serve --dev-addr=0.0.0.0:8000 --config-file=mkdocs.en.yml

   To create a default docker experience you should create a new dockerfile where you override the entrypont and define a default config file parameter. In this case you only need to specify the config file parameter to change debug language.

   FROM squidfunk/mkdocs-material:9.0.12
   
   EXPOSE 8000
   
   ENTRYPOINT ["mkdocs", "serve", "--dev-addr=0.0.0.0:8000" ]
   
   CMD ["--config-file=mkdocs.en.yml"]

   usage for overridden language

   docker build -t mkdocs .
   docker run -it --rm -p 8000:8000 -v ${PWD}:/docs mkdocs --config-file=mkdocs.hu.yml    

   usage for default language

   docker build -t mkdocs .
   docker run -it --rm -p 8000:8000 -v ${PWD}:/docs mkdocs

   note: docker build is only needed if the dockerfile has been changed

4. Use config inheritance and place common config into mkdocs.common.yml

5. Plugin configs should be in key-value syntax because array syntax cannot be overridden

6. Empty config's syntax should be a new object: search: { }

7. edit_url should be defined language specific: edit_uri: 'blob/master/docs/en' becuase docs_dir is not used in this feature

8. When hosting both languages in the same domain as subsite site_url should be defined: site_url: https://bmeviauac01.github.io/datadriven/hu/

9. extra.alternate.links should be absolute urls if site_url has been defined

10. If you want to share assets between languages you should place these assets into and overrides folder (like in the example) but relative links in the md files work only if the overrides folder follows the docs/[lang] folder's structure. So treat docs/[lang] and overrides folders as merges folders. Relative link should be used because of the overridden site_url

    ├─ docs/
    │    ├─ en/
    │    │   ├─ folder1
    │    │   │   └─ file1.md # use 'images/share-image1.png' relative url
    │    │   └─ folder2
    │    │        └─ file2.md # use 'images/share-image2.png' relative url
    │    ├─ hu/
    │    │   ├─ folder1
    │    │   │     └─ file1.md # use 'image/share-image1.png' relative url
    │    │   └─ folder2
    │    │           └─ file2.md # use 'image/share-image2.png' relative url
    │
    └─ overrides/
         ├─ folder1/
         │   └─ images/
         │        └─ shared-image1.png
         └─ folder2/
              └─ images/
                   └─ shared-image2.png
    

[christophhillisch]

I've tried your configuration, but I'm having a problem: when I launch the English or Hungarian version, I get a 404 message when I switch from one language to the other. I put my code in a public GitHub repository, maybe you are able to help.

Updating link in the common.yml to something like http://localhost:8000/en/ did not help

docker build -t mkdocs .
docker run -it --rm -p 8000:8000 -v .:/docs mkdocs

Any help is appreciated!

[uPagge]

I thought the support had to be deeper, too. But I really don't think it's necessary. That is, I was able to add support anyway, so I generate several sites and put them in the same folder with prefixes

cd documentation/de
mike deploy --prefix documentation/de --branch docs-deploy --push --update-aliases latest
cd ../en
mike deploy --prefix documentation/en --branch docs-deploy --push --update-aliases latest

and then nginx handles everything.

So this plugin only adds the switch and nginx does the rest. I think this is optimal not to complicate the logic of this project, because not everyone needs it.

The only thing that upsets me is the fact that the switch translates to the root page and does not show the same page where the user was, but in a different language.

[squidfunk]

The only thing that upsets me is the fact that the switch translates to the root page and does not show the same page where the user was, but in a different language.

Already on the roadmap: #4835

[kamilkrzyskow]

Hey @uPagge, I see that you're using mike, so I'm assuming you did figure out a way to properly join multi-language support with versioning. Could you share your workflow/setup and explain how to assure proper routing when switching versions in another discussion? #5364

[berkantsahn]

Hi everyone,
I would like to help people who have problems with the subject.
i did multi language operation without using docker etc.. I created more than one yml file in the main directory so that the pages are created accordingly and multi-language support is provided. I publish the project on github and it works without any problems. Friends who have problems can review the project I created on my github:
https://github.com/berkantsahn/mkdocs-sample

[berkantsahn]

@mendax1234
This Dockerfile is used to create a Docker image, which provides an environment for a specific version of MkDocs called "mkdocs-material" along with some additional features. Let's break down the different parts:

FROM squidfunk/mkdocs-material:9.0.9: This line specifies the base image from which the current Docker image is derived. In this case, it uses the "squidfunk/mkdocs-material" image with version "9.0.9."

RUN apk add --no-cache --virtual .build-deps gcc libc-dev libxslt-dev: This line installs necessary packages in an Alpine Linux-based environment. The installations are performed within a temporary virtual package group.

apk add --no-cache libxslt: This line adds the "libxslt" package to the Alpine Linux-based environment.

pip install --no-cache-dir lxml>=3.5.0: This line installs the "lxml" Python library, specifying a minimum version of 3.5.0.

apk del .build-deps: This line removes the temporary package group (gcc, libc-dev, libxslt-dev) that was installed earlier, cleaning up unnecessary files and reducing the image size.

pip install --no-cache-dir: This line is used to install various MkDocs plugins. The plugins installed are as follows:

mkdocs-git-revision-date-localized-plugin: A plugin that displays the localized revision date of the MkDocs documentation.
git+https://github.com/tibitoth/mkdocs-git-committers-plugin-2.git@master: A plugin used to list contributors in the MkDocs documentation. This one is fetched from a specific GitHub repository.
mkdocs-glightbox: A plugin that provides lightboxes for visual content in MkDocs documentation.
git config --global --add safe.directory /github/workspace: This line adds a secure directory to the Git configuration. The "/github/workspace" directory is typically used by ongoing integration processes like GitHub Actions.

EXPOSE 8000: This line notifies Docker that the container will listen on port 8000. However, it's important to note that this is just a declaration; Docker doesn't automatically create a network connection for it.

ENTRYPOINT ["mkdocs", "serve", "--dev-addr=0.0.0.0:8000"]: This line specifies the default command that will be executed when the Docker container starts. In this case, it runs MkDocs in serve mode, making the documentation available via a local server, and binds it to the address 0.0.0.0:8000 to allow connections from any IP.

CMD ["--config-file=mkdocs.tr.yml"]: This line specifies additional command-line arguments that are automatically executed when the Docker container runs. Here, it uses a custom configuration file named "mkdocs.tr.yml." This file likely contains the Turkish version of the documentation.

[mendax1234]

@berkantsahn Thanks for your detailed reply! How can l manage the plugins that the pip install --no-cache-dir:` will install?

[berkantsahn]

@mendax1234

I am not sure that i understand truly but i'm gonna try to explain with examples:

In the provided Dockerfile, it appears that we are building an image based on the squidfunk/mkdocs-material image and installing several plugins using the pip install --no-cache-dir command. The --no-cache-dir flag ensures that pip does not use the cache when installing the packages, which can be useful for Docker images to reduce the image size.

To manage the plugins that are installed, you can simply comment or uncomment the corresponding lines in the Dockerfile. For example, if you want to install the mkdocs-git-committers-plugin-2, you can uncomment the line:
# mkdocs-git-committers-plugin-2 \

By removing the '#' at the beginning of the line:
mkdocs-git-committers-plugin-2 \

If you want to skip installing this plugin, you can add the '#' back to comment out the line.

Here's the modified Dockerfile with the mkdocs-git-committers-plugin-2 uncommented:
FROM squidfunk/mkdocs-material:9.0.9

# required for mkdocs-git-committers-plugin-2
RUN apk add --no-cache --virtual .build-deps gcc libc-dev libxslt-dev && \
apk add --no-cache libxslt && \
pip install --no-cache-dir lxml>=3.5.0 && \
apk del .build-deps

RUN pip install --no-cache-dir \
mkdocs-git-revision-date-localized-plugin \
mkdocs-git-committers-plugin-2 \
# hotfix for authors because file move resets contributors list
git+https://github.com/tibitoth/mkdocs-git-committers-plugin-2.git@master \
mkdocs-glightbox

RUN git config --global --add safe.directory /github/workspace

EXPOSE 8000

ENTRYPOINT ["mkdocs", "serve", "--dev-addr=0.0.0.0:8000" ]

CMD ["--config-file=mkdocs.tr.yml"]

now, the mkdocs-git-committers-plugin-2 will be installed when you build the Docker image using this modified Dockerfile. If you want to manage other plugins, you can use the same approach of commenting or uncommenting the corresponding lines as needed. After making the desired changes, you can build the Docker image using the docker build command.

So you can manage your dockerfile like this. I hope I could help

[mendax1234]

@berkantsahn Got it! Thanks for you detailed explanation!

[berkantsahn]

@mendax1234 You're welcome I'm glad I could be of assistance. Have a nice day.

[Realvincentyuan]

can anybody please shed more lights on the correct and easy setup as of May 2023, in fact the things are really hard to follow without instructions.

Thank you!

[tibitoth]

I've followed the original post with the following modifications: #2346 (comment)

[berkantsahn]

actually there is a sample system i made for multi language.
You can check my repo and fork it: https://github.com/berkantsahn/mkdocs-sample

[squidfunk]

Insiders 4.38.0 ships a new plugin called projects! The plugin provides a consolidated build and serve mode for MkDocs, builds projects concurrently, and should help in creating multi-language installations. We're super interested in hearing your feedback to add the missing parts to enable dead-simple building of multi-language or other multi-project installations.

The reason why we built the plugin was our examples repository which we will now start to fill with downloadable examples, which is a project with nested projects by its very design. However, the plugin is also perfectly suited to allow for multi-language builds.

As always, happy for any feedback, good or bad!

[squidfunk]

Please try building the official Insiders image. Just check out the repo, the Dockerfile is in the root of the repository.

git clone https://github.com/squidfunk/mkdocs-material-insiders.git
cd mkdocs-material-insiders
docker build -t mkdocs-material .

[velduz]

I did:

▶ docker images           
REPOSITORY          TAG       IMAGE ID       CREATED         SIZE
mkdocs-material     latest    1adfd47ee4d9   8 minutes ago   183MB
papasmurf.website   latest    13a204062d65   14 hours ago    1.14GB

now changing to my project directory:

▶ cd ~/dev/papasmurf.website 

▶ cat mkdocs.yml 
site_name: my personal website

plugins:
  - projects

▶ tree projects 
projects
├── en
│   ├── docs
│   │   └── about.md
│   └── mkdocs.yml
├── eo
│   ├── docs
│   │   └── about.md
│   └── mkdocs.yml
└── nl
    ├── docs
    │   └── about.md
    └── mkdocs.yml

6 directories, 6 files

▶ docker run -p 8000:8000 -v ./:/docs mkdocs-material 
ERROR   -  Config value 'plugins': The "projects" plugin is not installed

Aborted with 1 configuration errors!

Am I still misunderstanding something?

[squidfunk]

Yes. Either:

site_name: my personal website

plugins:
  - material/projects

Or:

site_name: my personal website
theme:
  name: material

plugins:
  - projects

The projects plugin is bundled with the theme, so you either need to fully qualify the plugin, or specify the theme setting. Please note that all of our documentation assumes that you're using our theme.

[velduz]

The theme is the reason I'm here 😛. Thanks, this solved the issue.

This setup assumes a kind of 'master page' with links to the projects. In fact, a multi-language site is essentially a collection of parallel websites on the same level without a parent website.

Anyway, I can now continue exploring how to integrate this projects plugin with the multi-language setup discussed here.

[squidfunk]

You can use the redirect.html template on the top-level. Just create docs/index.md with:

template: redirect.html
location: /en/

[velduz]

I am looking for an example where somebody has a multi-language site that also has a multi-language blog. I am struggling to get that done.
I already have it built with Hugo, but I prefer mkdocs.

I am tempted to forget about the blog plugin feature, and just add the blog posts as normal pages and add them to the navigation. Without tags and categories and all... Then I can easily use one of the existing i18n implementations.

[squidfunk]

Hopefully, the issues I had will vanish like snow in the sun.

Bear in mind that this is all pretty experimental right now, but with more user feedback we can gravitate faster towards a stable solution. Also, you did not really specify in your OP what problems you were having, so I have no idea whether the latest changes can help you or not. If not, please specify precisely what does not work, so we can fix it 🚀

[velduz]

Yep, I'll do.
I used your multi-language-blog.zip as a starting point. That works, so I am now busy adapting it to my needs. One thing I noticed: when I changed the German directory to Dutch, the website only started up correctly after refreshing the .cache directory: sudo rm -rf .cache. Maybe it's enough to mention it in the documentation, rather than trying to fix it. Renaming projects will not occur that often.

[squidfunk]

You're right, there still seem to be some issues with the cache. I've reopened #6306 for that matter. In the meantime:

plugins:
  - projects:
      cache: false

[velduz]

I like the approach of the alternate header in the blog.
Default behavior should be to use the same slug for the blog posts in each language, unless someone wants to translate the slugs as well. But this comes with the time investment to write all mappings as 'alternate' in the blog post headers.

By the way, wouldn't it be good to have a default or fallback language? In my current website I have three languages, but some content is only available in English.

[squidfunk]

But this comes with the time investment to write all mappings as 'alternate' in the blog post headers.

By the way, wouldn't it be good to have a default or fallback language? In my current website I have three languages, but some content is only available in English.

That's exactly the functionality we're going to add to the projects plugin ☺️ It's currently very generic, but we'll add additional support for certain modes, e.g., to easily build multilingual sites, as we already said in #5800 (comment) (Modes)

[mateus2k2]

Hi, can anybody help me? I am trying to make a dual language blog, but I am not a contributor, so I tried to do things manually, following the instructions on the first post in this discussion

I created two .yml files, build them and use a web server to serve them. But when I access the build on the web server there is a bunch o things that does not work, like my blog post, custom html.

This is what I have done:
mkdocs-dual.zip

[mateus2k2]

Hi, thanks for the response. What I meant about not being a contributor was the projects plugin which I think would make things easier, but I don't have access to it.

What I did was use this example as a basis https://github.com/berkantsahn/mkdocs-sample and created mine https://github.com/mateus2k2/blog/

The only thing that I don't like is that I don't know how to run it locally, and the css won't be found no matter what I do. Any ideas how to solve this? Thanks again.

[kamilkrzyskow]

What I meant about not being a contributor was the projects plugin which I think would make things easier, but I don't have access to it.

Oh you meant not an Insiders sponsor, contributor is in part a GitHub term for people that added content to the repo.

The only thing that I don't like is that I don't know how to run it locally, and the css won't be found no matter what I do. Any ideas how to solve this?

You should set a site_url like https://example.com/en/ to properly set the "base" with the prefix, then the extra css should be only the assets/stylesheets/extra.css. Without the overrides part or any other part prefixed.

You can check the browser dev console to see what is being loaded, and how, and when 👌

[mateus2k2]

I see, so in my case I had to put the assets in each docs folder for each language. Like: docs/en and docs/pt. Is there a way to put it outside so I don't have to duplicate it?

[kamilkrzyskow]

Keep the files in overrides/assets/..., but don't add overrides to the path in extra.
The site_url is necessary so that the relative path is aware of the prefix.

[mateus2k2]

It works now. Thanks

[thdhondt]

Hi, I have been trying to make this approach work with an offline build. However, I could not get the links in the alternate URL to work:

• If I use a relative URL such as en/, it appends its value to the URL of the current page.
• If I use an absolute URL such as /en/, it redirects to a location C://en/ instead of the root of the page.

Is there something I missed or is this not supposed to work?

Thanks in advance for your help!

[squidfunk]

Good point, I don't think this currently works. Absolute URLs will definitely not work, as you noted, so URLs must be relative, but URLs in the language selector are not computed and resolved for each site – only top-level and then changed via JavaScript. You might be luckier by using a dedicated multi-language plugin like the static-i18n plugin, while we're rearchitecting how multi-project builds are supported.

CC @alexvoss for visibility

[thdhondt]

Thanks for the answer! I managed to get it to work using ../en/index.html in offline mode. I'm still in the process of figuring out how reliably it works though...

[squidfunk]

It will work from the first level of your docs, but likely not from deeper levels.