Detecting Language of a Visitor

Accept-Language, cross-browser compatibility, and the setLanguage Localize event.

Auto-detect Language

By default, Localize will automatically detect and set the preferred language for your visitor.

  • Frontend API option:
    • autodetectLanguage Defaults to true. Automatically set the language to the detected language.
    • If using the subdomains method: The subdomain is checked to detect the language, i.e. fr.localizejs.com.
    • If using the subdirectories method: The first path segment in the URL is checked to detect the language, i.e. www.localize.com/fr.
    • If neither of these 2 methods are used then the language setting in the user's browser is used.
    • This option overrides the Automatically detect website visitor's language preference setting in the Project.

Manually Detect Language

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.

Detecting Language of a Visitor


Accept-Language, cross-browser compatibility, and the setLanguage Localize event.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.