@tilde-nlp/web-translate-widget NPM

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.

Quickstart

Before you begin

To use the Tilde Website Translator you will need: 1. an active TildeMT subscription. You can request a free trial. 1. 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

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.

translate translator html tilde webpage website

@babel/polyfill axios core-js rxjs

@everything-registry/sub-chunk-919 @zalastax/nolb-_til

2 years ago

2 years ago

3 years ago

3 years ago