Skip to main content
Website translation

Advanced setup

This section provides detailed instructions for customizing the Website Translator beyond the basic configuration. If you need more control over the appearance, behavior, or integration of the translator, such as changing the look of the language switcher or handling existing multilingual content, this guide is for you.

You will learn:

Warning
  • You need access to your website's frontend source code to insert the Website Translator widget.
  • JavaScript and CSS knowledge are required for these advanced steps.

Step 1: Add new website​

Adding your website generates an integration code snippet, which allows the translator tool to function on your site.

To add new website:

  1. Open Tilde Website Translator platform.
  2. Click the Set up website translator button to begin the configuration process.
  3. Fill the form:
    • Enter a recognizable name for your website (e.g., "My Company Blog", "Main Corporate Site").
    • Add your website domain (e.g., https://www.example.com).
    • Select your website's original language.
    • Select the languages you want your website to be translated into.
  4. Click Create.
  5. Copy the generated integration code. You will need to add this snippet to your website's HTML source code to enable the translator.

Once the code is integrated correctly, the website translator will become active on your site according to your configuration.

Adding subdomains

Important: Each subdomain requires its own separate configuration entry. For example, https://example.com, https://www.example.com, and https://sub.example.com must each be added individually.

Tip

Consider adding separate website integrations for your Test and Production environments. This allows you to manage translations and test configurations independently without affecting your live website.

Figure 1. Start screen – Website Translator setup.
Figure 1. Start screen – Website Translator setup.
Figure 2. Filling out the website setup form.
Figure 2. Filling out the website setup form.
Figure 3. Generated code for website integration
Figure 3. Generated code for website integration

Step 2: Setup language selector​

Option A: Configure the default language selector​

The default language selector can be a dropdown or a list of buttons. Both can be styled using CSS. It automatically loads languages and handles translation initiation.

Add an element with class="website-translator" where you want the selector to appear.

<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.

Figure 4: Default language selector is a dropdown menu.
Figure 4: Default language selector is a dropdown 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
Example CSS styling applied to language switcher
Example CSS styling applied to language switcher
/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 dropdown styled with CSS
Website Translator dropdown 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;
}

Hide the language selector​

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​

Configure whether languages in the menu appear in their native names or translated into the current language.

To display native language names:

WebsiteTranslator.Options.ui.showLanguagesInNativeLanguage=true;
Figure 5. Menu with native language names.
Figure 5. Menu with native language names.

Option B: Use a custom language selector​

Use the JavaScript API to control translation with your own UI elements.

Initialize​

WebsiteTranslator.Initialize(): Initializes the translator and fetches available engines. Translates based on the URL "lang" parameter or the last used language. Call once on page load, or again if the DOM (including your custom 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​

WebsiteTranslator.Translate(languageCode): Translates the page to the specified language. Returns a promise that resolves when translation is complete. Calling Translate again cancels any ongoing translation, restores the original, and starts the new one. Updates the URL lang parameter.

// 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")
   })
})

The URL lang parameter is added or updated (e.g., https://example.com/ becomes https://example.com/?lang=lt). Restoring removes the parameter or sets it to the source language.

Cancel translation​

WebsiteTranslator.CancelAndRestore(): Restores the page to its original source language.

WebsiteTranslator.CancelAndRestore()

Translate with given language​

WebsiteTranslator.Translate(languageCode): Initiates translation to the specified language code (e.g., "hu" for Hungarian).

WebsiteTranslator.Translate("hu")

Get current language​

WebsiteTranslator.CurrentLanguage: Returns the language code of the currently displayed page (can be the source language code). Useful for programmatically checking the language state.

WebsiteTranslator.CurrentLanguage

Get available languages and machine translation systems​

WebsiteTranslator.GetTargetLanguages(): Returns available target languages and translation systems. Use this to populate a custom language menu.

WebsiteTranslator.GetTargetLanguages()

Step 3: Customize translation progress bar​

The progress bar appears during translation and shows a link to restore the original language afterward. By default, its text is in the target language.

Figure 6. Website translator progress bar in target language
Figure 6. Website translator progress bar in target language

To show the progress bar text in the website's original language: Set WebsiteTranslator.Options.ui.translate = "source".

Figure 7. Website translator progress bar in source language
Figure 7. Website translator progress bar in source language

Change display position​

Position the bar at the top or bottom.

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".

Change appearance​

Customize the progress bar using CSS.

Use selectors: .website-translator-toolbar .dashboard, .website-translator-toolbar a and .website-translator-toolbar .progress-bar.

Example
Website Translator progress styled with CSS
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​

Set WebsiteTranslator.Options.ui.headless=true to completely hide the translation progress bar and the restore link.

Step 4: Customize original text popup​

Hovering over translated text reveals a tooltip with the original text.

Figure 8. Original text popup
Figure 8. Original text popup

Adjust the hover delay (in milliseconds):

WebsiteTranslator.Options.ui.tooltipShowDelay = 300; // Default is 500ms

Hide the popup entirely:

WebsiteTranslator.Options.ui.showPopup=false;

Customize the popup's appearance using CSS selectors .website-translator-tooltip and .website-translator-tooltip .original-label.

Example
Default popup
Default popup
Popup styled with CSS
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​

Use machine translation to supplement your existing translated content.

Specify languages already handled by your website in thirdPartyTranslationLanguages to prevent machine translation for those languages.

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

Use the onLanguageSelected callback to implement custom logic (like redirects) when a user selects a language you already provide.

Full example​

This example shows how to redirect users to existing translated pages (/page_de.html, /page_fr.html, /page_sv.html) instead of using machine translation for German, French, and Swedish.

<!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://traduzzjoni.mt/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​

Reference list of all JavaScript configuration options.

Debug mode​

WebsiteTranslator.Options.debug​

  • Type: Boolean
  • Default: false
  • Enables detailed console logging.

Language options​

The widget detects target language from the URL parameter (?lang=xx or ?lang=xx-YY). It supports ISO 639-1 language codes, optionally combined with ISO 3166-1 alpha-2 country codes. If a specific language-country combination isn't available, it falls back to the base language.

WebsiteTranslator.Options.currentLanguage​

  • Type: String
  • Default: null
  • Specifies the language of the currently rendered page, especially if it's already translated by means other than the widget. If set and different from the source language, selecting a new language triggers translation.onLanguageSelected(language).

Translation API options​

WebsiteTranslator.Options.api.clientId​

  • Type: String
  • Default: null
  • Required. Your unique authorization key for accessing the translation API.

Translation options​

WebsiteTranslator.Options.translation.autoTranslate​

  • Type: Boolean
  • Default: true
  • If true, remembers the last selected target language and automatically translates on subsequent visits. The URL lang parameter takes precedence.

WebsiteTranslator.Options.translation.translateOnlyAllowedTags​

  • Type: Boolean
  • Default: false
  • If true, only translates elements (and their children) explicitly marked with the translate="yes" attribute.

WebsiteTranslator.Options.translation.translateAttributes​

  • Type: Boolean
  • Default: true
  • If true, translates content within HTML attributes (e.g., title, alt).

WebsiteTranslator.Options.translation.onLanguageSelected​

  • Type: Function
  • Default: () => Promise.resolve(false)
  • A callback function executed when a language is selected. Return true if you handled the language change (e.g., via redirect) and want to prevent the widget's default translation. Return false to allow the widget to proceed with machine translation.

WebsiteTranslator.Options.translation.thirdPartyTranslationLanguages​

  • Type: Array<string>
  • Default: []
  • An array of language codes (e.g., ['de', 'fr']) that are already handled by your website. The widget will not machine translate into these languages; instead, onLanguageSelected will be triggered.

UI options​

WebsiteTranslator.Options.ui.headless​

  • Type: Boolean
  • Default: false
  • If true, hides the translation progress bar entirely.

WebsiteTranslator.Options.ui.showPopup​

  • Type: Boolean = Default: true
  • If true, shows the original text in a tooltip when hovering over translated content. Set to false to disable.

WebsiteTranslator.Options.ui.tooltipShowDelay​

  • Type: Number
  • Default: 500
  • Delay in milliseconds before the original text tooltip appears on hover.

WebsiteTranslator.Options.ui.toolbarPosition​

  • Type: String
  • Default: bottom
  • Position of the translation progress bar. Accepts "top" or "bottom".

WebsiteTranslator.Options.ui.mainContentElement​

  • Type: HTMLElement
  • Default: null
  • Specify the main HTML element containing the page's scrollable content, if needed for accurate positioning or behavior.

WebsiteTranslator.Options.ui.showLanguagesInNativeLanguage​

  • Type: Boolean
  • Default: false
  • If true, displays language names in the selector using their native spellings (e.g., Deutsch, Français). If false, names are translated into the current language.

WebsiteTranslator.Options.ui.translate​

  • Type: String
  • Default: source
  • Language for the UI elements (progress bar text). Accepts "source" (use website's original language) or "target" (use the selected translation language).

WebsiteTranslator.Options.ui.showTranslationControls​

  • Type: Boolean
  • Default: true
  • If true, shows the 'restore original' link/button in the translation toolbar. Set to false to hide it.

WebsiteTranslator.Options.ui.layout​

  • Type: String
  • Default: menu
  • Controls the default language selector's appearance:
    • "menu": Dropdown menu.
    • "list": List of buttons.
    • null: Hides the default selector (useful if building a custom one).

SEO options​

WebsiteTranslator.Options.seo.setCanonicalUrl​

  • Type: Boolean
  • Default: true
  • If true, the widget adds a canonical link tag pointing to the URL with the appropriate ?lang=x parameter for each machine-translated version. Example for Estonian:
<link rel="canonical" href="https://example.com?lang=et" wt-attr-original-url="https://example.com/">
  • If false, the canonical link tag will point to the original page URL without the lang parameter:

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

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