Skip to content

Navigation Menu

Sign in
Appearance settings
mdn

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings
Discussion options

tl;dr

We launched an experimental MDN feature on September 25, 2024 that allows users to choose their preferred language and automatically switch to this language when the requested content is available in that language.

Screenshot of 'Remember language' setting

Background

MDN is currently available in English (en-US) and 8 other translated languages (es, fr, ja, ko, pt-BR, ru, zh-CN, zh-TW) and users have always been able to switch to their preferred language manually using the language menu.

Problem

There have been two outstanding issues:

  1. Some users prefer English, but their search engine suggests links to their local or native language, so every time these users have to manually switch to their preferred language.
  2. Some users prefer a translated language and some content is unavailable in these languages, so MDN links to the English language instead, but this means these users have to manually switch back to their preferred language.

Solution

We have introduced a "Remember language" setting in the language menu. Enabling the setting saves the current language in the preferredlocale cookie, and this will prompt MDN to redirect users whenever they navigate to a page that is available in that language. Disabling the setting will delete the cookie, and users will no longer be redirected.

Note: The cookie has been previously used to save the last language that the user switched to. For this reason, the setting is enabled for all users that have recently switched the language on MDN.

Use case 1: Preference for English

Charlie lives in France and uses French Google, but prefers to read MDN in English, so they enabled "Remember language" while browsing MDN in English.

  • Charlie searches for "localstorage" on Google.
  • Google suggests https://developer.mozilla.org/fr/docs/Web/API/Window/localStorage in French.
  • Charlie clicks on the link.
  • Because Charlie's browser sends the preferredlocale=en-US cookie, they now get redirected to English:
    /fr/docs/Web/API/Window/localStorage
    → /en-US/docs/Web/API/Window/localStorage
    
  • Charlie no longer has to switch the language manually.

Use case 2: Preference for translated language

Jin lives in South Korea and has basic English knowledge, but prefers to read MDN in Korean, their native language, so they enabled "Remember language" while browsing MDN in Korean.

  • Jin is browsing MDN in Korean, and clicks on Blog in the top menu.
  • As the Blog is only available in English, Jin is now browsing MDN in English.
  • Jin opens the "New JavaScript set methods" blog post.
  • The Blog post contains links to several English pages in the MDN Web Docs, like the following one:

    intersection() returns a new set with elements in both this set and the given set.

  • Jin clicks on the intersection() link.
  • Because Jin's browser sends the preferredlocale=ko cookie and the page is available in Korean, they now get redirected to:
    /en-US/docs/Web/JavaScript/Reference/Global_Objects/Set/intersection
    → /ko/docs/Web/JavaScript/Reference/Global_Objects/Set/intersection
    
  • Jin no longer has to switch the language manually.
You must be logged in to vote

Replies: 25 comments · 13 replies

Comment options

This is an amazing experiment, I'd love to hear how it ends up helping folks read better on MDN! 📚

You must be logged in to vote
2 replies
@piligrim554
Comment options

Sanks very much💪💯💪🤟

@bharathi9989
Comment options

Please translate the course into Tamil. Tamil people also have good knowledge and logical skills, but some of them cannot understand English fluently

Comment options

I have just found this page from the "?" icon next to the feature. I just wanted to sing a few words of praise.

A bit of feedback:

  • I speak French, English and German, in order of fluency
  • My browser languages are German, English and French, in order of preference
  • I prefer to read documentation in English, the technical language I prefer
  • Google prefers to show me results in German, as I intend it

So what is my intent? It depends on the task:

  • German to get a bit of language practice
  • English because it's the language I usually work in
  • English because the original is often much better than the translation
  • French/German because the task has some cultural context
  • English/French/German because I need instructions in the same language as the software or operating system I am using

A pet peeve of mine is clicking on an English result and seeing the German version, then having to scroll all the way to the bottom of the page to change the language. A bit later, I click another English result and the same thing happens again.

I find your approach very elegant, and accommodating to all user intents. Very well done!

You must be logged in to vote
0 replies
Comment options

I was wondering why my automatic redirection to English was acting weird, turns out I don't need it anymore!

Thank you for this QoL experiment!

You must be logged in to vote
0 replies

This comment was marked as spam.

Comment options

OMG YOU ARE A SAVIOUR. For years I had to manually change the langague to english, because MDN translations are inconsistent (they generally have less content that the page in english and some layouts are broken).

You must be logged in to vote
0 replies

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

Comment options

Hi!

Some weird behaviour regarding language redirections: If a MDN url is shared with NO language slug (without the /en-US/ or any other language part), it will redirect to the 'remember language' locale version of that page regardless if that translation exists or not.

Example:

In this scenario:

Maybe this extra click to get to the English fallback page is the intended way to work. But it's a bit weird given that MDN asks to always use this non-localized format in the "mdn_url" field of several repos and services like BCD.

One idea: all these non-localized urls could always be redirected to the /en-US/ version in the first place; then, if the user has set a preferred language, check if that page has a locale version. If the translation exists, redirect, and if not, stays on the English page.

Not sure if this is a good idea as it could generate a lot of redirects. Another option would be to change all those mdn_urls to their /en-US/ version in the origin, but I guess that would also involve other complex things beyond my experience. And having that extra click is not a big deal for the user, really. Anyway, I came upon all these links and just wanted to point that out.

Regards!

You must be logged in to vote
2 replies
@caugner
Comment options

caugner Nov 12, 2024
Maintainer Author

Thank you for taking the time to report this issue, which is similar to https://github.com/mdn/yari/issues/11717.

@decrecementofeliz Can you share whether your browser's preferred languages include English? You can check via this Playground.

@decrecementofeliz
Comment options

Hi, yes, my browser (Firefox) includes English (and Galician and Spanish) as preferred language:

en,gl,es

Comment options

Tnx for support

You must be logged in to vote
0 replies
Comment options

There's another problem solved by the solution: I prefer local language, but sometimes I use English search engines. The search engine will give me English page and I had to switch back to my local language. This solution is really amazing!

You must be logged in to vote
0 replies

This comment was marked as off-topic.

This comment was marked as spam.

Comment options

I also prefer English for development. It makes sense when you develop in English, with English variable names, English comments and English syntax. In my opinion, every developer should develop in English. It's easier to understand in a software context and you can communicate better with other developers around the world. Same for error messages and the use in search engines. I watch movies, play games and search the web in my native language, but when developing, everything has to be in English. It really bothers me when MDN is displayed in my native language and not in English. Thank you for addressing the matter, but it seems that it’s not working as expected.

My case:

  1. Open search engine: https://www.google.de/ (Google aggressively uses your language. Means https://www.google.com/ is also in German)
  2. Search for: date getDay
  3. Click on the suggested page (MDN): https://developer.mozilla.org/de/docs/Web/JavaScript/Reference/Global_Objects/Date/getDay
  4. The page is displayed in the German language as specified in the URL (de).
  5. Ok, test the new feature and switch to English with Remember language enabled.
  6. Repeat (open the link again): Result: German again. Not English as expected.

DuckDuckGo behaves similar. My choice of langauge select (remember) should ignore/override the URL. Correct URL:
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getDay

Btw. I would prefer it to be permanent in localStorage rather than in expiring cookies, but I can live with changing it again once a year.

Why not just remove the language from the URLs? Because every user would read this in their own language (which can be changed via the selected input and is preselected by browser language by default). It makes no sense to have the language in URL. Not for bookmark, not for sharing, etc. I would never share the langauge URL to e.g. forums, etc. It would aldo reveal my language. Without this information, each user has a neural URL where the content is displayed in their individual language. If you want to point something to a specific language because it only appears there, just tell which language you want to switch to. Any reason against removing the language from the URL?

You must be logged in to vote
3 replies
@caugner
Comment options

caugner Feb 20, 2025
Maintainer Author

@fudom Thanks for sharing this feedback and your experience.

Repeat (open the link again): Result: German again. Not English as expected.

This sounds like a local browser caching issue, because our CDN uses the preferredlocale cookie to segment the cache. Assuming that the preferredlocale cookie is properly set, can you please verify if you still don't get redirected to en-US if you do a hard-refresh?

Why not just remove the language from the URLs?

I'm not exactly sure what you have in mind, but if you're suggesting to serve different content on the same URL depending on cookie or Accept-Language,, then this isn't a good practice, and neither recommended nor viable from an SEO perspective.

@fudom
Comment options

Now it works. Without hard reloading. I forgot to do a hard reload when I had the problem. I'm just wondering: Why Cookie (expiring) and not LocalStorage (persistent)? Regarding the language code in URL: I missed the SEO point. I don't know what options and best practices there are. Anway... Thanks for the feature. 👍

@caugner
Comment options

caugner Feb 20, 2025
Maintainer Author

Why Cookie (expiring) and not LocalStorage (persistent)?

The primary reason is that the redirect to your preferredlocale is executed server-side using an HTTP 302 redirect. We did consider handling the redirect on the client side, but ultimately felt it wouldn’t provide the best user experience.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

Comment options

I simply don't understand why most companies that have some kind of developer documentation now show some terrible machine translated version. It's so annoying and unnecessary.

You must be logged in to vote
3 replies
@caugner
Comment options

caugner Jun 2, 2025
Maintainer Author

Thanks for flagging this.

@K0bin Just to make sure: Are you talking about machine-translated docs in general or MDN's German pages in particular? If it’s MDN, could you please share some examples so that we can fix those?

For more background on why we added German to MDN, see this discussion.

@K0bin
Comment options

@caugner I mean in general. The fix is really easy. Disable the machine translation altogether and always serve the English version.

Besides MDN, Microsoft and Google also serve machine translated versions of their developer documentation now and it's incredibly annoying to have to change it to English manually every single time.

@Florinstruct
Comment options

Yes, nobody asked for this, nobody likes it. It literally makes a considerable percentage of your audience hate you. See Youtube.

This comment was marked as spam.

Comment options

caugner
Aug 25, 2025
Maintainer Author

Update: MDN has a new front end! 🎉 To address some of the feedback in this discussion, you can now switch from a translated page to the English original with just a single click, either temporarily ("View in English") or permanently ("Always switch to English"):

image

PS: "Always switch to English" enables the "Remember language" feature, which remains accessible from the language drop down.

You must be logged in to vote
0 replies
Comment options

It doesn't work for me. My german search engine always sends me to the German page in new tabs.
What is the technical reason for not simply checking the preferred languages of the browser? Mine is set to English, on purpose, so I see dev related sites in English. I'm not interested in seeing translations at all.

You must be logged in to vote
3 replies
@aldafu
Comment options

so much this. it's so frustrating, aggravating even.

@caugner
Comment options

caugner Oct 16, 2025
Maintainer Author

Please see my previous comment.

tl;dr You can now switch to English permanently with a single click.

(If that doesn't work, please file a bug.)

@annam002
Comment options

This works only as long as you keep the cookie. If you clean up the browsing data regularly, you still get it in the wrong language the first time you open it.
I would like to repeat the question: why do you not look at the preferred languages set in the browser?

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Morty Proxy This is a proxified and sanitized view of the page, visit original site.