Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Documentation

If you need help with something, don't hesitate to contact us! We're available during normal business hours.

Easy for Non-Developers

SiteTran is a website translation tool, built for developers and non-technical people alike.

The average user doesn’t need to know how any of this code works. We've got you covered in that department. Integration is a one time thing. Once it’s done, you don’t really need to think about it again. Just follow our integration instructions, and you should be up and running, hassle free within minutes!

Highly Customizable

The SiteTran Widget is very customizable. You can change almost any setting, style or design to ensure your users get the best possible internationalized experience.

For customizing the design, you can use our widget editing tool, useful for making most adjustments.

More advanced design changes will require a little knowledge of CSS, but since the widget’s CSS is totally exposed, it’s really easy to make changes to the styles. Pay attention to your widget_type when customizing the widget.

How Does SiteTran Work?

SiteTran works by translating phrases on the front-end of your site, dynamically replacing them with their corresponding translations in the DOM, which is what creates your site on the front end - what the end user sees.

Because of this, translating your website to perfection with SiteTran rarely requires any changes to be made to your original content, and SiteTran requires almost no intervention from developers. This massively reduces the time and cost needed to translate and maintain your website’s translations.

In order for SiteTran to work its magic, all you need to do is:

  1. Integrate SiteTran with your site, by adding your SiteTran Widget, a few lines of code, to each page of your site that you want translated.
  2. Get your website’s phrases into SiteTran.
  3. Translate and approve those phrases.

The SiteTran Widget produces a language dropdown on each page allowing your users to switch to any languages that you’ve made public in your SiteTran site.

How Do I Integrate SiteTran with My Site?

  1. If you haven’t already, sign up to SiteTran, and create a new site. 
  2. Go to your site’s Widget page and copy your widget code. 
  3. Paste it before the closing </body> tag on every page that you want translated

Widget Code Explained

Our copy-pastable code snippet contains crucial code that must be added to each page of your site that you want translated in order for SiteTran to work properly. The widget that you can copy from your site’s widget editing tool doesn’t need to be changed, but it’s nice to know what’s in there, so here’s the breakdown:

  1. HTML which includes a div element with the ID sitetran_translate_element. It might have parent elements (other elements around it) if you’re including an icon.
  2. CSS, used to add styles to your widget. Everything between the <style> tags is the widget’s CSS.
  3. JavaScript (JS), between the <script> tags. There’s a link to SiteTran’s widget code, which is what powers everything, and a separate script element contains the JS code needed to initialize your widget with your site’s parameters.

Whenever we're talking about the "Widget Snippet", or "Widget Initialization Code", or anything sounding like "Widget Code" — the code below is what we're referring to.

If you look at your Widget Snippet, you’ll see script tags containing the JavaScript that initializes your SiteTran Widget.


<script>
var sitetran = {};
sitetran.site_id = 123;
sitetran.site_default_language_code = "en";
sitetran.url_type = "none";
sitetran.widget_type = "styled-select";
</script>

We'll examine a few lines of the Widget Initialization Code.

sitetran.site_id = 1234; ← That's one line of your widget code.

1234 is an example site_id, yours would be different. Your site_id is your public key. It’s needed to retrieve your site’s translations.

sitetran.site_default_language_code = "en";

This lets SiteTran know the language that your site’s phrases were written in. It’s the language we show in the widget if no other language was previously selected by a user on your site.

sitetran.url_type = "none";

This is one of the ways to add the selected language code to your URLs. The options are:

  1. sitetran.url_type = "none"; ← No language code in URL.
  2. sitetran.url_type = "hash";  ← The language code gets added at the end like www.example.com#en
  3. sitetran.url_type = "sub.domain"; ← Configure subdomains. Requires a few more steps. Contact us!

Note: adding the language code as a subdirectory can be accomplished either by using a plug and play SiteTran integration, or by integrating with the Static API.

sitetran.widget_type = "styled-select";

The first step to styling your widget is deciding on a widget type. There are a few widget types that allow you to accomplish different things:

  1. sitetran.widget_type = "select"; ← The most basic select box. No additional styles.
  2. sitetran.widget_type = "styled-select"; ← Our beautifully styled select box. Guaranteed to work everywhere
  3. sitetran.widget_type = "list"; ← Our beautifully styled list, that also covers the ability to produce fully customizable dropdowns (select boxes have many limitations).

Automatic Language Redirection

Automatically detects and switches to your user’s preferred language based on their browser settings.

Note: This is not the same thing as the sitetran.sitetran_lang cookie which is used to remember a user’s language (if they selected one).

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


sitetran.auto_switch_from_browser_lang = true;

sitetran.auto_switch_from_browser_lang defaults to false. Your website’s visitors by default will not have their language changed to their browser's language automatically unless you set it to true.

Run Your Code When the Language Changes

If you want to run some code when the language is changed, you can define this function and it will run when the language is changed.

Especially useful for configuring things like Google Analytics tracking


sitetran.language_change_function = function(language_code){
    // Put your code here
}

Stop SiteTran from updating page’s HTML lang attribute

If a page is in English, The HTML lang attribute should be "en".

<html lang="en">

SiteTran automatically changes the language code for example to "es" if the user switched to Spanish, but if you want to stop the SiteTran widget from updating the lang attribute of the HTML element, you can add this code to your Widget Snippet.


sitetran.update_page_lang_attr = false;

It is true by default, so you don’t need to worry about this UNLESS you know that you need to stop SiteTran from updating the lang attribute of the HTML element.

Stop SiteTran from updating page’s hreflangs

If you want to stop the SiteTran widget from updating the hreflangs, add this in to your Widget Snippet.


sitetran.update_page_hreflangs = false;

It is true by default, so you don’t need to worry 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.

Configuring Google Analytics with SiteTran

We’re using


sitetran.language_code_function

from above to trigger an event on your Google Analytics tracker.

This is for the newest version of Google Analytics (Google Analytics 4)


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

Note: If you’re still on the older version of GA you should replace the gtag line above with the ga code below.


ga("send", "event", "sitetran-language", language_code);

Change Translation Speed

This is the frequency at which SiteTran checks for new phrases on your page.

Add this code at the end of your widget initialization snippet.


sitetran.refresh_translation_seconds = 2;

This value defaults to 0.5, which is half a second. So SiteTran checks to see if there are any phrases on the page missing translations every half second. This is very useful because the phrase isn’t always available to be translated by SiteTran in your HTML, when you have phrases in popups, or anything being added by javascript, dynamically translating on the front end with SiteTran becomes very useful.

Choose Between JSON and JSONP

sitetran.use_jsonp defaults to false. Meaning, by default we use JSON not JSONP. This is not something the average user needs to think about, but if for some reason you would rather use JSONP instead of JSON, you can add the code below at the end of your widget initialization snippet.


sitetran.use_jsonp = true;

Hide the Widget (Language Dropdown)

You can hide the language dropdown on a particular page, but still have the SiteTran Widget translate.

This can be useful on a page where you don't want the language dropdown, but you do want SiteTran to set the site language based on the user’s previously selected language, or if you are automatically redirecting users based on their preferred language set in their browser settings. (Note: From a UX perspective, your users should have access to the language dropdown on at least some pages).

Here's what you do:

First, wrap your SiteTran Widget's HTML parent element with a div. The Parent element you are wrapping should  either have the ID sitetran_translate_element or if you're using an icon, it will have the ID sitetran_translate_wrapper.  Wrap all that HTML with a div that has a class like "sitetran_hide_wrapper". It should look like this:


<div class="sitetran_hide_wrapper">
    Your Widget HTML Here
</div>

Next, add these CSS styles to your page.


<style>
sitetran_hide_wrapper {
    display: none;
}
</style>

Get User's Selected Language Code

To return the currently selected language code call:


sitetran.lang;

console.log(sitetran.lang);

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

Programmatically Change Language

To change languages using JavaScript, call these 2 functions one after another. You can pass any language_code from the live languages on your site.

‘es’ for example is for Spanish.


sitetran.widget_set_language_code( language_code_goes_here );
sitetran.onchange_event_function();

Don't save user's selected language

If for some reason you don't want the browser to save your user's selected language, (which will lead to the user needing to change languages on each page load), you can add this line to your Widget Snippet.

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


sitetran.widget_set_language_code( language_code_goes_here );
sitetran.onchange_event_function();

Translating Images/URLs

It’s really easy to translate images or URLs (they both use the same functionality) with SiteTran. Simply add the URL of the image src as you would any other phrase, and then for the translation add the source URL of the translated version of your image/url.

Ignore/Exclude Phrases from Being Translated or Discovered

Sometimes you need to be sure that certain phrases or HTML elements containing content will not get translated. 

SiteTran provides you with two different methods to accomplish this.

1. Inline HTML:

Use either the class "notranslate", or the attribute translate="no" to stop SiteTran from translating phrases within elements. SiteTran automatically ignores elements that have the class notranslate, or the attribute translate="no".

If your ignored element contains phrases nested within it that you DO want to translated, you can add the translate="yes" attribute to the element(s) you want translated. 

The notranslate class and translate="no" attribute also work to block those elements from getting translated by Google Translate which is great because often users will use Google Translate if your website isn’t translated to their preferred language with SiteTran, this will enhance their experience.

2. JavaScript:

You can define selectors that the SiteTran widget will not change languages on. You do it by adding the sitetran.ignore_selectors array after you initialize your SiteTran widget object on each page, and then you can 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" ];

Can I translate text in a CSS content="my text" style for a ::before pseudo-element

Let’s say you have some element like a div with a ::before pseudo-element:


<div>
::before
</div>

The content of ::pseudo is determined by the CSS content style. You can translate the text of the content style by overwriting the CSS for each language. For example:


<style>
.yourClassOrOtherSelector:before {
    content: “Your Translation Goes Here" !important;
}
</style>

Note: we’re using 1 colon in the :before instead of 2 because it seems to have better browser support for the selector and it matches both 1 and 2 colons.

Follow the instructions for updating CSS by language below, and add the CSS to override the content for each language and URL Selector so that those styles only appear on the correct page.

Replace the .yourClassOrOtherSelector with your class or some other query selector, and Your Translation Goes Here with your translation.

Second Note: You can add the original phrase(s) to a page-doc in order to get them translated. After they're translated, you will have to add a CSS style for each language, and add the translated phrase from the page-doc in the CSS for Your Translation Goes Here.

Updating Styles (with CSS) by Language and Page

In SiteTran: 

For when you need to update the CSS for a particular language and page on your site. This is powered entirely through SiteTran, and requires no additional work from a developer.

CSS is set by language, so first go to your languages & translators page. Select “manage translators” for the language you want. On the bottom of that page, you’ll see a button with “Add CSS Styles for LANGUAGE”. Click that button!

Now you can add your CSS by language and page.

The first input area asks you for a URL to select for. This is so that you can specify exactly what page you want this CSS to apply to and nothing else. Write just the path of the URL. Don’t include the domain name or query parameters…

If you want the CSS to apply to every page, you should pass DEFAULT for the URL Selector.

Note: Don’t include <style> tags.

Widget solution:

if you don’t want to use the Site Manager interface to add new CSS styles, or need to override the CSS from the Site Manager interface, you can do so entirely on the front end using our Widget API. After you initialize your SiteTran Widget add the


sitetran.css_lang_lookup_override

object which contains language_code to css string key value pairs. For language code, put in the language code of the language which you’re trying to change CSS on, and then pass a string with all your CSS.

Here’s an example:


sitetran.css_lang_lookup_override = {
    "language_code_goes_here” : "div{width:20px; height 50px;} .niceClass{cursor:pointer;}", 
    "fr" : ".classForFrench{display:none;}"
}

Alternative Translation with Selectors

Sometimes you need to translate the same phrase in different ways based on the context. This is powered entirely through SiteTran, and requires no additional work from a developer.

You can select elements based on the element’s tag name (like p, or div), the element’s class, ID, or attribute. 

A good explanation of CSS selectors can be found here.

And examples of all CSS selectors can be found here.

With your Site Manager account, find your phrase in site-phrases-in-page. Click on the 3 vertical dots to the right of the phrase and select “Alternative”. Add your URL selector and your CSS selector. Press save. You will now see that your phrase’s source circle is black, and when you hover over it you will see that it says “Phrase added with alternate translation” (it also has a different phrase_id). Now the phrase’s translation can be changed. When you created the alternative phrase, SiteTran took the old phrase and put it at the bottom of your page so that the phrase and translations will still exist. That phrase doesn’t have any selectors on it, so it will still contain the previous translation.

Note: unfortunately it’s impossible to select individual text nodes within elements using CSS selectors, so if you have multiple text nodes in an element, and you need to translate one of the nodes differently, your best bet is to wrap it in a <span> and give it a unique class, ID, or attribute.

Example Problem:

<div>some text <div>in the middle</div> problematic text </div>

A Possible Solution:

<div>some text <div>in the middle</div><span id="translate-different"> no more problematic text</span></div>

Translation of Dynamic Content (Variable Translation)

For when you have phrases that have dynamic/varying content, such as dates, numbers, or names… A huge time and money saving feature. This is powered entirely through SiteTran, and requires no additional work from a developer.

It’s pretty easy to make this work, it’s a 2 step process. First you need to define the word(s), or number(s), etc. in the phrase that varies. Second, you need to translate the newly created phrase that contains the variables. To define the variables in the phrase, you need to edit the phrase, and select the parts of the phrase that varies. Click on the 3 vertical dots on your phrase in site-phrases-in-page then click the “Edit” button.

Let's take this phrase as an example:

    Hello, Jonathan! Welcome to our site.

In the phrase above, the only word that varies is “Jonathan”. Depending on the site’s visitor, it will show a different name. It would be really hard (not to mention expensive) for a translator to translate that phrase with every single possible name combination… So here’s our solution:

    Hello, Jonathan! Welcome to our site.

Becomes

    Hello, {{welcome_person_name}}! Welcome to our site.

We surrounded the name with 2 curly braces. Just the name. Notice how the exclamation mark and the space are outside of our double curly braces {{variables_go_here}}

After you save your original phrase edit, you will need to translate the phrase as you normally do in the translator interface, but you must include your (untranslated) variable in the translation

Hello, {{welcome_person_name}}! Welcome to our site.

Translated to French becomes:

Bonjour, {{welcome_person_name}}! Bienvenue sur notre site.

SiteTran automatically swaps your variables out of the original phrase on your site and into the translation.

It even works with phrases that have multiple variables. Translating phrases with multiple varying segments is basically the same as above, you just need to surround your {{variables}}.

Let’s say we have the phrase:

Joined: March 10, 2022

And we want to be able to control the position of the variables, because in Spanish, for example, it would be:

 Se unió el 10 de mayo de 2022

Here’s what the edited original phrase would look like:

Joined: {{joined_month_name}} {{joined_month_day}}, {{joined_year}}

The translator would need to input

 Se unió el {{joined_month_day}} de {{joined_month_name}} de {{joined_year}}

Note: It’s nice to leave a comment with the original (unedited) phrase in the translator interface, so that translators can clearly see what the phrase looks like.

Variables work perfectly - almost always. The only time there can be an issue is if your phrase matches some other phrases that it should be matching, such as:

March 2022

Becomes

{{the_month}} 2022

This COULD be problematic if there’s a phrase on your site like:

I was born in 2022

The solution is that the variables are for small divs and also to make more strict regexes. 

The SiteTran Widget would think that “I was born in” is the variable, and it would leave it untranslated.

In instances like that, you will want to add a regular expression to have more explicit matching rules. Contact us and we’ll help you immediately!

Language Codes as Subdirectories

If you have control over your backend so that you can create subdirectories to return static translated pages like those generated by our Static API, or if you’re generating static translated pages another way, SiteTran can keep everything in sync for an optimal SEO solution.

Add your language codes and URLs as "key": "value", pairs respectively to the object variable below.


sitetran.static_url_language_code_lookup

For example, on SiteTran’s homepage, this is what we have.


sitetran.static_url_language_code_lookup = {
    "en":"https://www.example.com/",
    "pt":"https://www.example.com/pt/",
    "de":"https://www.example.com/de/",
    "es":"https://www.example.com/es/"
}

Website Translation Made Easy