README
Webpage translation widget
Reach a global audience for your website with just a few clicks!
With the website translation widget, you can make your site multilingual without any coding, manual translating, and duplication of pages.
AI technology-based translation widget can be integrated into any website or e-commerce platform, which instantly translates all its content. The user can switch between multiple languages and get a precise and fast understanding of what you’re offering.
Feature
- Visual Editor A visual editor gives you complete quality control and allows you to edit and manage your translations effortlessly directly inside your website 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 metadata information to make your content attractive to search engines.
- Usage Statistics You can see your translation traffic and the number of translations on your translation platform dashboard.
- Integrations Tilde Website widget is compatible with any kind of website including WordPress, Shopify, Drupal, JavaScript, Joomla, HTML.
Translatable text
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
atribute is not equal to source language configuration in the plugin's 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>
Usage
Include reference to translation plugin
<script src="/dist/widget.js"></script>
Language selection
[Optional] If you want to use built-in language selection, add element to your page. This will be container where language select will be placed.
<div class="tildemt-widget"></div>
Initialization
Initializes plugin to be ready translate page - 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 widget was used, then widget 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 plugin with 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 plugin
await TildeMTTranslationPlugin.Initialize()
Plugin 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 widget 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
Adding MT to already multilingual website
Here are instructions on how to broaden language coverage with machine translation for already multilingual website that have content in two or more languages.
Step #1: Additionally to initial configuration with clientId
you still have to decide which one is going
to be the source language sourceLanguage
. The source language version of the page is going be used to generate
machine translation in additional languages. This decision can be made according to available machine translation
language directions that are available to your subscription.
TildeMTTranslationPlugin.Options.api.clientId = 'x-xxxxxxxx-xxxx-xx'
TildeMTTranslationPlugin.Options.sourceLanguage = "en"
Step #2: Specify languages of your webpage that has translation already embedded and machine translation should
not be carried out. Configure thirdPartyTranslationLanguages
option assuming that we have German and French version
of English pages, for example.
TildeMTTranslationPlugin.Options
.translation.thirdPartyTranslationLanguages = ['de', 'fr']
Step #3: Set 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 JavaScript action to perform on user changes language to one of 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 elaborated example is available in npm package ./examples/Multi pretranslated lang example/
directory.
Options
Plugin determines automatically target language if webpage uses lang
parameter in URL query.
Plugin 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 plugin 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, plugin 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 plugin 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, plugin will use it for translation. Otherwise iflang
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 this Translation plugin,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 plugin UI, values can be:
- source - Show plugin UI in source language
- target - Show plugin UI in target language
TildeMTTranslationPlugin.Options.ui.showTranslationControls
Type:
Boolean
Default:
true
Show or hide "restore" and "cancel" translation buttons on Translation Plugin 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?
TildeMTTranslationPlugin.Options.ui.branding.url
Type:
String
Default:
https://translate.tilde.com/
MT branding link
You can find all development options in npm package ./src/js/interfaces/IPluginOptions.ts
Example
Full examples of code can be viewed in npm package ./examples/
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
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 plugin 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.