• Documentation
  • Transifex Live
  • JavaScript API

JavaScript API

The JavaScript API lets you change the normal behavior of the Transifex Live snippet for specific use cases. Use the API to customize the language selector, to define the language detection on the user's side, to enable the automatic detection of phrases and to mark what's translatable and detectable.

Note

The window.liveSettings parameters are normally controlled remotely within Transifex Live Tool and every parameter set in JavaScript API will override those.

Transifex Live works following this loading process:

  • Read the window.liveSettings options.
  • Parse the static content.
  • Fetch the available languages.
  • Translate a page (if the selected language is not the source language).
  • Store the translations to local storage.

Transifex Live JavaScript code

The liveSettings object contains a set of parameters that define the way Transifex Live behaves, including language detection and language picker settings.

This object supports the following structure in general:

window.liveSettings = {
  api_key: "<key>",
  detectlang: true|false|function() { return lang-code; },
  picker: "top-left|top-right|bottom-left|bottom-right|#id",
  version: 'latest|<version>',
  autocollect: true|false,
  dynamic: true|false,
  staging: true|false,
  parse_attr: ["attr1", "attr2", ...],
  ignore_tags: ["tag1", "tag2", ...],
  ignore_class: ["classname1", "classname2"]
};

Only the api_key parameter is obligatory and the rest of the fields can be set up optionally as described below.

Language detection

The detectlang property is used to define the initial target language of the user.

Values are:

  • true to enable auto detection.
  • false to disable auto detection (default).
  • function for user defined logic.

Example:

window.liveSettings = {
  ...
  detectlang: function() {
    //return language code
    return 'fr';
  },
  ...
}

Auto detection follows the pattern described here.

Language selector

The picker property is an easy way to construct a language selector so that you can switch between languages. It accepts the following options:

  • top-left
  • top-right
  • bottom-left
  • bottom-right
  • element id

The first four options will create a floating selector in the corner of the page. It should probably be used for debugging as each website should define its own style for changing languages.

The element id option will create a select element as a child to the defined element id. For example:

<select id="tx-live-lang-picker">
  <option value="en">English</option>
  <option value="fr">French</option>
  <option value="de">German</option>
</select>

The automatic language selector is fine for getting started, but in practice, each website has its own needs. In that case, its best to use the JavaScript API to create a custom language selector using the following example.

Working with staging servers

Sometimes its useful to be able to prepare your translations on a staging/test server before taking them live to a production server. By default Transifex Live identifies automatically a staging environment from production. You can override this by setting the staging: true option (off by default) on the JavaScript snippet you install on a staging server.

Setting this option has the following effect:

  • Automatically detected and collected strings are marked as staging.
  • The website is translated using translations that have been taken live by clicking Publish to staging in Transifex Live.

Versions

With the version property you can define a specific version of your content to be deployed.

This functionality is to be enabled in the future.

Callbacks

Transifex Live API is making use of the Transifex.live.* namespace and is asynchronous. Callbacks can be registered to capture several Transifex Live events.

onReady

This is called when Transifex Live has been loaded and the translation has been applied to the page. Think of it as the jQuery $(document).ready equivalent.

Transifex.live.onReady(function(load_msec) {

});

The load_msec parameter can be used to benchmark the milliseconds overhead of the Transifex Live operations.

onFetchLanguages

This event is triggered when the available languages have been downloaded from the Transifex CDN.

Transifex.live.onFetchLanguages(function(languages) {

});

The callback takes as parameter an array that describes the languages, for example:

languages = [
  {
    name: 'English',
    code: 'en',
    source: true
  },
  {
    name: 'German',
    code: 'de'
  },
  {
    name: 'Greek',
    code: 'el'
  }
]

onTranslatePage

When a page is translated into a language the following callback is triggered:

Transifex.live.onTranslatePage(function(language_code) {

});

The language_code parameter defines the language the page was translated into.

onDynamicContent

This callback is triggered when dynamic content is detected automatically or when the Transifex.live.translateNode or Transifex.live.translateNodes API calls are invoked.

Transifex.live.onDynamicContent(function(new_strings) {

});

onError

Called when an error has occurred, e.g. translations failed to download.

Transifex.live.onError(function(err) {

});

unBind

Unbind a function from callbacks.

function cb(lang) {
  ...
}
Transifex.live.onTranslatePage(cb);
...
Transifex.live.unBind(cb);

Methods

A set of methods is available after the onReady callback has been triggered.

hasLanguageCode

Check if a language code exists.

true|false = Transifex.live.hasLanguageCode(lang_code)

hasTargetLanguage

Check if target (translation) language code exists.

true|false = Transifex.live.hasTargetLanguage(lang_code)

getSourceLanguage

Get source language.

{code:<code>, name:<name>} = Transifex.live.getSourceLanguage()

getLanguageName

Get language name by language code.

name = Transifex.live.getLanguageName(lang_code)

getAllLanguages

Get all languages.

{...} = Transifex.live.getAllLanguages()

See Transifex.live.onFetchLanguages for the object returned.

matchLanguageCode

Check if a language code has a fuzzy match. For example 'de' and 'de_DE' or 'de-de' will be the same. Return a target or source language code that matches the search.

lang_code = Transifex.live.matchLanguageCode(lang_code)

normalizeLangCode

Normalize language code to match the xx_YY@ZZ pattern.

For example, convert de-de to de_DE.

lang_code = Transifex.live.normalizeLangCode(lang_code)

detectLanguage

Try to guess the user's language based on the browser URL or preferred languages.

lang_code = Transifex.live.detectLanguage()

getSelectedLanguageCode

Get currently selected language code.

lang_code = Transifex.live.getSelectedLanguageCode()

translateTo

Trigger a page to be translated to the defined language code.

Transifex.live.translateTo("fr")

translateNode

Manually translate additional dynamic content by specifying a parent node. New strings are also auto collected if automatic collection is enabled.

Transifex.live.translateNode(element)

e.g. with jQuery:

Transifex.live.translateNode($('#id').get(0));

translateNodes

Manually translate an array of parent nodes. New strings are also auto collected if automatic collection is enabled.

Transifex.live.translateNodes(array)

translateText

Manually translate a text fragment. Strings are also auto collected if automatic collection is enabled.

Dynamic variables are also populated using an (optional) variable object.

var translation = Transifex.live.translateText(
  "Hello {username}",
  {
    username: "John"
  }
);

See example on using this function with dynamic content.