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

To enable automatic language detection and redirection add this line to the bottom of your SiteTran Widget code:

sitetran.auto_switch_from_browser_lang = true;

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) {
  // Put your code here
}

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){
    gtag("event", language_code, { event_category : "sitetran-language" });
}

You can read more about it here.

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 );