Detecting the Language of a Visitor

Auto-detect Rules

By default, Localize For Web will automatically detect and set the preferred language for your visitor based on how you have your site set up, following the rules below.

1st: Subdomain

First the subdomain is checked (es.example.com)

• This is one of the preferred methods for good SEO.
• Read more about using the subdomains method

2nd: Subdirectory

Second the subdirectory is checked (example.com/es)

• This is one of the preferred methods for good SEO.
• Read more about using the subdirectories method

3rd: Browser Preference

Third: The browser language preference is checked

• If neither of the first 2 methods are used then the language setting in the user's browser is used.

📘

autodetectLanguage

The autodetectLanguage option is set to true by default.

If you do NOT want to auto-detect the language, you must explicitly set this option to false in your initialization call to Localize.

Alternate: Query String

You can also set the language on the query string using the parameter: ?ljs=LANG_CODE

If you use this option, it will override other options following these rules:

• If using the subdomains method, ?ljs=LANG_CODE will be ignored.
• So es.example.com?ljs=fr will display Spanish
• If ?ljs=LANG_CODE is set to a language other than the source language, then the subdirectory will not be autodetected.
• So example.com/es?ljs=fr will display French
• If ?ljs=LANG_CODE is set to a language other than the source language, then the language won’t be automatically detected from the browser’s language preference.

📘

Not great for SEO...

Setting the language on the query string is not one of the preferred methods for good SEO.

Manually Detect Language

If you are not using the automatic language detection provided by the Localize For Web SDK, then the best way to detect a user's preferred language is to analyze the Accept-Language header, which is based on the preferred languages set in the user's browser settings or their operating system.

Parse the 'Accept-Language' header (server-side only)

The Accept-Language header is the best method for detecting a user's preferred language. Example:

Accept-Language: en-US,en;q=0.8,es;q=0.6,fr;q=0.4

This may be interpreted as:
"I prefer English (en-US,en;q=0.8), but will accept Spanish (es;q=0.6) or French (fr;q=0.4)".

Here's a simple JavaScript function for parsing the Accept-Language header. It uses a regular expression to return an ordered array of the user's preferred languages.

var acceptLanguage = 'Accept-Language: en;q=0.8,es;q=0.6,fr;q=0.4';

var languages = acceptLanguage.split(':')[1].match(/[a-zA-Z\-]{2,10}/g) || [];
console.log(languages); // ['en', 'es', 'fr']

Localize.detectLanguage()

The Localize JavaScript library provides a detectLanguage method that returns an array of the user's preferred languages based on the Accept-Language header outlined above.

Localize.detectLanguage(function(err, languages) {
  console.log(languages); // ['en', 'es', 'fr']
});

Be careful to only detect the user's language the first time they visit the page. Many users will manually select the language they want to view the page in, and you don't want to override the user's selection when they refresh the page.

Note: Use the server side approach when possible. Since Localize.detectLanguage relies on making an http request to Localize servers, it can take 40-200ms to complete.

IP address lookup (server-side only)

The user's country can be extracted from their IP address. You can then map their country to a particular language.

The risk in this approach is that not everyone in Mexico speaks Spanish, and not everyone in the United States speaks English. And if the user is visiting your website behind a proxy, the country associated with their IP address may be inaccurate.

The Accept-Language approach is generally favored over determining country of their IP address.

Here are a few libraries for detecting a user's country from IP:

Node.js: geoip, geoip-lite

Python: python-geoip, pygeoip

Ruby: geoip gem, geoip

navigator.language

window.navigator.language returns the language of the browser's UI or the user's most preferred language (depending on the browser). This method is not recommended due to its lack of cross-browser support.

Chrome: returns the language of the browser's UI (not the Accept-Language header)

FireFox (5+): returns the user's preferred language (same as the Accept-Language header)

IE (11+): return the language of the user's operating system

navigator.languages

window.navigator.languages returns an array of the user's preferred languages as set in their browser. This array is the same values sent in the Accept-Language header, except for the quality value (ie. q=0.6). We don't recommend relying on this method due to its lack of cross-browser support.

window.navigator.languages // ['en', 'es', 'fr']

Compatibility: window.navigator.languages is only available in Chrome (32+) and FireFox (32+). It will be undefined in all other browsers.

What happens when a user's decides to switch into another language?

Read more about changing content with Javascript and CSS.