FAQ: How do I read MDN in English?

Several MDN readers have a similar problem: They want to read MDN content in English, but instead are getting pages in a different language. This is a hard problem to solve, but there are some things you can do to see more English on MDN.

Examples of the problem

Here are some ways this issue occurs:

  1. An Italian developer types “developer.mozilla.org” in the browser location bar. They are redirected to https://developer.mozilla.org/it (Italian). They wanted https://developer.mozilla.org/en-US (English).
  2. A German developer uses https://www.google.de/ to search for “array foreach”, and are linked to https://developer.mozilla.org/de/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach. They wanted the English version, https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach.

Some reasons why developers prefer the English document:

  • The translation is stale, and doesn’t include changes made to the English page.
  • The translation is a mix of English and their language, and just English would be easier to follow.
  • Their development team or community uses English.
  • Most technical documentation is in English, and they want to stay in English when reading.
  • They prefer to use machine translation of the English content.

If you’d like to help improve the translations, see https://developer.mozilla.org/docs/MDN/Contribute/Localize

Why does this happen?

MDN has two kinds of URLs - locale-specific URLs, and locale-redirect URLs.

Locale-specific URLs specify the locale in the URL. For example, the URL https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language specifies en-US, or English (US). The same content is available in French at https://developer.mozilla.org/fr/docs/Web/HTTP/Headers/Accept-Language, which specifies fr. Sometimes, just the locale changes in the URL, but in other cases, the slug is translated, such as https://developer.mozilla.org/en-US/docs/Learn/Getting_started_with_the_web versus https://developer.mozilla.org/fr/docs/Apprendre/Commencer_avec_le_web.

Locale-redirect URLs do not specify the locale, and are the English document without en-US/. For example, https://developer.mozilla.org/docs/Web/HTTP/Headers/Accept-Language will redirect the user based on the browser’s Accept-Language header, which specifies the user’s language preferences. The Accept-Language setting is often determined from the language settings of the operating system, or by downloading a region-specific version of a browser.

Search Engines, such as Google, only index locale-specific URLs. If the engine determines that you would prefer a language (such as using https://www.google.de/, or searching from a German IP address), then Google will prefer to show MDN pages in that language, and you won’t see the MDN page in English.

Please continue using locale-specific URLs

You may be tempted to switch translations to use locale-redirect links. However, we’d like you to continue to use locale-specific URLs in MDN documentation, so that visitors and search engine crawlers get a consistent locale. For the complete discussion, see Localized URLs Hardcoded.

Workarounds and short-term solutions

There are some things you can do to get English content on MDN more often.

Install an add-on / extension / plugin

The English Content Firefox add-on redirects to the English document on MDN and other developer sites, and is the most direct way today to say “Show me MDN in English”. There may be other plugins, and writing a plugin would be a way to explore the design issues and become a hero to MDN readers with your issue.

Configure the Accept-Language header

If you prefer English all the time, then find the browser setting to change your Accept-Language setting.

Set your preferred language for search

For Google, you can set your preferred language to English, or ask Google to show multiple languages in results. See https://support.google.com/websearch/answer/3333234.

Set a language preference cookie

When MDN detects that you’ve changed languages, we ask if you want to remember that preference. If you select Yes, then we save a cookie that overrides Accept-Language for locale-redirect URLs. This does not change the language for locale-specific links.

Select%20English

Use an offline documentation tool

There are third-party tools that include some MDN English documentation for specific topics, such as the CSS Reference.

Long-term solutions

MDN’s Mozilla staff is aware of the problem with translations, and that a significant number of users prefer to always read English. We hope to improve the experience of MDN for non-English readers. The developers think it will take a 3 to 5 year effort to redesign the content engine, rather than a series of bug fixes for the current content engine. Some design goals for a new content engine are:

  • Make it easy for the community to keep translations up to date
  • Avoid indexing out-of-date or incomplete translations
  • Avoid showing out-of-date or incomplete translations by default
  • Prioritize translations of the most useful pages
  • Allow users to customize when a translation is shown
  • Allow users to automatically redirect to the English page

We’re also researching the costs and benefits of translations by page type (reference versus Learning Area), and the value of translations to groups of native speakers, to determine how much resources should be dedicated to translations versus other priorities.

Previous discussions

Most of the previous discussion of this issue is in Bugzilla, such as

  • bug 1331729 - Introduce a language preference/cookie to prevent site redirections
  • bug 1440602 - Always view documentation pages in user selected language
  • bug 1432826 - Create a “MDN in English” extension to make it easier to view MDN in English

One of the goals of this post is to have a summary of the issue for future bug reports, with some helpful advice for readers with with annoyance.

6 Likes

i’m having trouble can you find me i really need your help through this