Multi Language Support

[gaborvecsei]

It would be great if we could manage multiple languages for our documentation

There should be a sticky language "switcher" button on the header.
And we could write the pages under docs/<language>/...

Btw, thanks for this beautiful site! I just love it and I am planning on using for my projects

[syngo-ibm]

Hello @pmarsceill ,

I use just-the-docs for documentation.
I'm looking forward to search in Japanese in the next major release.
(I read #222, and I have found that the lunr search engine supports searches in 14 languages , including Japanese.)

Let me ask you a question.
When are you planning next major release?

[dominique-mueller]

Using https://github.com/untra/polyglot, I was able to at least internationalize the site content. But the theme for sure needs i18n baked in, cause things like the title or the footer content or even the search is either impossible or very difficult to internationalize.

[ChaiNikhilShinde]

@pmarsceill Can you please let us know when is "Next release that will include multi-lingual support" planned?

[mattxwang]

Since this is one of the most-requested features, I'm going to pin this at the top of our issues page.

When are you planning next major release?

For context: a couple of maintainers have been partially onboarded recently, and I am currently doing the bulk of the triaging work; between myself and @pdmosses, we are split on implementing new features. As such, if anybody is willing to take point on this issue, that would be much appreciated. I agree that internationalization will require a huge undertaking and likely some significant refactoring.

Also going to place requests for internationalized search in this issue for now. Happy to create a separate (fresh) issue, but it seems like it is a related (if not completely synonymous) topic.

[aschrijver]

FYI In #128 there's also mention of using the Multiple Languages Jekyll plugin.

[zkvvoob]

Hello all.

I had to scratch my head a bit today in order to figure out how make the nav menus change based on the selected language (using the above-mentioned Multiple Languages Plugin). If you're interested, I've outlined my path and the solution I came to in this discussion.

[linhandev]

I'd like to share a workaround I've tested that works.

To have a multi language doc site, I built two just the doc sites separately and assigned each with a subpath. For example in the two _config.yml

EN site:

baseurl: "/project_name/EN/"

Other language site:

baseurl: "/project_name/other_language/"

And at the top of the markdown files insert

English | [Other language](/doc/other_language/)

With a py script to change some paths before building the site with jekyll, this language switching can work both when viewing the docs on github and in the built just the doc site. Because these are just two sites, I can use different image or video assets demoing the project with different frontend languages.

The build action I used is here (it's a bit complicated because I'm putting the doc folder inside the project instead of a separate repo, but essentially just jekyll build repeated twice), doc markdown in github repo is under this folder

[CanadianBeaver]

What about supporting the projects which uses suffix/prefix in file's name for separate language specific pages?

What I mean:
+- Documentation
|- index.md
|- index.ru.md
|-page-what-describe-something.md
|-page-what-describe-something.ru.md

[Aharito]

Hello! Thank you for the wonderful Jekyll theme.

But, unfortunately, search in non-Latin languages does not work.
How are things with this search now?

[mattxwang]

Hi @Aharito, thanks for the comment. As of now, no progress has been made - both with broad multi-language support and the narrow case for search. For the latter, we are relying on lunr.js, which hasn't been updated in about 3 years. However, my understanding is that the lunr-languages project might support your use-case; I haven't used it specifically with JtD, so would be curious to see what your experience is!

[Aharito]

Everything turned out to be very simple.

I chose the simplest method to install the theme in my repo - through “Use this template”. That is, I did all the actions directly on this GitHub repo, without creating a local copy.

To connect the necessary lunr languages, I didn’t bother and also chose the simplest method. Namely:

I created an /assets/js/ folder in my repo and uploaded a copy of the just-the-docs.js file from your original repo, in which I added the line this.use(lunr.multiLanguage('en', 'ru') ); after the line var index = lunr(function(){.

I created a subfolder /assets/js/vendor/ in my repo and uploaded the files I needed into it:

lunr.min.js
lunr.multi.min.js
lunr.stemmer.support.min.js
lunr.ru.min.js

Next, I created the /_includes/ folder and in this folder I created the head_custom.html file, in which I called the scripts I needed.

{% if site.search_enabled != false %}
   <script type="text/javascript" src="{{ '/assets/js/vendor/lunr.min.js' | absolute_url }}"></script>
   <script type="text/javascript" src="{{ '/assets/js/vendor/lunr.multi.min.js' | absolute_url }}"></script>
   <script type="text/javascript" src="{{ '/assets/js/vendor/lunr.stemmer.support.min.js' | absolute_url }}"></script>
   <script type="text/javascript" src="{{ '/assets/js/vendor/lunr.ru.min.js' | absolute_url }}"></script>
{% endif %}

Then I added my .md document files to the /docs/ folder, and everything works great.

P.S. If someone needs another language, instead of the lunr.ru.min.js file, they need to use a file for another language from the lunr-languages set.

[Aharito]

Hi @mattxwang

By the same method as above, it is easy to move the inclusion of multi-language search to __config.yml, for example by entering the search_languages parameter there.

If search_languages is an list, then include corresponding lines and files to theme.

[mattxwang]

I'm glad it worked well @Aharito, and I appreciate you enumerating these steps. If you're willing, it'd be great if you could document this upstream (so others can learn how to do it too). I'm happy to work with you (reviewing the PR, etc.) to get this done.