Intended audience: users who want to configure their user agent/browser to automatically download pages in a given language when available (assuming that there are alternate pages on the server, and that the server is set up to negotiate between them).
Updated 2011-03-22 17:56
How do I use the language settings of my browser to specify the language in which a server should send me pages?
When your browser pulls a document from the Web, it sends a request to the server where the information is stored. This is known as an HTTP request. With the request, the browser sends information about its language preference settings. These are preferences about the preferred language of pages, not the user interface of the browser.
The part of the HTTP request that holds this language preference information is called the Accept-Language request-header. If the server can return alternate versions of a page or resource in more than one language, the Accept-Language information can be used to retrieve the page in your preferred language, if it is available, through a process known as HTTP content negotiation. If there is only one version of a page on the server, that version will be retrieved. If the language you request is not available, the server should be set up to return a default language choice.
Mainstream browsers allow you to modify the language preferences expressed by your browser in the HTTP request. The value itself should conform to
BCP 47 (Tags for the Identification of Languages). It is typically a two- or three-letter
language code (eg.
fr for French), followed by optional subcodes representing such things as country (eg.
French as used in Canada).
In many cases, the initial browser setting will meet your needs. For example, if you have a Japanese version of a browser, the browser typically assumes that you prefer pages in Japanese, and sends this information to the server. This article tells you how to discover and change the language preferences expressed by your user agent.
Note: Sometimes a server may determine which language to send to you in a way that doesn't rely on the Accept-Language information. For example, Google tends to use IP information to determine the language you will receive. The browser settings discussed here do not affect content negotiation based on this kind of mechanism.
To configure your browser to automatically download pages in a given language when available (assuming that there are alternate pages on the server, and that the server is set up to negotiate between them), you need to control the information that is sent in the Accept-Language HTTP header when you request the page.
Most browsers have preferences or options that allow you to check or change the language preference settings. On a Mac OS X system, however, you may need to change the OS X system settings.
Most browsers will allow you to specify a list of languages, so that if your first choices are not available you can say what alternative languages to try, and in what order. Typically, when you have multiple languages, the browser will assign qvalues (quality values) to the languages lower down the list. This is a kind of weighting system that is supposed to help the server understand the order in which you prefer the languages. Here is an example of an Accept-Language header with multiple languages. Danish is preferred. If that fails, British English is requested, and finally any type of English.
Accept-Language: da, en-gb;q=0.8, en;q=0.7
If your current browser setting uses a language tag with a region subtag you should ensure that there is another language tag listed after it with just the language subtag (as shown for English in the example). See the notes below for more information.
Some browsers allow you to specify custom language tags, rather than just selecting from a pre-defined list. This can be useful when the browser doesn't provide what you need in its pre-defined lists.
The rest of this article provides more detailed information about these points.
You can use the Internationalization Checker to find out what Accept-Language information is actually being sent by your browser. Run the checker on any page, then in the Information panel, look under Request Headers > Accept-Language. (See an example using this page.)
Here is how you would change the language settings for recent versions of a number of popular browsers on Windows or Mac OS X platforms. Unless otherwise specified, we use the latest versions of those browsers at the time this article was written.
Internet Explorer. When you install a copy of Internet Explorer version 7+, your preferences are automatically set according to the Windows user locale, although you are given the opportunity to modify this when you first install.
By default, the values sent in the Accept-Language request-header from IE7 onwards are typically of the form language-region. Typically no language-only form is included. For example, if you are French your Accept-Language header will present fr-FR to the server. This has implications for some servers, particularly if you add other language tags. See the section below entitled Levels of detail in language tags for more information.
To change your language preferences go to Tools > Internet Options > General (tab) > Languages > Language preference. In IE you can also specify your own customized language tags: click on the 'Add' button in the language preferences dialog, and type your language tag into the 'User defined' field.
Firefox. To change your language preferences go to Tools > Options (Windows) or Firefox > Preferences (Mac OS X), and select Content (tab) > Languages > Choose (button).
You can add languages to this from a (long) pre-defined set, and Firefox will send all the languages you choose with the Accept-Language header in the order in which you arrange them.
You can't create custom language tags using the standard interface. (You can, however, via about:config, using intl.accept_languages if you are geeky enough.)
Safari. On Mac OS X the language sent is that specified in the OS X system language preferences. To change those preferences go to System Preferences > Language & text > Language. You can have a long list of languages in this dialog box, but Safari will only send the top item with the Accept-Language header. You can't create custom language tags.
On Windows, you can't change the language sent by Safari. The language sent with the Accept-Language header is derived from your system settings.
Google Chrome. To change your language preferences go to Options (Windows) or Chrome > Preferences (Mac OS X), and select Under the Bonnet > Web Content > Languages & Spellchecker settings.
You can add languages to this from a pre-defined set, and Chrome will send all the languages you choose with the Accept-Language header in the order in which you arrange them. You can't create custom language tags.
Opera. On Windows you can change your language preferences at Menu > Settings > Preferences > General > Language > Details (button).
You can add languages from a pre-defined set, or create a custom (User-defined) language tag. Opera will send all the languages you choose with the Accept-Language header, in the order in which you list them in the dialog box.
On Mac OS X, Opera takes the list of languages to send with the Accept-Language header from the OS X system language preferences. To change those preferences go to System Preferences > Language & text > Language. You can have a long list of languages in this dialog box, and, unlike Safari, Opera sends all of them with the Accept-Language header.
You can't create custom language tags using the standard interface. (Again, you can if you are sufficiently technically aware to use opera:config and the Network > HTTP Accept Language setting.)
Command sequences for additional browsers can be found at http://www.debian.org/intro/cn#mozilla.
You can typically specify several alternatives that will be treated in order of preference. The following example shows a setting in Firefox for someone who would prefer Swiss French pages, but if that is not available would settle for any French, German or English page, in that order.
Often browsers will allow you to select the languages you want from a list. You may also be able to specify custom language preferences. If you do so, you need to use values that will be recognized by the server (see below).
To ensure success you should configure your browser to request both
fr, in that order. (See the
following section.) This will cause the server to look for a Swiss French version first, but failing that, look for a French version.
If you if you list variants for a given language, your preferences for that language should always be ordered from most to least specific, top to bottom. This generally means, if you use multiple
subtags then include shorter tags lower down the list. For example, when specifying a preference for French and then English in Canada, you would order the list as follows:
fr-CA, fr, en-CA, en.
The basic rule here is that if your language preference list contains a language tag containing a hyphen, such as
fr-CH (French as spoken in Switzerland), you should consider adding an additional language tag without the hyphen, ie.
fr (French) in this case, immediately after.
This is because if a server follows the HTTP/1.1 specification literally, it is unable to match
fr-CH against a document labelled on the server as
In practice, a server such as Apache will actually still produce a result in this case. This is because the server adds an implicit
fr preference to the list.
This preference is, however, added with a very low priority. While Apache's workaround may solve the problem if your language preference list contains only a single language, you can run into problems if you have specified more than one. The Apache documentation explains this as follows:
Implicitly, Apache will add the parent language to the client's acceptable language list with a very low quality value. But note that if the client requests "en-GB; q=0.9, fr; q=0.8", and the server has documents designated "en" and "fr", then the "fr" document will be returned. This is necessary to maintain compliance with the HTTP/1.1 specification and to work effectively with properly configured clients.
Let's look at an example. The language preference list in the image in the previous section will always return a French document on an Apache server labeled as
fr, because the
French [fr] choice is explicitly listed, immediately after
French/Switzerland [fr-ch]. If we remove
French [fr] from the list, however, even though the Apache server adds an implicit
French [fr] value, it has a lower quality value than the
German [de], and therefore a German version of the document will be returned if no Swiss-French version is available (even though a version labeled as French is available).
In a browser like Internet Explorer you may have to specify the simple language tag as a user-defined setting. Other browsers will have selections for these in their pre-defined lists.
You will normally be able to select the language tags you want from a list provided by your browser. This section tells you how to create your own language tags if what you need is not available from the pre-defined list.
Your language tag must start with a two- or three-letter code, called a subtag, from the list of languages specified in the IANA Language Subtag Registry. You may then add a second subtag to indicate a country or region, if you need to. These subtags can also be found in the registry. The first and second subtags must be separated by a hyphen.
Language. The IANA Language Subtag Registry is a long text file. To find a language subtag, search for the name of that language, in English. If we search for 'French', we find a record that looks like this:
Type: language Subtag: fr Description: French Added: 2005-10-16 Suppress-Script: Latn
Note that the type of this record is 'language'. You use the code nearby that is labelled 'Subtag', ie. 'fr'.
Region. If you want to specify that you would prefer a specific type of French, if it is available, you could add a region subtag, such as CA for fr-CA (French as spoken in Canada). To find a region subtag search for the name of the country or region. If you search for 'Canada' you will find a record like this:
Type: region Subtag: CA Description: Canada Added: 2005-10-16
Note that this is a subtag of type 'region', which is what you want. Use the 'CA' subtag (to end up with fr-CA).
Subtags to avoid. You should avoid subtags that are described in the registry as redundant or deprecated. There are other types of subtag available in the registry, but, generally speaking, it is very unlikely that you would need to use them currently for this purpose (because people are unlikely to use the other subtags to label documents on the server).
Chinese. The registry also contains subtags for scripts, but these are not normally needed, and so should normally be avoided. One example of an exception is the script subtag for Chinese.
Chinese people, though they may speak mutually unintelligible dialects or languages, typically write what they want to say in the same way, distinguishing only between Simplified and Traditional forms of Chinese characters. If you are looking for Chinese information, therefore, you may want to simply specify whether the text is in simplified or traditional script, rather than in a specific language.
Due to the absence in the past of a way to refer to script in language tags, servers tended to return text in traditional script if your language setting said zh-TW (Chinese as spoken in Taiwan), and in simplified script if your settings said zh-CN (Chinese as spoken in Mainland China). If your settings said zh-SG (Chinese as spoken in Singapore) or zh-HK (Chinese as spoken in Hong Kong), it is less clear that you would get back what you expect (normally simplified and traditional Chinese, respectively).
The IANA registry now also contains subtags for scripts. The Hans and Hant script subtags in the registry allow you to specify preferences for zh-Hans (simplified Chinese) or zh-Hant (traditional Chinese).
It may be worth doing this, as people begin to label their resources using these subtags on the server. However, you should also include other alternatives, to catch older servers that still use the old approach. For example, if you are living in Taiwan you may want to set up a list of preferences as follows:
zh-Hant zh-TW zh
Note that you should generally avoid using script subtags for other languages in browser settings, especially where the Language Subtag Registry lists a Suppress-Script field for that language. If you do use a language tag with a script subtag, say for Serbian, you should use it as an alternative language tag, ie. alongside the simple language tag.
A nice example of the use of language negotiation is the Press Release of the
W3C Spanish Office’s Standards Tour in 2004, available in English, Spanish, Basque, Catalan, and Galician, as well as Japanese and French. To try this out,
set your preferences to each of the available Iberian peninsular languages in turn, and click on
this link after each change. The codes you need are
ca (Catalan) and
Content first published 2003-10-30. Last substantive update 2011-03-22 17:56 GMT. This version 2012-08-20 19:25 GMT
For the history of document changes, search for qa-lang-priorities in the i18n blog.
Copyright © 2003-2012 W3C® (MIT, ERCIM, Keio, Beihang), All Rights Reserved. W3C liability, trademark, document use and software licensing rules apply. Your interactions with this site are in accordance with our public and Member privacy statements.