Detecting the Language of a Visitor

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

Auto-detect Rules

By default, Localize 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 (

2nd: Subdirectory

Second the subdirectory is checked (

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.



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: ?lsj=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 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 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

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:


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']


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


**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

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.

Updated 2 months ago

Detecting the 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.