Frontend API - Widget Initialization Options

Frontend API

Customize your Widget Initialization settings on any page, and programmatically control the Widget to suit your localization needs.

Widget Initialization Options:

Auto Switch To User's Preferred Language

By default the Widget will automatically detection and redirect to your user's preferred language based on their browser settings.

Read more about it here.

Run Code When The Language Changes

If you want to run some JS code when the language is changed on your website, you can define this function and SiteTran will call it when the language is changed.

sitetran.language_change_function = function(language_code, language_change_reason) {
  // Your code here
}

Here are the values for language_change_reason:

This is especially useful for configuring tracking like Google Analytics:

Connect With Google Analytics

For the newest version (Google Analytics 4), add this code:

sitetran.language_change_function = function(language_code, language_change_reason){
    gtag("event", language_code, { event_category : "sitetran-language" });
}

You can read more about it here.

SiteTran Ready Event

SiteTran dispatches a custom sitetranReady event once the widget has fully initialized. This means the language selector has loaded, any necessary translations have been applied, and the widget is ready for interaction.

You can listen for this event to run code that depends on SiteTran being fully ready:

window.addEventListener('sitetranReady', function() {
  console.log('SiteTran is ready!');
});

Don't Save User's Selected Language

If you don't want the browser to save your user's selected language, you can add this line to your Widget Snippet.

Note: We do not recommend you add this, it will produce a deteriorated user experience.

sitetran.cookie_is_readonly = true;

Don't Update The HTML Lang Attribute

If for some reason you don't want the SiteTran Widget to update the lang attribute of the HTML element, you can add this line to your Widget Initialization code:

sitetran.update_page_lang_attr = false;

The value is true by default, so you don’t need to worry about this UNLESS you need to stop SiteTran from updating it (not recommended).

Ignore Elements From Being Translated Or Discovered

You can define selectors that the SiteTran Widget will not translate or discover phrases in. You do it by adding the sitetran.ignore_selectors array after you initialize your SiteTran widget object on pages that you contain content you want to ignore. List all the elements you want to ignore using their selectors such as class, ID or attribute…

sitetran.ignore_selectors = [ ".some-selectors", "#another-one-that-you-ignore" ];

Read more about it here.

Don't Update Hreflang Attributes

If you need to stop the SiteTran Widget from updating the page's hreflang attributes, you can add this line to your Widget Initialization code:

sitetran.update_page_hreflangs = false;

sitetran.update_page_hreflangs is true by default, so you don’t need to think about this UNLESS you know that you need to stop SiteTran from updating the hreflangs, for example if they’re being set somewhere else already.

Disable Direction Change

If you need to stop SiteTran from updating the direction of a page when the language changes to/from a right to left (RTL) or left to right (LTR) language, you can do so by adding this line to your Widget Init:

sitetran.update_direction = false;

Translate HTML Comment Elements

If you need to translate HTML comment elements, you can do so by adding this line to your Widget Init:

sitetran.translate_html_comments = true;

Change Widget Speed For Dynamic Content

You can change the default value of 0.5 seconds to specify how often you want the widget for new phrases to translate on the page.

Here's how to do it:

sitetran.refresh_translation_seconds = 0.5;

You can read more about it in this article.

Using JSONP Instead Of JSON

By default, SiteTran uses JSON not JSONP.

This is not something the average user needs to think about, but if you need to use JSONP instead of JSON, you can add this at the end of your widget initialization snippet:

sitetran.use_jsonp = true;

Programmatic Widget Control:

Access, use, update or hook into the Widget programmatically.

Get User's Selected Language Code

To return the currently selected language of a user, call:

sitetran.lang;

Which returns "en" if the user's selected language is English.

Programmatically Changing Language

To change languages using JavaScript, call this function. You can pass any language_code from the available live languages on your site.

‘es’ for example is for Spanish.

sitetran.api_change_language(language_code_goes_here, language_change_reason);

language_change_reason defaults to 'API-PROG' if not specified, you can also pass your own language_change_reason.