Navigation: stay on page when switching languages

[KusakabeShi]

Contribution guidelines

• [X] I've read the contribution guidelines and wholeheartedly agree

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

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

Description

At this doc: https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language-selector

This config always redirect to the homepage of another language:

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

Assume I'm in the https://example.com/de/customization page, click the "English" Button will be redirect to https://example.com/en/

Is it possible to set it like this

extra:
  alternate:
    - name: English
      link: /en/{nav.item} 
      lang: en
    - name: Deutsch
      link: /de/{nav.item}
      lang: de

So that I'm in the https://example.com/de/customization page, click the "English" Button will be redirect to https://example.com/en/customization page ?

Use Cases

Switching languages without leaving the current page.

I'm in the https://example.com/de/customization page, click the "English" Button will redirect to https://example.com/en/customization instead of https://example.com/en/

Screenshots / Mockups

No response

[squidfunk]

Thanks for suggesting. I've had this idea a while ago, but never followed up on it. However, I definitely think it is useful, as it would also mirror behavior of versioning, which will try to stay on the same page, as long as there is one in the version that is switched to. We could implement similar behavior for the language selector, but this would mean that the path must stay the same between versions. If that is given, it should work. Also, both sites would need to be built with MkDocs.

[KusakabeShi]

By the way, is it possiable to use variable in the nav path like this?

nav:
  - Poema IX: {language}/index.md
  - Virtual IXP: {language}/Virtual-IXP.md
  - Members: {language}/members.md
  - Route Server: {language}/RS.md

In this example, the redirect target will follow the current language like en/Virtual-IXP.md or zh/Virtual-IXP.md

So that I can hendle multi language in one site.

[squidfunk]

So that I can hendle multi language in one site.

It may be possible through some third-party plugin, but not in Material for MkDocs itself.

[vedranmiletic]

This would be far more useful if it could be expanded with language_maps in spirit of redirect_maps, e.g.

plugins:
    - languages:
        language_maps:
            hr:
                'en/example.md': 'hr/primjer.md'
            de:
                'en/example.md': 'de/exempel.md'

[squidfunk]

Thanks! I already think I have a pretty good idea how this could look from an implementation side. There should be several possible ways to provide mappings, and this might be one of them.

[YQisme]

@squidfunk Has this feature been completed now?

[squidfunk]

Not yet, otherwise this issue would've been marked as resolved ☺️ We're working on other parts right now, but it's on the roadmap. We'll also release a public roadmap in the coming months, so it's clearer how things are prioritized.

[YQisme]

Not yet, otherwise this issue would've been marked as resolved ☺️ We're working on other parts right now, but it's on the roadmap. We'll also release a public roadmap in the coming months, so it's clearer how things are prioritized.

Got it, thank you.

[janvanveldhuizen]

I'd like to add the request to preserve the language selection when a user returns to the web site.

[squidfunk]

I'd like to add the request to preserve the language selection when a user returns to the web site.

I think we should create a separate feature request for that, as albeit related, it's an entirely different problem. Could I ask you to create one with a minimal reproduction and the expected behavior you'd like to see? The mechanics are very important here, i.e., when to navigate the user to this previously version and when not to. We should discuss this first.

[squidfunk]

7d8a310 in Insiders adds experimental support for staying on the same page when switching languages. As with versions, it's currently necessary that the page that is part of the other language build has the same URL as in the site you're switching from. If not, you're taken to the root. This is a limitation we're actively working on lifting very soon, in order to allow for things like blog posts with different slugs to be supported as well.

No configuration is necessary, except for extra.alternate, so if you already have that in-place, navigation should work for pages that have the same path, e.g.:

https://example.com/en/foo/bar/ # <-- Changing language to German ...
https://example.com/de/foo/bar/ # <-- ... takes you here.

Please also note that we're working on improving the projects plugin to allow for easier building of multilingual sites. We'll keep you updated here, as well as in #5800.

[squidfunk]

I've started work on a PR that will add the ability to specify alternate paths if the URLs differ between versions. Work is being carried out in https://github.com/squidfunk/mkdocs-material-insiders/pull/75, which will evaluate the new alternate metadata property of a page. So, say you have the following blog post URLs

https://example.com/en/blog/2023/my-first-post/
https://example.com/de/blog/2023/mein-erster-post/

In both posts, you can now explicitly define the link to the translation, e.g. in the english version

---
date: ...
authors: ...
alternate:
  de: blog/2023/mein-erster-post/
---

Note that this assumes that you have defined extra.alternate in mkdocs.yml for each project. We still need to do the routing based on alternate URLs, but that should be available shortly. Furthermore, since blog URLs are computed, we could add the ability to reference a concrete filename from which the URL is resolved. But this is likely something for later.

[squidfunk]

b00bdfc adds support for resolving path mappings in the frontend. I've attached a self-contained example that shows how it works. It uses the projects plugin and extra.alternate mappings as described above.

https://github.com/squidfunk/mkdocs-material/assets/932156/c894ff5e-0b6c-4745-bd2b-fd28df5872bc

If you want to give it a try, check out the following demo project (Insiders required) ☺️ multilingual-blog.zip

[poettig]

7d8a310 in Insiders adds experimental support for staying on the same page when switching languages.

Thats amazing! Will this eventually be backported into the OSS version once it leaves experimental state or will it stay an insiders feature?

[squidfunk]

Of course, as always! We haven't released it yet, but once we do, it will be tied to the Blockpaprika funding goal, because all previous goals are considered feature-complete, and it will be much more useful together with the projects plugin which is in the same goal. Thus, users of the community edition will have to wait for quite a while until they can start using it, or become a sponsor and use it right now among 25 other features ☺️

[squidfunk]

Released as part of 9.5.1+insiders-4.47.0.

---

This release contains a lot of improvements for the projects plugin. We're making great progress transforming the projects plugin into one of the simplest solutions for building multi-lingual sites, and solving this issue is a first step towards that. There's also https://github.com/squidfunk/mkdocs-material-insiders/pull/75, an open PR on the Insiders repository that implements specific routing between alternate versions if the URLs differ between those versions.

[janvanveldhuizen]

In my case, this setup works perfectly when I am developing my website locally. However, after building and deploying, it no longer functions as expected. Instead of spending a lot of time trying to build an example, I think it's easier to provide a link to the website I am building.

Locally, when I'm on the English version of a page, switching to Dutch immediately brings me to the Dutch version of that page. But in the online version, it redirects to the index.md of the other language.

For example, go to https://janvv.nl/nl/contact/, then switch from Dutch to English. It opens https://janvv.nl/en/ instead of https://janvv.nl/en/contact/. The same behavior occurs for other pages as well.

I'm not entirely sure if this is a bug in mkdocs-material or if it's a configuration issue on my end. You can find a link to my Gitlab repo in the header.

UPDATE: Could reproduce this issue with the provided multi-language-bog example site: https://github.com/squidfunk/mkdocs-material/issues/6515

[janvanveldhuizen]

It would be great to have the same feature for normal pages as well. If you have /en/about-me, then it would be nice to have the translations mapped like

---
alternate:
  de: ueber-mich/
  nl: over-mij/
---

[RxnNode]

b00bdfc adds support for resolving path mappings in the frontend. I've attached a self-contained example that shows how it works. It uses the projects plugin and extra.alternate mappings as described above. Ohne.Titel.mov

If you want to give it a try, check out the following demo project (Insiders required) ☺️ multilingual-blog.zip

Hi, I'm testing with the demo, but I can't get the same result shown in you video. When switching from en blog post to the de one, it redirected to the de main page(http://127.0.0.1:8000/de/), instead of the post in German. Did I miss something? I'm on the latest version of insider.

[squidfunk]

Switching works for when URLs are the same between versions, but not if they're different, which for blog posts, they are. There's already still an open PR over at Insiders for which I'm waiting for feedback, as said in https://github.com/squidfunk/mkdocs-material/issues/4835#issuecomment-1846889331. In essence, you can define alternate URLs to link between pages. We're looking into improving it to make it automatic, but it's still a little way to go. You can test the PR and provide feedback, if you can spare some time.

Edit: here's another example using this PR: https://github.com/squidfunk/mkdocs-material/issues/6518#issuecomment-1861127236

[estan]

I was wondering, with this being closed as soon as it was in the Insiders version, is there some way I can be notified when it's available in the OSS version?

[estan]

I was wondering, with this being closed as soon as it was in the Insiders version, is there some way I can be notified when it's available in the OSS version?

Nevermind, I found how the sponsorware setup works now. So tied to the $ 22,000 – Habanero Orange funding goal (https://squidfunk.github.io/mkdocs-material/insiders/#goals). Sorry for the noise!