Translations nav

[victorbnl]

Contribution guidelines

• I've read the contribution guidelines and wholeheartedly agree

I want to suggest an idea and checked that ...

• ... to my best knowledge, my idea wouldn't break something for other users
• ... the documentation does not mention anything about my idea
• ... there are no open or closed issues that are related to my idea

Description

I chose the feature template as it didn't seem to fit the bug one, but it's a problem I'm describing. So the thing is that I have a multilingual site, and the language selector. But when I'm on a french page I still have the general nav so I can't go on the french pages other than home (on which I can go by the language selector). It would be cool to have nav list the french pages in this case.

Use Cases

I think it's already clear

Screenshots / Mockups

(There are french mistakes, I did it fast)

[victorbnl]

Also temporarily, or if you don't want to implement it, are there workarounds to achieve this?

[squidfunk]

Thanks for suggesting. However, I'm afraid I don't really understand the problem 😅 The language selector, in its essence, is only a list of links the author can freely define. There are several ways to achieve multi-language sites for MkDocs, so there's no one-size-fits-all solution. For this reason, the language selector is currently rather dumb. Two thoughts:

1. I recommend reading the guide on setting up multi-language sites on the discussion board. It gives really guide guidance how to build multi-language sites and how to handle things like shared and language-specific assets.
2. We currently don't have the functionality to "stay on page when switching languages", so when you are on the English version of "Changelog" and switch to French, one might expect it directly goes to "Historique". It will currently just default to the top-level page. This functionality is on the roadmap for Insiders, so it will be added at some point in the future. The version selector already supports this functionality - it will stay on page when switching versions, given that the page exists. The language selector functionality will be somehow similar.

[victorbnl]

The problem: if you go on the french page and then click and element of the nav, you go back to the english site because the nav doesn't change depending on languages

Some solutions:

1. Being able to define multiple navs, to have one per language
2. Having the links fixed automatically so if I define an element of the nav like - Install: installation.md, on the french site the name would still be title but would take me to fr/index.md

[squidfunk]

Thanks for getting back. Are you using one MkDocs instance per language? If not, that's what you need to do. Because with this setup, you can have one nav section in each mkdocs.yml per language. Please see the guide I linked in #2937 (comment). Other than that, we can't help you without having more details about your setup.

[victorbnl]

Are you using one MkDocs instance per language?

No, and that's not what I want to do. If I want to change the primary color of the site I shouldn't have to change this 4 times if my site have 4 languages

[squidfunk]

Okay, so this is not a problem with Material for MkDocs then. As I said in my first comment, the language selector is currently rather dumb. It will be improved to support better navigation between multiple MkDocs installations, as that's the canonical use case that Material for MkDocs supports. If you deviate from this, you can still extend the theme and add your own logic.

Also note that MkDocs supports configuration inheritance as of version 1.2, so you could simply define all commonalities like colors and feature flags in a shared mkdocs.yml.

[victorbnl]

Ooh configuration inheritance seems very cool, I think I'll use that then. Thanks!

[scmcca]

@victorbnl

The problem: if you go on the french page and then click and element of the nav, you go back to the english site because the nav doesn't change depending on languages

I was able to achieve this using mkdocs-awesome-pages-plugin and mkdocs-static-i18n.

My docs directory contains my markdown pages with their translations like this (english and french are configured using "languages:" in mkdocs.yml). Note the ".fr" extension for french versions of my page:

• index.md (default english)
• index.fr.md (french)
• page1.md
• page1.fr.md
• page2.md
• page2.fr.md
• Folder 1
  • page3.md
  • page3.fr.md
  • page4.md
  • page4.fr.md

Then using awesome pages, define a .pages file for nav ordering:

• index.md (default english)
• index.fr.md (french)
• page1.md
• page1.fr.md
• page2.md
• page2.fr.md
• .pages
• Folder 1
  • page3.md
  • page3.fr.md
  • page4.md
  • page4.fr.md
  • .pages

Finally, I translated the name "Folder 1" to "Dossier 1". I did this in the main mkdocs.yml using nav_translations..

The result is a that when I switch the language to french, the nav brings me to the home page of the french version of my site and all nav material is translated and points to the proper files.

Sorry for the rough explanation, hope that helps!

[krahu]

Then using awesome pages, define a .pages file for nav ordering:

• index.md (default english)

• index.fr.md (french)

• page1.md

• page1.fr.md

• page2.md

• page2.fr.md

• .pages

• Folder 1

  • page3.md
  • page3.fr.md
  • page4.md
  • page4.fr.md
  • .pages

Finally, I translated the name "Folder 1" to "Dossier 1". I did this in the main mkdocs.yml using nav_translations..

Hello, using nav_transaltion for very large documentation is very problematic. But mkdocs-static-i18 supports Set Directory Title in .page file. Do you know how to make it work together with localization? I have tried to create file en.pages where I wrote different "title", but with no affect.