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.

Localize.initialize

Localize.initialize(options);

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. www.localize.com/fr. If no language dictionary exists for that segment then the language setting in their browser is used.
  • translateBody Defaults to false. 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.
  • translateTitle Defaults to true. If true, the <title> of the page will translate.
  • translateMetaTags Defaults to false. Allows users to turn on meta tag translation. This optimizes your site for SEO.
  • saveNewPhrasesFromSource Defaults to false. If true, Localize will detect phrases only when the page is not translated. Please contact support@localizejs.com 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 false. If 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.

Localize.setLanguage

Translates the page into the given language.

Localize.setLanguage(language)
  • language Required. Language codes can be found on your Languages page.

Localize.getLanguage

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

var currentLanguage = Localize.getLanguage()

Localize.detectLanguage

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

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

Localize.getAvailableLanguages

Returns all available languages for the project.

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

Localize.translate

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) {
  console.log(translation);
});

Localize.translatePage

Translates all text on the page

Localize.translatePage();

Localize.untranslatePage

Untranslates all text on the page

Localize.untranslatePage();`

Localize.untranslate

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

Localize.untranslate(element);
  • element Required. A DOM node to untranslate

Localize.bootstrap

Bootstrapping translations enables your app to translate without fetching translations remotely from Localizejs.com

Localize.bootstrap(translations);
  • translations Required. Generate properly formatted translations on your Languages page

Localize.prefetch

Speed up language switching by prefetching

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

Localize.phrase

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.

Localize.phrase(phrase);
  • phrase Required. A string or an array of strings

Localize.on

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 }

Localize.off

Remove an event handler.

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

Localize.getExchangeRate

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:
  {
     fromCurrency
     toCurrency
     rate
  }

Library API

Configuration options for the on-site Localize script.