Setting up multi-language installations #2346
Replies: 17 comments 92 replies
-
Wow, this is just amazing! Thanks for sharing! I'll see how I can integrate parts of your suggestions into the docs! |
Beta Was this translation helpful? Give feedback.
-
great concept and thanks for sharing! |
Beta Was this translation helpful? Give feedback.
-
Hm,I have some problems, else go to |
Beta Was this translation helpful? Give feedback.
-
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 |
Beta Was this translation helpful? Give feedback.
-
How can I make the announcement black visible only on the English version? |
Beta Was this translation helpful? Give feedback.
-
Thanks for this help, but there are some things that are not clear to me here.
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? |
Beta Was this translation helpful? Give feedback.
-
I am trying to set up my website using GitHub pages and I've followed this guide to get the languages working. 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. https://lztek-io.github.io/SightlineDocs Thanks! |
Beta Was this translation helpful? Give feedback.
-
Currently
What I want to do. My real situation: Would a symlink work? But would it work with git? |
Beta Was this translation helpful? Give feedback.
-
Very interesting but can we reuse config sections between language specific mkdocs.yml files? |
Beta Was this translation helpful? Give feedback.
-
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
|
Beta Was this translation helpful? Give feedback.
-
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
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. |
Beta Was this translation helpful? Give feedback.
-
Hi everyone, |
Beta Was this translation helpful? Give feedback.
-
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! |
Beta Was this translation helpful? Give feedback.
-
Insiders 4.38.0 ships a new plugin called 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! |
Beta Was this translation helpful? Give feedback.
-
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 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. |
Beta Was this translation helpful? Give feedback.
-
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: |
Beta Was this translation helpful? Give feedback.
-
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:
Is there something I missed or is this not supposed to work? Thanks in advance for your help! |
Beta Was this translation helpful? Give feedback.
-
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:
docs/
foldergenerated/
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:
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:
docs/en/
,docs/fr/
anddocs/nl/
). Therefore, the logo, favicon and CSS are shared by all the languages and have been moved to theoverrides/assets/
folder. This configuration deviates from the main Material for MkDocs documentation.language
key is used for:lang
attribute in thehtml
tagdocs_dir
key. So in this case, useindex.md
and notdocs/en/index.md
.English
Dutch
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:
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:
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/
anddocs/nl/
folder, you can add a filedevelopers.md
with the following contents: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:But for Dutch, you include a different URL file:
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:
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:
And for Dutch, the URLs file may look like this:
Advantages
Disadvantages
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:
docs/
folder contain empty keys, e.g.[Some link][]
?docs/
folder contain "orphan" keys that are not in the URLs files?There is also one test across languages:
[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:When the documentation has been built in Docker or on our development server, I browse to that page and run a link checker:
These test files are excluded from the build for the production server.
Beta Was this translation helpful? Give feedback.
All reactions