Library API

Configuration options for the on-site Localize script.

Visit our Installation Guide for step-by-step instructions for adding our client-side Javascript library to your site.



Available options:

  • key Required. Your project key. Find it here.
  • targetLanguage Language to translate your website to.
  • rememberLanguage Defaults to false. If true, Localize will translate your website to the last selected language on subsequent page views.
  • fetchTranslations Defaults to true. If true, translations will be fetched from Localize if not bootstrapped.
  • saveNewPhrases Defaults to true. If true, unrecognized phrases will be added to your Localize account. Disable this in development.
  • translateAlt Defaults to true. If true, "alt" attributes will be translated.
  • prefetch Defaults to false. Set to true to prefetch all active languages, or pass a language code or an array of codes to.
  • blockedClasses Array of class names for which Localize will ignore.
  • translateClasses Array of class names for which Localize will translate. If you use this option, Localize will only translate content contained in these classes and will ignore all other content in the body of the page.
  • autodetectLanguage Defaults to true. Automatically default the page language to the user's preferred language. The first path segment in the URL is used to check to detect the language, ie. If no language dictionary exists for that segment then the language setting in their browser is used.
  • translateBody Defaults to true. When true, Localize will attempt to translate the entire body of the page. If false, Localize will only translate content contained with a "localizejs" class name.
  • defaultLanguage The default language your website will be in when no language has been selected. Defaults to the source language of your website.
  • basePath The base path will be stripped from the URL of the phrase as seen in the "Filter by pages" feature (e.g. becomes /pagename).
  • translateTitle Defaults to true. When true, the <title> of the page will translate.
  • translateMetaTags Can be used to override the project setting found in the UI. If this option is not added, Localize defers to the project setting. Translating meta tags optimizes your site for SEO.
  • saveNewPhrasesFromSource Defaults to false: new phrases are only detected when a user is displaying a page in a target language. If true, Localize will detect phrases only when the user is viewing a page in the source language. Please contact prior to updating this option.
  • retranslateOnNewPhrases Defaults to false. Automatically translate content that is added dynamically to your webpage. For example, if your webpage dynamically adds html into the source of the page, our library will translate it once the translations have been generated. Behind the scenes this means the dictionary file with all your translated content is available for use with Localize.translate(). However, translations are not generated instantly, so use with our library event updatedDictionary is recommended.
  • enhancedContentSecurity Defaults to true. When true, the Localize library will not send additional metadata to our servers. This metadata includes the surrounding HTML of the phrases detected on your website.
  • translateTimeElement Defaults to false. If true, the Localize library will pick up phrases in the <time> elements.
  • translateNumbers Defaults to false. If true, the Localize library will pick up numbers as phrases.


Translates the page into the given language.

  • language Required. Language codes can be found on your Languages page.


Returns the current language of the page. If a language hasn't been set, source is returned.

var currentLanguage = Localize.getLanguage()


Returns the visitor's list of preferred languages, based on the browser's "accept-language" header.

  • callback Required.
Localize.detectLanguage(function(err, languages){
  if (err) return console.log(err);


Returns all available languages for the project.

  • callback Required.
Localize.getAvailableLanguages(function(err, languages) {
  // Do something with the languages array


Translates text or text within html.

Localize.translate(input, variables, callback)
  • input Required. Can be text, html or native DOM elements
  • variables Optional. Object of variables that will be replaced in the input, if it's a string
  • callback Optional. Callback will trigger once translations have been fetched from Localize.

If the Localize.translate() input is a string, instances of %{variable} will be replaced with the given value in the variables object. You may also use HTML <var> tags in the string For example, all of the following variations are supported:

Localize.translate('My name is %{name}', { name: 'Joe' }, callback);
Localize.translate('My name is <var name></var>', { name: 'Joe' }, callback);
Localize.translate('My name is <var name>Joe</var>', callback);

If the active language is the source language of the page, Localize.translate will return the untranslated phrase.

Localize.translate can be used with or without a callback. We highly recommend using the callback approach if you're calling Localize.translate in the first 10 seconds of page load to ensure that the latest translations are available. The callback will allow the translation to delay until translations have been fully loaded into the browser. If the translations are already loaded, the callback is executed immediately.

Localize.translate('My name is %{name}', { name: 'Joe' }, function(translation) {


Translates all text on the page



Untranslates all text on the page



Untranslates a specified element on the page. Use Localize.untranslatePage() if untranslating the whole page.

  • element Required. A DOM node to untranslate


Bootstrapping translations enables your app to translate without fetching translations remotely from

  • translations Required. Generate properly formatted translations on your Languages page


Speed up language switching by prefetching

  • languages Required. Accepts a string or an array or languages (ex. 'zh-CN')


Saves the phrase, if unrecognized, to your Localize project. Useful for ensuring rarely printed text (ie. an obscure error message) is translated. Returns the phrase it was passed.

  • phrase Required. A string or an array of strings


Attach an event handler to Localize events.

Localize.on(eventName, fn)
  • eventName Required. Name of event to bind to. Can optionally be namespaced: "setLanguage.ns"
  • fn Required. Event handler.

Available events:

  • initialize - passes initialization parameters
  • setLanguage - passes { from: oldLang, to: newLang }
  • pluralize - passes { node: pluralizedNode }
  • translate - passes { node: translatedNode }
  • untranslatePage
  • **updatedDictionary passes { dictionary, version, language }

Remove an event handler.[, fn])
  • eventName Required. Name of event to unbind from. Can optionally be namespaced: "setLanguage.ns"
  • fn Optional. The function to unbind from the event.


Returns exchange rate for provided currencies.

Localize.getExchangeRate(fromCurrency, toCurrency, callback)
  • fromCurrency Required. The default source currency, to be converted from.
  • toCurrency Required. The new currency, to be converted to.
  • callback Required. Receives err and rateData arguments.
rateData schema: