Getting Started
Advanced
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!
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.
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:
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.
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:
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.
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:
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:
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 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.
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
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.
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.
If you want to stop the SiteTran widget from updating the hreflangs, add this in to your Widget Snippet.
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.
We’re using
from above to trigger an event on your Google Analytics tracker.
This is for the newest version of Google Analytics (Google Analytics 4)
Note: If you’re still on the older version of GA you should replace the gtag line above with the ga code below.
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.
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.
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.
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:
Next, add these CSS styles to your page.
To return the currently selected language code call:
console.log(sitetran.lang);
Prints "en" if the user's selected language is English.
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.
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.
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.
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…
Let’s say you have some element like a div with a ::before pseudo-element:
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:
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.
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
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:
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>
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!
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.
For example, on SiteTran’s homepage, this is what we have.
