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:
NOTE: All option names are case-sensitive!!

  • 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.
  • autoApprove Defaults to false. If true and you have machine translations enabled, any new phrases found in your website will be automatically moved to the Published bin, and a machine translation will be generated.
  • fetchTranslations Defaults to true. If true, translations will be fetched from Localize.
  • 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 single language code or an array of codes to prefetch specific languages. It is not necessary to prefetch the currently selected target language translations, as they are loaded automatically.
  • 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 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.
  • disableWidget Defaults to false. When true, the default Localize widget is disabled. This option overrides the Widget Customization setting in the Project.
    You can use this option to hide the widget on specific pages in your website. If you want the widget enabled on some pages but disabled on others, you will need to write Javascript code to accomplish this. See the following code sample, and replace PAGE_NAME_HERE with the page name on which you want to hide the widget.
var hideWidget = (window.location.href.indexOf("PAGE_NAME_HERE") > -1) ? true : false;

Localize.initialize({
  key: '[[app:key]]', 
  rememberLanguage: true,
  disableWidget: hideWidget,
});
  • basePath This specifies the 'base' or 'root' path of your application. This will be stripped from the URL of the phrase when seen in the "Filter by pages" feature. For example:
    • full URL = https://example.com/one/two/three
    • basePath = https://example.com/one
    • relative path = /two - phrases will be found by Localize in pages starting at this relative path and in any subfolders contained within this folder
    • If not specified, the default value would be https://example.com in the example above.
  • translateTitle Defaults to true. When true, the <title> tag of the page will be translatable.
  • translateMetaTags Can be used to override the project setting found in the Localize dashboard. If this option is not added, Localize defers to the project setting. Translating meta tags optimizes your site for SEO.
  • translateAriaLabels Can be used to override the project setting found in the Localize dashboard. If this option is not added, Localize defers to the project setting. Translating aria-labels optimizes your site for use with assistive technologies.
  • 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 support@localizejs.com prior to updating this option.
  • retranslateOnNewPhrases Defaults to false. If set to true, Localize will 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 Localize.on() library method with the updatedDictionary event is recommended.
    • When phrases are saved to Localize (either new phrases or deprecated phrases), Localize:
      • ...waits 3.5 seconds, then it checks if the current version of the translation file has been updated since the page originally loaded.
        • If the translation file version has changed since loading the page, the new file is fetched and the page retranslates with the updated translations.
        • Else if the translation file has not changed, then the translation file is not fetched.
      • It repeats the check once more after 6.5 seconds, and fetches the file if it did change.
  • 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.

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. A string with the name of the callback function, or the function itself.
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. A string with the name of the callback function, or the function itself.
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.prefetch

Speed up language switching by prefetching

Localize.prefetch(languages);
  • languages Required. Accepts a string or an array of 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

Suggested Edits are limited on API Reference Pages

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