Skip to main content
Website translation

Advanced setup

Follow Advanced setup guide if:
  • You wish to display languages as buttons
  • You wish to hide language selector or translation notice when translating your website
  • You wish to use a custom language selector
  • Your website is already multilingual
Warning
  • To set up Tilde Website Translator, you'll need to access your website's frontend source code to insert the Website Translator widget.
  • You will need JavaScript and CSS knowledge to follow the Advanced setup instructions.

Add new website​

To add new website:

  1. Open Tilde Website translator platform.
  2. Click Set up website translator.
  3. Fill the form:
    • Enter the name of your website.
    • Add your website domain.
    • Select your website's original language.
    • Select languages you want your website to be translated into.
  4. Click Create.
  5. Copy the generated integration code and add it to your website.
Adding subdomains

Important: For subdomains, like https://example.com, https://www.example.com and https://sub.example.com , each needs to be added individually to the configuration.

Tip

Add separate website integrations for Test and Production environments to maintain distinct translations.

add new website 1 Create new integration Create new integration2

Setup language selector​

Configure the default language selector​

The language selector can be displayed as a dropdown or a list of buttons, both of which can be styled with CSS to match your website's design. It automatically loads available languages and initiates translation when a selection is made.

Add an element with class="website-translator" to your page.

<div class="website-translator"></div>

Setting WebsiteTranslator.Options.ui.layout="menu" will display the language selector as a dropdown menu. This is the default appearance.

Website Translator menu

Customize its appearance further with CSS styling.

To customize the appearance of the language button, use the CSS selectors .website-translator .website-translator-select .selected-item and .website-translator .website-translator-select .selected-item .menu-text.

Example

Website Translator menu styled with CSS

/example-style.css
.website-translator .website-translator-select .selected-item
{
background:#efeff9!important;
text-transform: uppercase;
border:1px solid purple!important;
color:purple!important;
text-align:left!impotrant;
font-size:12px!important;
height:30px!important;
}

.website-translator .website-translator-select .selected-item .menu-text
{
text-align:left!important;
}

To customize the appearance of the language dropdown menu, use the CSS selectors .website-translator .option and .website-translator .option.selected.

Example

Website Translator menu styled with CSS

/example-style.css
.website-translator .option
{
text-transform:uppercase;
font-family:sans-serif;
color:navy!important;
font-size:12px!important;
padding:0 10px 0 10px;
line-height:30px!important;
}

.website-translator .option.selected
{
color:purple!important;
background-color:#efeff9!important;
}

List of buttons​

The Website Translator's language selector can be displayed as a list of buttons by setting WebsiteTranslator.Options.ui.layout="list",

Website Translator button list

To customize the appearance of the language buttons, use the CSS selectors .website-translator button and .website-translator button.active.

Example 1

Website Translator menu styled with CSS

/example-style.css
.website-translator button
{
background:white!important;
color:purple!important;
border:1px solid purple!important;
text-transform:uppercase!important;
padding:.375rem 1.5rem;
min-height:35px!important;
border-radius:5px;
}
 
.website-translator button.active
{
background:#efeff9!important;
}
Example 2

Website Translator menu styled with CSS

/example-style.css
.website-translator button
{
background:transparent!important;
color:purple!important;
border:none!important;
text-transform:uppercase!important;
padding:.375rem 0.5rem;
text-decoration:underline!important;
}

Hidden​

Setting WebsiteTranslator.Options.ui.layout=null will hide the default language selector, but keep the translation progress bar visible.

Change how the languages are displayed in menu​

The menu languages can be displayed in their native names or translated into the currently selected language.

To display the native language names set:

WebsiteTranslator.Options.ui.showLanguagesInNativeLanguage=true;

menu with native language names

To display the translated language names set:

WebsiteTranslator.Options.ui.showLanguagesInNativeLanguage=false;

menu with translated language names

Use a custom language selector​

Initialize​

WebsiteTranslator.Initialize() - initializes the Website Translator and fetches the available translation engines. If a "lang" parameter is included in the URL, the content will be translated into the specified language. If no "lang" parameter is present in the URL, the content will be translated into the previously used target language.

Normally, WebsiteTranslator.Initialize() should be called once. Subsequent calls will reinitialize the language selector. Consider this if your website's DOM (including the language selector) changes dynamically.

// Configure your personal access key
WebsiteTranslator.Options.api.clientId = 'x-xxxxxxxx-xxxx-xx'

// Initialize
await WebsiteTranslator.Initialize()

Start translation and wait until finished​

Translate page to specific language. If you call Translate even if previous translation is not finished, it will cancel current translation, restore web page in original language and start new translation in specified language - same as to issue Cancel and restore translation and start new translation with Translate

// You can call next translation even when previous is not finished
WebsiteTranslator.Translate("lt").then(function(translationFinish){
   // You can wait when page is translated
   Promise.all(translationFinish).then(function(){
      console.log("Translation is complete")
   })
})

When page is translated, web page url lang parameter is changed to translated language or added if it does not exist

For example: https://example.com/ -> https://example.com/?lang=lt If page translation is restored, then lang parameter is set to source language.

Cancel translation​

Restores page in Source language

WebsiteTranslator.CancelAndRestore()

Translate with given language​

WebsiteTranslator.Translate("hu")

Get current language​

Returns language code for web page. Value can be also SourceLanguage. This can be used to programmatically read web page language.

WebsiteTranslator.CurrentLanguage

Get available languages and machine translation systems​

Returns available languages and systems. Can be used to create custom language menu or language selection using JavaScript translation API.

WebsiteTranslator.GetTargetLanguages()

Customize translation progress bar​

A translation progress bar appears while the page is being translated. Once complete, a link to restore the original language becomes available. By default, the progress bar is displayed in the target language.

Website translation progress bar

To display the progress bar in the website's original language, set WebsiteTranslator.Options.ui.translate = "source".

Website translation progress bar source

Change display position​

The translation progress bar can be positioned at the top or bottom of the page. Set WebsiteTranslator.Options.ui.toolbarPosition="top" or WebsiteTranslator.Options.ui.toolbarPosition="bottom" to adjust its location.

Change appearance​

You can customize its appearance further using CSS.

To customize the appearance of the translation progress bar, use the CSS selectors .website-translator-toolbar .dashboard, .website-translator-toolbar a and .website-translator-toolbar .progress-bar.

Example

Website Translator progress styled with CSS

/example-style.css
.website-translator-toolbar .dashboard
{
background:#efeff9!important;
text-transform:uppercase!important;
font-family:sans-serif!important;
color:navy!important;
}

.website-translator-toolbar a
{
color:purple!important;
}

.website-translator-toolbar .progress-bar
{
background-color:purple!important;
}

Hide translation bar​

To hide the translation bar, add the WebsiteTranslator.Options.ui.headless=true option to the configuration. This will prevent visitors from seeing the translation progress bar and the option to restore the original language.

Original text popup​

Hovering over a translated text displays a tooltip showing the original text.

original text popup

To adjust the tooltip display delay, set the WebsiteTranslator.Options.ui.tooltipShowDelay value in milliseconds.

WebsiteTranslator.Options.ui.tooltipShowDelay = 300;

To hide the popup, set:

WebsiteTranslator.Options.ui.showPopup=false;

To customize the appearance of the popup, use the CSS selectors .website-translator-tooltip and .website-translator-tooltip .original-label.

Example

unsyled popup

popup styled with css

/example-style.css
 .website-translator-tooltip
 {
 background:#efeff9!important;
 color:#240032!important;
 border-radius:10px!important;
 }
 
 .website-translator-tooltip .original-label
 {
 color: #240032!important;
 font-size:16px!important;
 text-transform: uppercase;
 margin-bottom:15px!important;
 }

Integrate in an already multilingual website​

Expand your website's language reach with machine translation.

To prevent machine translation of languages already available on your site, specify these languages in the thirdPartyTranslationLanguages option.

WebsiteTranslator.Options.translation.thirdPartyTranslationLanguages = ['de', 'fr','it'];

Full example:

<!DOCTYPE html>
<head>
   <script type="text/javascript" src="https://unpkg.com/@tilde-nlp/website-translator/dist/widget.js"></script></head>
<body>
    <div class="website-translator"></div>
    <p>This is an example</p> 
</body>
<footer>
    <script>
      // 👇 Change XXXXXXXXXXX to your Client-ID
      WebsiteTranslator.Options.api.clientId = "XXXXXXXXXXX";
      WebsiteTranslator.Options.api.url = "https://services.tilde.com/service/website-translation";
       // Specify languages already available on the website
        var thirdPartyLanguages = ["de", "fr", "sv"];
        WebsiteTranslator.Options.translation.thirdPartyTranslationLanguages = thirdPartyLanguages;
       // Set the language of the currently rendered webpage. Example demonstrates how to obtain the language code from the document's lang attribute.
        WebsiteTranslator.Options.currentLanguage = document.documentElement.getAttribute('lang')
        // Implement custom logic to use pre-existing translations instead of machine translation
        WebsiteTranslator.Options.translation.onLanguageSelected = function (selectedLanguage) {
            return new Promise(function (resolve) {
                let translationHandled = false
                console.info('Language selected: ' + selectedLanguage)
                // Determine if a custom action is required to access pre-existing translations, bypassing machine translation.
                if (WebsiteTranslator.Options.translation.thirdPartyTranslationLanguages.includes(selectedLanguage)) {
                    translationHandled = true
                    if (WebsiteTranslator.Options.currentLanguage !== selectedLanguage) {
                        console.info('Redirecting to embedded language version of the page')
                        // Add your own logic on how to transform URL of current language to URL of selected target language
                        // or other necessary actions.
                        // Note. This replacement logic is to transform http://example.com/page_en.html to http://example.com/page_de.html
                        // and vice versa.
                        window.location.href = window.location.href.replace(/page_\w+/, 'page_' + selectedLanguage)
                        // For example, for page https://example.com/en/news to transform to https://example.com/de/news
                        // window.location.href = window.location.href.replace(/example.com\/\w+/, "/example.com/" + selectedLanguage)
                   }
                }
                resolve(translationHandled)
            })
        }
        // Initialize and run translations
        WebsiteTranslator.Initialize()
    </script>
</footer>
</html>

Full configuration options list​

Complete list of plugin configuration options available for JavaScript customization.

Debug mode​

WebsiteTranslator.Options.debug​

  • Type: Boolean
  • Default: false

Enables verbose logging in console.

Language options​

The widget automatically detects the target language if specified in the URL's language parameter.

It supports ISO 639-1 language codes with optional ISO 3166-1 alpha-2 country codes. If a language-country combination isn't found, the widget attempts to match the language without the country code.

WebsiteTranslator.Options.currentLanguage​

  • Type: String
  • Default: null

Determines the current language of the webpage (if pre-translated). When the current language differs from the source language and a new translation is selected, the Website Translator attempts to fetch the page in the chosen language by invoking translation.onLanguageSelected(language).

Translation API options​

WebsiteTranslator.Options.api.clientId​

  • Type: String
  • Default: null

A valid authorization key is required for Website Translator to access the translation API.

Translation options​

WebsiteTranslator.Options.translation.autoTranslate​

  • Type: Boolean
  • Default: true

Remembers the last translated language for automatic translation on subsequent page loads. However, if the URL contains a 'lang' parameter, that language takes precedence. Otherwise, the previously saved language is used.

WebsiteTranslator.Options.translation.translateOnlyAllowedTags​

  • Type: Boolean
  • Default: false

Translate only elements and their child content marked with the translate="yes" attribute.

WebsiteTranslator.Options.translation.translateAttributes​

  • Type: Boolean
  • Default: true

Translate HTML attributes.

WebsiteTranslator.Options.translation.onLanguageSelected​

Type: Function Default: () => Promise.resolve(false)

Custom actions for language selection. If implemented, this function should return true to initiate Website Translator translation, or false to bypass it.

WebsiteTranslator.Options.translation.thirdPartyTranslationLanguages​

  • Type: Array<string>
  • Default: []

Prevent machine translation of languages already available on your website.

UI options​

WebsiteTranslator.Options.ui.headless​

  • Type: Boolean
  • Default: false

Hide translation progress bar.

WebsiteTranslator.Options.ui.showPopup​

  • Type: Boolean = Default: true

Display or hide the original text popup on hover.

WebsiteTranslator.Options.ui.tooltipShowDelay​

  • Type: Number
  • Default: 500

Adjust the original text tooltip display delay, set the WebsiteTranslator.Options.ui.tooltipShowDelay value in milliseconds.

WebsiteTranslator.Options.ui.toolbarPosition​

  • Type: String
  • Default: bottom

Translation toolbar position:

"top" - Show translation toolbar at the top of the page "bottom" - Show translation toolbar at the bottom of the page

WebsiteTranslator.Options.ui.mainContentElement​

  • Type: HTMLElement
  • Default: null

The main HTML element containing all scrollable content on the webpage.

WebsiteTranslator.Options.ui.showLanguagesInNativeLanguage​

  • Type: Boolean
  • Default: false

Display languages in their native names within the language selector.

WebsiteTranslator.Options.ui.translate​

  • Type: String
  • Default: source

Translate UI, values can be:

  • "source" - Show UI in source language
  • "target" - Show UI in target language

WebsiteTranslator.Options.ui.showTranslationControls​

  • Type: Boolean
  • Default: true

Display or hide the 'restore' translation button in the toolbar.

WebsiteTranslator.Options.ui.layout​

  • Type: String
  • Default: menu

Configure the language selector display mode. Options include:

  • menu: Show available languages in a dropdown menu.
  • list: Display available languages as a list.
  • null: Hide the language selector.

SEO options​

WebsiteTranslator.Options.seo.setCanonicalUrl​

  • Type: Boolean
  • Default: true

The Website Translator automatically generates canonical URLs by appending the ?lang=x parameter to the URL for each translated page.

By default, this option is enabled (true). For instance, a page translated into Estonian will have the following canonical URL:

<link rel="canonical" href="https://example.com?lang=et" wt-attr-original-url="https://example.com/">

To disable this feature, set WebsiteTranslator.Options.seo.setCanonicalUrl=false. When disabled, the canonical URL will be:

<link rel="canonical" href="https://example.com">