Tilde Website Translator

Quickly scale up from one language to a dozen! No coding, manual translation, or duplicated webpages! Simply select the target languages and Tilde’s Website Translator will instantly translate the content. For quality control, you can review and edit translations with a visual editor.

Features

• Text Editor Manage your translations with text editor which will allow you to quickly post-edit machine translations in real-time.
• Visual Editor The visual editor gives you complete quality control and allows you to edit and manage your translations effortlessly directly inside your website's design and structure!
• SEO indexing Search engines will index machine translated pages and your customers will be able to find them in their native language. This includes canonical URL metatag update of the page together with references to all available machine translated versions of the same page.
• SEO editing Some keywords and headlines may need extra special attention and adaptation for each market. With the SEO text editor, you will be able to easily edit all the translated metadata information to make your content attractive to search engines.
• Integrations Tilde Website Translator is compatible with any kind of website including WordPress, Shopify, Drupal, JavaScript, Joomla, HTML.

Table of contents:

• Quickstart
  • Before you begin
  • Installing the client library
  • Translatable and untranslatable content
  • Examples
• Usage
  • Integrate using the default language selector
  • Custom integration
    • Initialization
    • Start translation and wait until finished
    • Cancel translation
    • Translate with given language
    • Get current language
  • Adding MT to already multilingual website
• Options

Quickstart

Before you begin

To use the Tilde Website Translator you will need:

1. an active TildeMT subscription. You can request a free trial.
2. a Client-ID for authentication. You can generate the Client-ID and the basic configuration code on the TildeMT Platform.

Installing the client library

npm i @tilde-nlp/web-translate-widget

Translatable and untranslatable content

All elements are translatable by default, but you may set elements as non-translatable by setting the value of translate attribute to no. The same applies to language attributes. All elements are translatable unless the value of lang attribute is not equal to source language configuration in the options (TildeMTTranslationPlugin.Options.sourceLanguage). Translate attribute affects localization and translation of element's attributes (href, title, label, etc.)

<div translate="yes">
   You can define elements to translate with translate attribute
   <div translate="no">
      Excluded elements can be child of translatable elements
      <div translate="yes">
            Multiple levels of translate attribute can be processed
            <div translate="no">
               This element will not be translated because of translate
               attribute
            </div>
      </div>
   </div>
</div>

Examples

Full code examples can be found in the npm package's './examples' folder.

• examples/Multi pretranslated lang example - Full example of pretranslated website integration

  • page_de.html - Page in German
  • page_en.html - Page in English. Used to translate page in other languages.
  • page_fr.html - Page in French. This is configured to be already pretranslated page.

• examples/example1.html - Example of custom language switching through translator API

• examples/example2.html - Example of minimal pretranslated website integration

Usage

Include a reference to the Tilde Website Translator

<script src="/dist/widget.js"></script>

Tilde Website Translator can be integrated using the default language selector or a custom solution. Both options support adding third party languages. Try the default selector for out-of-the-box solution. Check Options for a full list of options. Check the npm package's /examples folder for more implementation examples.

Integrate using the default language selector

Default language selector can be displayed as a dropdown or a list of buttons that can be styled by css to further match your style. It will load the available languages automatically and start translation on making a selection.

<html lang="en">
<head>
   <!-- Enter the correct source code path -->
   <script src="/dist/widget.js"></script>
</head>
<body>
   <div class="tildemt-widget"></div>
   <!-- This will be translated  -->
   <p>This will be translated</p>

   <!-- This will not be translated  -->
   <p translate="no">This will not be translated</p>

   <!-- This will not be translated  -->
   <p lang='ja'>これを訳して</p>
</body>
<footer>
   <script>
      // Configure

      // Change XXXXXXXXXXX to your Client-ID
      TildeMTTranslationPlugin.Options.api.clientId = "XXXXXXXXXXX";

      TildeMTTranslationPlugin.Options.ui.toolbarPosition = "top";

      // Display the language selector as a dropdown:
      //    menu - "menu"
      //    list of buttons - "list"
      TildeMTTranslationPlugin.Options.ui.layout = "menu";

      // Set UI language the administrator will see,
      // by default it will be displayed in the language you are translating into
      TildeMTTranslationPlugin.Options.ui.translation.adminLanguage="en";

      // Display UI in the language your visitors are translating into:
      //    target language - "target",
      //    the original language - "source"
      TildeMTTranslationPlugin.Options.ui.translate = "target";

      // Allow your visitors to suggest translations:
      //    allow - "true"
      //    disallow - "false"
      TildeMTTranslationPlugin.Options.ui.suggestions.allowAnyoneToSuggest=false;

      // Set the source language
      TildeMTTranslationPlugin.Options.sourceLanguage = "en";

      TildeMTTranslationPlugin.Initialize()
   </script>
</footer>
</html>

Custom integration

Initialization

Initializes Tilde Website Translator - language select, fetches available MT systems. If there is lang parameter in URL, it will translate to language that is provided in parameter value. If there is no lang parameter and current source language is the same as last time when Tilde Website Translator was used, then it will translate to last translated target language.

Normally Initialize should be issued only once, but further calls will reinitialize language select. Consider this when your page changes DOM including language menu.

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

// Source language that will be used to generate machine translation
TildeMTTranslationPlugin.Options.sourceLanguage = "en"

// Initialize
await TildeMTTranslationPlugin.Initialize()

Translation can be started or canceled through JS. This is especially needed if default language selection is not used.

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

TildeMTTranslationPlugin.CancelAndRestore()

Translate with given language

TildeMTTranslationPlugin.Translate("lv")

Translate with specific system for given language

TildeMTTranslationPlugin.Translate("lv", "smt-xxxxxxxx-xxxx-xx")

Get current language

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

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

TildeMTTranslationPlugin.GetTargetLanguages()

Adding MT to already multilingual website

Broaden the language coverage with machine translation for an already multilingual website that has content in two or more languages.

Step #1: Additionally, to the initial configuration you have to decide which of the pre-existing language versions of the website will be the source for the translation. It is going be used to generate the machine translation in additional languages. Set the sourceLanguage option to the selected language. Check what language directions your subscription offers to make the decision.

TildeMTTranslationPlugin.Options.sourceLanguage = "en"

Step #2: Specify the languages of your webpage that already have the translation embedded and machine translation should not be carried out. Configure the thirdPartyTranslationLanguages option if we have German and French versions of the English pages, for example.

TildeMTTranslationPlugin.Options
  .translation.thirdPartyTranslationLanguages = ['de', 'fr']

Step #3: Set the language of the webpage that is currently rendered (English, German, or French in this example). Use your own logic to detect this.

TildeMTTranslationPlugin.Options
  .currentLanguage = document.documentElement.getAttribute('lang')
console.log('Current lang: ' + TildeMTTranslationPlugin.Options.currentLanguage)

Step #4: Implement a JavaScript action to perform when the user changes language to one of the embedded languages (German or French in this example) instead of machine translation.

function onLanguageSelectedHandler(language) {
  console.info('Language selected: ' + language)
  return new Promise(function (resolve) {
    var translationHandled = false

    // Check if custom action must be perform to open a page with embedded
    // translation bypassing MT process
    if (TildeMTTranslationPlugin.Options
          .translation.thirdPartyTranslationLanguages.includes(language)) {
      translationHandled = true

      if (TildeMTTranslationPlugin.Options.currentLanguage !== language) {
        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 transform https://example.com/en/news to
        // https://example.com/de/news and vice versa.
        window.location.href =
          window.location.href.replace(/\.com\/\w+/, "/.com/" + language)
      }
    }

    resolve(translationHandled)
  })
}

TildeMTTranslationPlugin.Initialize()
TildeMTTranslationPlugin.Options.
  translation.onLanguageSelected = onLanguageSelectedHandler;

More elaborate example is available in npm package ./examples/Multi pretranslated lang example/ directory.

Options

Tilde Website Translator determines automatically target language if webpage uses lang parameter in URL query.

Tilde Website Translator supports ISO 639-1 language codes with optional ISO 3166-1 alpha-2 country codes. If language is not found with specified country code, then Tilde Website Translator checks if language without country code is available.

TildeMTTranslationPlugin.Options.sourceLanguage

• Type: String

• Default: en

  Source language for machine translation

TildeMTTranslationPlugin.Options.currentLanguage

• Type: String

• Default: null

  Current web page language (if the web page is already pre-translated). The language in which the website has been translated. When currentLanguage is not equal to sourceLanguage, selecting language to translate, Tilde Website Translator will try to get page in sourceLanguage by calling translation.onLanguageSelected(sourceLanguage)

TildeMTTranslationPlugin.Options.debug

• Type: Boolean

• Default: false

  Enable verbose logging in console

Translation API options

TildeMTTranslationPlugin.Options.api.clientId

• Type: String

• Default: null

  Authorization key which allows Tilde Website Translator to access translation API Required

TildeMTTranslationPlugin.Options.api.services.Translation

• Type: String

• Default: https://letsmt.eu/ws/Service.svc/json

  Translation service Uri

TildeMTTranslationPlugin.Options.api.services.Authentication

• Type: String

• Default: https://readymt.tilde.com/Account/Token

  Authentication service Uri

Translation options

TildeMTTranslationPlugin.Options.translation.autoTranslate

• Type: Boolean

• Default: true

  Save last translation target language and on next page load, automatically translate to it.

  if browser url contains lang parameter in url, Tilde Website Translator will use it for translation. Otherwise if lang parameter is not available, saved language will be used.

TildeMTTranslationPlugin.Options.translation.systems

• Type: Object

• Default: null

  Limit translation systems by defining systems and their target languages as object Default will show all available systems. Limiting systems can be useful, because there may be multiple systems with different domains for single language code.

  {
     "smt-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx": "lv",
     "smt-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx": "ru"
  }

TildeMTTranslationPlugin.Options.translation.translateOnlyAllowedTags

• Type: Boolean

• Default: false

  Translate only tags and their children which have translate="yes" attribute

TildeMTTranslationPlugin.Options.translation.translateAttributes

• Type: Boolean

• Default: true

  Translate HTML attributes

TildeMTTranslationPlugin.Options.translation.onLanguageSelected

• Type: Function

• Default: () => Promise.resolve(false)

  Custom actions on selecting languages. This function if implemented should return Boolean -> true when Language must be Translated with Tilde Website Translator, false otherwise

TildeMTTranslationPlugin.Options.translation.thirdPartyTranslationLanguages

• Type: Array<string>

• Default: []

  Define languages which are supposed to be translated with third party

TildeMTTranslationPlugin.Options.translation.filterSystemsByAppID

• Type: Boolean

• Default: false

  Filter systems by app id to show only systems

UI options

TildeMTTranslationPlugin.Options.ui.headless

• Type: Boolean

• Default: false

  Hide MT toolbar with translation progress.

TildeMTTranslationPlugin.Options.ui.translation.adminLanguage

• Type: String

• Default: null

• Example: en

  Language code in which plugin interface is shown when user is signed in WTW

TildeMTTranslationPlugin.Options.ui.suggestions.allowAnyoneToSuggest

• Type: Boolean

• Default: false

  Show option to suggest translation for unauthorized users

TildeMTTranslationPlugin.Options.ui.suggestions.automaticPreview

• Type: Boolean

• Default: true

  Automatically preview suggestion changes in web page when suggestion is added.

TildeMTTranslationPlugin.Options.ui.tooltipShowDelay

• Type: Number

• Default: 500

  How much time to wait after user is started to hover translation to show suggestion popup (in ms)

TildeMTTranslationPlugin.Options.ui.toolbarPosition

• Type: String

• Default: bottom

  Where toolbar is positioned. Values can be:

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

TildeMTTranslationPlugin.Options.ui.mainContentElement

• Type: HTMLElement

• Default: null

  Main container HTMLElement for web page that contains all scrollable content

TildeMTTranslationPlugin.Options.ui.alwaysShowOriginalTextInPopup

• Type: Boolean

• Default: false

  Show original text even if public suggestions are set to false

TildeMTTranslationPlugin.Options.ui.showPopupTranslationProvider

• Type: Boolean

• Default: true

  Show notification about what service is providing translation

TildeMTTranslationPlugin.Options.ui.showPopup

• Type: Boolean

• Default: true

  Show or hide translation popup Also when disabled, highlight for translated sentences won't be visible.

TildeMTTranslationPlugin.Options.ui.showLanguagesInNativeLanguage

• Type: Boolean

• Default: false

  Show languages in native language for example in Language Menu

TildeMTTranslationPlugin.Options.ui.showSignInLink

• Type: Boolean

• Default: true

  Show sign in link for WTW

TildeMTTranslationPlugin.Options.ui.translate

• Type: String

• Default: source

  Translate UI, values can be:

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

TildeMTTranslationPlugin.Options.ui.showTranslationControls

• Type: Boolean

• Default: true

  Show or hide "restore" and "cancel" translation buttons on UI

TildeMTTranslationPlugin.Options.ui.layout

• Type: String

• Default: menu

  Change display mode of the language selection in UI, values can be:

  • "menu" - Show available languages in select
  • "list" - Show available languages as list items
  • null - Hide language menu If you wish to add more functionality, please consider use your own language menu?

You can find all development options in npm package ./src/js/interfaces/IPluginOptions.ts

Browser support

| Edge | Firefox | Chrome | Safari | Opera | | --------- | --------- | --- | --- | --- | | 14+ | 52+ | 51+ | 10+ | 38+ |

Edge Legacy and Internet Explorer browsers are not supported.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Current

Fixed

• Native language name for Norwegian Bokmål

v6.1.20 - 2023-03-22

Fixed

• Url localization fixes

Changed

• Implemented translation of area-* attributes

v6.1.18 - 2023-1-30

Changed

• Added api error retry timeout and request timeouts
• SEO: Fixed canonical URL processing if canonical url already exists

v6.1.15 - 2023-1-3

Changed

• Changed way that page is translated and added feature to translate only visible elements to speed up translation.
• Optimized caching even more
• Localized Ukrainian menu languages

v5.7.0 - 2022-12-8

Changed

• Localisation improovements of Ukrainian language

v5.4.0 - 2022-11-28

Changed

• Added translation caching inside Website translator for faster translations in same page

v5.3.10 - 2022-11-1

Changed

• Changed package.json encoding from UTF-8 with BOM to UTF-8

v5.3.8 - 2022-10-13

Changed

• Improoved dynamic translation for textual elements
• Fixed translation display of page title

Added

• Examples of how to asynchronous initialize website translator

v5.2.0 - 2022-08-1

Changed

• Improved serialization of HTML text content to better support XML translation API. Some suggestions may be not used due to serialization changes. This affects texts where named HTML entities or other non-XML suitable symbols are used.
• Dynamic translation improved to better process DOM elements that disapear from DOM.

v5.1.11 - 2022-06-22

Changed

• Enabled ui popups for authenticated users

v5.1.10 - 2022-06-21

Changed

• Fixed built-in language menu when used inside html forms

v5.1.9 - 2022-04-7

Changed

• Fixed internal intialization of language menus

v5.1.7 - 2022-03-31

Changed

• Fixed dynamic translation boundaries using translate attribute
• Readme improovements
• Fixed broken GetTargetLanguages api
• Add info in readme about GetTargetLanguages API

v5.1.2 - 2022-03-23

Changed

• Fixed language localization in list layout. Now Language buttons are localized the same as in menu layout.

v5.0.17 - 2022-03-16

Changed

• Updated dependencies

v5.0.16 - 2022-03-10

Changed

• Translation suggestions tag editing support to increase customization of suggested text placement around HTML tags.

Fixed

• When page does not contain language attributes, assume its correct one when watching dynamic content of page.

v4.3.2 - 2022-01-10

Added

• Information about supported browsers
• Instructions about integration in multilingual site "Adding MT to already multilingual website"
• Added info about url language parameter
• Added to ability to detect new HTML elements when they are added to DOM and translate them.

Changed

• Update description about SEO and non-translatable elements
• Localized de, fi lt, pl, sv languages

v4.2.2 - 2021-10-27

Added

• Instructions about integration in multilingual site "Adding MT to already multilingual website"

Changed

• Update description about SEO and non-translatable elements

v4.2.1 - 2021-09-17

Changed

• Localized more languages

v4.2.1 - 2021-09-17

Changed

• Fixed iframe translation due to element reordering.

v4.2.0 - 2021-09-15

Added

• Add option to configure in headless mode
• Add more info about autotranslation and lang parameter

v4.1.4 - 2021-08-20

Added

• Add changelog to readme

v4.1.3 - 2021-07-1

Added

• Add support for translation tag element reordering. Now inline elements will be reordered the same as translation API is transformed.

Fixed

• Fix canceling translation on source language.
• Fix deescaped html processing in text

v4.1.2 - 2021-07-1

Fixed

• Fix deescaped html processing in text

v4.1.1 - 2021-07-1

Fixed

• Fix canceling translation on source language.

v4.1.0 - 2021-06-30

Added

• Add support for translation tag element reordering. Now inline elements will be reordered the same as translation API is transformed.
• Add to readme about SEO functionality

Changed

• Cleanup wtw custom element ids when restoring.

v4.0.0 - 2021-06-18

Fixed

• Apply translatable attribute functionality for SEO url localization.

v3.2.20, v3.2.19 - 2021-06-10

Changed

• Webpack: in dev env run with hot reload

v3.2.18, v3.2.17 - 2021-06-10

Fixed

• Keep links without lang codes if it is source language and wtw is in init stage

v3.2.16 - 2021-06-10

Fixed

• When initializing, apply SEO, so search engines instantly sees related pages in different languages.

v3.2.15 - 2021-06-08

Added

• Allow to reinitialize language menu

v3.2.14 - 2021-06-7

Added

• Allow to reinitialize language menu

Fixed

• SEO restore should restore links to original state. SEO should be applied to iframes too
• Remove suggestion windows after sign-out.

v3.2.13 - 2021-06-04

Fixed

• Make or localize canonical urls for SEO improvements.

v3.2.12 - 2021-06-04

Fixed

• Autotranslate should not translate source language.

v3.2.11 - 2021-06-03

Fixed

• Make or localize canonical urls for SEO improvements.
• Ignore zombie text fragments.

Changed

• Fix readme for wtw init

Removed

• Remove deprecated allowpublic option
• Remove widget.css from examples
• Remove obsolete options because of new design

v2.0.9 - 2021-05-12

Fixed

• Continue gracefully when system is gone and metadata cannot be read

Licence

Copyright (C) 2020 by Tilde SIA. All rights reserved.

Proprietary software.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.