How to search a single language translation

[maurelian]

Description

Our documentation site recently had a full translation of Korean submitted. This is obviously wonderful.

Unfortunately, the search functionality mixes the two languages, which reduces the usability for readers in either language. Adding more languages in this way would presumably make it worse.

Expected behavior

I would prefer if there was a site wide toggle for the active language. Does such an option exist?

Package versions

python==3.6
mkdocs==0.17.2
mkdocs-material==2.2.5

Project configuration

https://github.com/ConsenSys/smart-contract-best-practices/blob/master/mkdocs.yml

Thanks very much for this excellent project, and for your help in advance!

[squidfunk]

MkDocs doesn't support language toggling/branching, so Material cannot add this functionality either. To solve this, you would need to build two separate versions of your docs, one for each language configuring the correct search language in mkdocs.yml. By customizing the theme you could link to the other language inside the header or where you want, effectively switching between the two separate builds.

[maurelian]

Great explanation, thank you!

[rllola]

@squidfunk I have been following your recommendation and done it for ZeroNet documentation. The most tricky part was the lunr search_index.json file which was containing the text. Also for convenient I wanted to have the 2 languages folders in the docs (so we don't need to modify twice and forget).

Here what I have which I believe might be useful for people willing to do it in the future :
https://github.com/rllola/Documentation/tree/french

It has :

• The icon with dropdown button
• The nginx conf file which does the magic to get the proper search_index.json
• A python script to generate everything
• Dockerfile because why not
• Insctructions in README

Your feedback would be appreciated.

EDIT: the all is still really hacky but it does the job.

[squidfunk]

@rllola Thanks for sharing your setup! It will be beneficial for anyone wanting to achieve this until MkDocs adds support for multi-language builds (if ever).

EDIT: The ZeroNet documentation looks super awesome (I like the logo/color combination). Great to see that people use the customization options Material offers.

[maurelian]

@rllola Have you got a site up with both the french and english versions? I couldn't find one.

[rllola]

@maurelian Sure. https://zeronet.io/docs-dev/en/

I am not done with the french translation tho. I have been focusing on the multi-language support side of it.

Here the PR with a little bit more information : HelloZeroNet/Documentation#117

Let me know if you have questions or need help.

[squidfunk]

Hmm, thinking about it, maybe we could add something like this to Material by default. If somebody can come up with a good spec on how to integrate it in a way that is easily workable, I'm happy to help integrating it or pull it of my self. Here are some problems to tackle:

• How do we link different-language translations (URLs are different)?
• Do all translations/versions require the same structure?
• Would it be practical to do it with the metadata extension?
• How would it look on desktop? tablet? mobile?
• How is the file/project layout for such a multi-language documentation?

[rllola]

Also the tricky part is loading the proper search index for lunr. Because by default it is looking in /search/ folder but I generated one for each language and put it inside their respective language folder : /fr and /en. And I need to play with nginx rule to load the proper one which is really hacky.

I believe the others problems that you mentioned are solvable, except maybe the metadata extension (I am not sure what is it 😄 ). For mobile, it needs a little bit more coding but nothing too hardcore.

I would be happy to contribute and start on a PR...

EDIT: Also doing a PR so mkdocs can ignore files would be really neat.

[suricactus]

Would be interesting if someone found a better solution than building a seperate site and search index for each language and share it here.

[squidfunk]

There's the mkdocs-static-i18n plugin which allows for building a single site and index, as I understand. I'm not a user of it, since this comes with some other caveats, which is why we're following the approach to build multiple sites alongside each other and will add better support for this in the future with the new projects plugin, but it might be something to consider.

[alexvoss]

I think a separate search index is a good thing because the size of a single search index would blow up with each translation added.

The projects plugin feels like the right path to me. I have recently started helping @squidfunk develop more examples for Material for MkDocs functionality, which means I am a heavy user of this plugin. One thing I like about the approach taken with it is that it will facilitate more use cases. (I am looking to develop an example that produces a second, stripped-down version of a site -e.g., for including training material in Open edX).