Documentation for the TranslateThis Button

With it's wide variety of customizable options, the TranslateThis Button isn't only for the cut-n-paster's.

These are the docs for the TranslateThis Button script. For the WordPress Plugin documentation, click here.


Setting TranslateThis Options

Setting custom options for the TranslateThis Button is pretty simple. First find the part that looks like this:

<script type="text/javascript">
TranslateThis();
</script>

You can set a number of options for the TranslateThis Button by passing this function an option array like this:

<script type="text/javascript">
TranslateThis({
    GA : true,
    scope : 'content'
});
</script>

In this example we are setting GA to turn on Google Analytics tracking and scope to restrict the translation to inside the element with the ID of 'content'.

One thing to be careful about when setting the options is to make sure that the last element in the array doesn't have a comma at the end. Note how the first element GA : true, has a comma whereas the last one scope : 'content' does not.

Example with most of the options set:

<script type="text/javascript">
TranslateThis({
    GA : true, // Google Analytics tracking
    scope : 'content', // ID to confine translation
    wrapper : 'translate-this', // ID of the TranslateThis wrapper
    
    onLoad : function() { alert('loaded') }, // Callback function
    onClick : function() { alert('translation started') },
    onComplete : function() { alert('translation finished') },
    
    cookie : 'tt-lang', // Name of the cookie - set to 0 to disable
    
    panelText : 'Translate Into:', // Panel header text
    moreText : '42 More Languages »', // More link text
    busyText : 'Translating page...',
    cancelText : 'cancel',
    doneText : 'Translated by the', // Completion message text
    undoText : 'Undo »', // Text for untranslate link
    
    undoLength : 10000, // Time undo link stays visible (milliseconds)
    
    
    ddLangs : [ // Languages in the dropdown
        'cs',
        'pt-PT',
        'it',
        'ru',
        'ar',
        'zh-CN',
        'ja',
        'ko'
    ],

    noBtn : false, // whether to disable the button styling
    btnImg : 'http://x.translateth.is/tt-btn1.png',
    btnWidth : 180,
    btnHeight : 18,

    noImg : false, // whether to disable flag imagery
    imgHeight : 12, // height of flag icons
    imgWidth : 8, // width of flag icons
    bgImg : 'http://x.translateth.is/tt-sprite.png',

    reparse : true // whether to reparse the DOM for each translation
});
</script>

The only options left out are allLangs and imgMap since those are very long. See the default option listing for more info on these.


Available Options for the TranslateThis Button

Here is a list of options available for TranslateThis:

GA

Set GA to true to enable Google Analytics tracking. This will call the Google tracking script whenever the page is translated. For instance for Spanish it will pass this string as a page view: 'TranslateThis-es'. This hooks in automatically to any Google Analytics script you have running.

Defaults to false


scope

Set scope to an ID of any element on your page to restrict the translation to that element only. This can provide for a much faster translation if you only care about translating a certain portion of your page.

Defaults to false


wrapper

Set wrapper to the ID of your TranslateThis widget. Use this if you want to include multiple TranslateThis widgets on a single page–make sure to change the ID for each one and then call TranslateThis() with the wrapper set for each one.

Defaults to 'translate-this'


onLoad

A callback function that gets called when the script loads. The easiest way is to define a function on the fly here, for instance:

<script type="text/javascript">
TranslateThis({
    onLoad : function() {
        // whatever you want in here
        alert('callback working');
    }
});
</script>

Alternately you can set this to the name of a function, leaving off the parentheses like: onLoad : translateCallback to call the function translateCallback().

Defaults to null


onClick

Callback function for when translation starts. onClick also passes the Google language slug as the first argument in the callback function. For instance:

<script type="text/javascript">
TranslateThis({
    // here we set up the variable lang to reference the language slug
    onClick : function(lang) {
        // whatever you want to run on click
        alert('callback working - language: ' + lang);
    }
});
</script>

Defaults to null


onComplete

Callback function for when the translation completes. For instance:

<script type="text/javascript">
TranslateThis({
    onComplete : function() {
        // whatever you want to run on complete
        alert('callback working');
    }
});
</script>

Defaults to null


cookie

Name of the cookie used to track which language a user has selected on subsequent pages on a site (so that it translates every page on your site). Set to false to disable cookies altogether and only use the TranslateThis Button to translate a single page at a time.

The TranslateThis Button's cookie expires in 30 days or as soon as a user clicks "cancel" or "untranslate".

Defaults to 'tt-lang'


doneText

Text for the message shown after the translation completes. The script takes this string and adds ' TranslateThis Button'

Defaults to 'This page translated by the'


undoText

Text for the untranslate link.

Defaults to 'Undo »'


panelText

Panel header text for the dropdown and all languages overlay.

Defaults to 'Translate Into:'


moreText

Text for the more link in the dropdown.

Defaults to '<count of all languages minus count of dropdown languages> More Languages »'


busyText

Text for the overlay panel that shows up while the translation is processing.

Defaults to 'Translating page...'


cancelText

Text for the cancel link in the Translating page.... panel.

Defaults to 'cancel'


undoTime

Duration of time that the undo link appears at the top of the screen. Set in milliseconds, e.g. a value of 10000 would make the undo link disappear after 10 seconds. Set to 0 to make undo link appear permanently.

Defaults to 4000 (4 seconds)


fromLang (Now deprecated since the script automatically detects language for every page)

Defaults to ''


ddLangs

Array of languages to be used in the dropdown. Pass in Google language codes. The order of the array is the order that they will be shown, descending each column and then from left to right.

Defaults to:

[
    'fr',
    'es',
    'ar',
    'zh-CN',
    'ko',
    'it',
    'cs',
    'iw',
    'de',
    'pt-PT',
    'ru',
    'ja',
    'vi',
    'el',
    'hi',
    'tr'
]

allLangs

Array of languages to be used in the all language overlay panel. Pass in the Google language slugs. Just like ddLangs, the order of the array is the order that they will be shown, descending each column and then from left to right.

For default value see the default option listing


onlyDD

Set onlyDD to true to disable the "All Languages" overlay and only use the language dropdown.

Defaults to false


noBtn

Set noBtn to true to disable the styling of the TranslateThis Button (but not the flags in the dropdown). This allows you to use a plain text link, replace the text of the link with an image, or style the link yourself using CSS. noBtn will disable btnImg, btnHeight and btnWidth if set to true.

Defaults to false


btnImg

The location of the button background image

Defaults to 'http://x.translateth.is/tt-btn1.png' (this may change with new releases to ensure image assets are synced up with JavaScript)


btnHeight

The height of the button in pixels.

Defaults to 18


btnWidth

The width of the button in pixels

Defaults to 180


noImg

Set noImg to true to disable the flag imagery and use text only links. This will provide a performance increase because the widget won't style the flags for the main links or append them at all for the dropdown or overlay.

Defaults to false


imgHeight

The height of the flag icons in pixels

Defaults to 12


imgWidth

The width of the flag icons in pixels

Defaults to 18


bgImg

The location of the flag imagery sprite sheet

Defaults to 'http://x.translateth.is/tt-sprite.png' (this may change with new releases to ensure image assets are synced up with JavaScript)


imgMap

The mapping of the sprite sheet. Pass an object with language code - value pairs, where the value is the flag's index vertically on the sprite sheet. TranslateThis multiplies this index by the value of imgHeight to determine the vertical background positioning for the flag icon.

For default value see the default option listing


reparse

Set reparse to true to cause TranslateThis to re-parse the DOM each time a translation is called instead of reusing any content strings it has already parsed. Use this for dynamic websites with changing content. If your content is static, leave this set to false, since the DOM parsing operation is one of the heaviest in the script.

Additionally, the translation will be of higher quality if reparse is set to false. This is because the script will reuse the original text for the translation, rather than translating the translated text over again. (Remember in the 90's if you would copy tape and then try to make a copy of the copy).

reparse only effects users who translate a given page more than once.

Defaults to false


Default Options for the TranslateThis Button

defaultOptions = { 
    GA : false,
    scope : false,
    wrapper : 'translate-this',
    
    onLoad : null,
    onClick : null,
    onComplete : null,
    
    cookie : 'tt-lang',
    
    undoText : 'Undo »',
    panelText : 'Translate Into:',
    moreText : '42 More Languages »',
    busyText : 'Translating page...',
    cancelText : 'cancel',
    
	
    ddLangs : [
        'cs',
        'da',
        'nl',
        'fi',
        'el',
        'iw',
        'hi',
        'hu',
        'is',
        'id',
        'ga',
        'no',
        'pl',
        'ro',
        'sv',
        'th',
        'tr',
        'vi'
    ],
    
    allLangs : [
        'af',
        'sq',
        'ar',
        'hy',
        'az',
        'eu',
        'be',
        'bg',
        'ca',
        'zh-CN',
        'zh-TW',
        'hr',
        'cs',
        'da',
        'nl',
        'en',
        'et',
        'fi',
        'fr',
        'gl',
        'ka',
        'de',
        'el',
        'ht',
        'iw',
        'hi',
        'hu',
        'is',
        'id',
        'ga',
        'it',
        'ja',
        'ko',
        'lv',
        'lt',
        'mk',
        'ms',
        'mt',
        'no',
        'fa',
        'pl',
        'pt-PT',
        'ro',
        'ru',
        'sr',
        'sk',
        'sl',
        'es',
        'sw',
        'sv',
        'tl',
        'th',
        'tr',
        'uk',
        'ur',
        'vi',
        'cy',
        'yi'
    ],
    
    noBtn : false,
    btnImg : 'http://x.translateth.is/tt-btn1.png',
    btnHeight : 18,
    btnWidth : 180,
    
    noImg : false,
    imgHeight : 12,
    imgWidth : 18,
    bgImage : 'http://x.translateth.is/tt-sprite3.png',
    
    imgMap : {
        af : 10, // Afrikaans
        sq : 11, // Albanian
        ar : 6, // Arabic
        hy : 52, // Armenian
        az : 53, // Azerbaijani
        eu : 54, // Basque
        be : 12, // Belarusian
        bg : 13, // Bulgarian
        ca : 50, // Catalan
        'zh-CN' : 7, // Chinese simplified
        'zh-TW' : 14, // Chinese traditional
        hr : 15, // Croatian
        cs : 16, // Czech
        da : 17, // Danish
        nl : 18, // Dutch
        en : 19, // English - use 20 for UK flag
        et : 21, // Estonian
        fi : 22, // Finnish
        fr : 0, // French
        gl : 51, // Galician
        ka : 55, // Georgian
        de : 1, // German
        el : 23, // Greek
        ht : 56, // Haitian Creole
        iw : 24, // Hebrew
        hi : 25, // Hindi
        hu : 26, // Hungarian
        is : 27, // Icelandic
        id : 28, // Indonesian
        ga : 29, // Irish
        it : 4, // Italian
        ja : 8, // Japanese
        ko : 9, // Korean
        lv : 30, // Latvian
        lt : 31, // Lithuanian
        mk : 32, // Macedonian
        ms : 33, // Malay
        mt : 34, // Maltese
        no : 35, // Norwegian
        fa : 36, // Persian
        pl : 37, // Polish
        'pt-PT' : 3, // Portuguese
        ro : 38, // Romanian
        ru : 5, // Russian
        sr : 39, // Serbian
        sk : 40, // Slovak
        sl : 41, // Slovenian
        es : 2, // Spanish
        sw : 42, // Swahili
        sv : 43, // Swedish
        tl : 44, // Tagalog (Filipino)
        th : 45, // Thai
        tr : 46, //Turkish
        uk : 47, // Ukrainian
        ur : 57, // Urdu
        vi : 48, // Vietnamese
        cy : 49, // Welsh
        yi : 24 // Yiddish
    },
    
    maxLength : 1000,
    reparse : false
};

TranslateThis Button Changelog

Version 1.0.8

Released January 28th, 2012

  • The button was originally created and developed by Jon Raasch up until this version but is now being developed and hosted by Translate Company to continue development and updates for it.
  • Adds 6 new languages: Armenian, Azerbaijani, Basque, Georgian, Haitian Creole and Urdu.
  • Adds undoTime option to allow control over the duration the undo link stays visible. Can be used to display undo link permanently.
  • Adds onlyDD option to allow only the dropdown to be used (and disable the all languages overlay).
  • Automatically calculates number for "42 More Languages" text link (if not over-written by options).
  • Does not require Google API to be loaded saving one HTTP request.
  • Now uses next-generation WebSockets to speed up performance in new browsers, and maintain similar performance in older browsers. This has been combined with significant rewrites of the translation code that increased overall speed.
  • fromLang option has been deprecated and it will be ignored if specified. The button now automatically detects the language for each individual page.

Version 1.0.7

Released November 3, 2010

  • Fixes window overflow issue when button is placed on the far right side of the browser window.
  • Better window overflow handling in general (based on actual dropdown dimensions rather than default dimensions).
  • Popup alert if user tries to translate into a language that their browser does not support (e.g. if they don't have the appropriate character set installed).

Version 1.0.6

Released October 19, 2010

  • Huge performance boost for translation (around 70% for most sites).
  • Preserves any DOM based JavaScript by translating only text nodes.
  • Reduces HTTP requests to Google Language servers.
  • Data URI for button image in all browsers except IE7-.
  • Fixes a bug causing the script to time out and not complete translation.

Version 1.0.5

Released May 10, 2010

  • Improved handling of click event bubbling for better performance & faster script instantiation.
  • gZipping script, bringing file size down to 5.2 kb, and further improving script load time.

Version 1.0.4

Released April 22, 2010

  • Considerable performance increase in the translation operation – now processes translation asynchronously while parsing the DOM into translatable segments.
  • If translating into the fromLang, it triggers a cancel. This provides another way to cancel the automatic translation cookie.

Version 1.0.3

Released April 21, 2010

  • Incorporates "notranslate" functionality – apply the class "notranslate" to any element you want to avoid translation on.
  • Fixes bug with table data in IE.
  • Speed improvement to translation operation.

Version 1.0.2

Released February 11, 2010

  • Considerable speed gains for the translation operation.
  • Additional performance gain for faster script loading.

Version 1.0.1

Released January 21, 2010

  • Fixes z-indexing issues some users were experiencing, by assigning a z-index of 3000 to the overlay and a z-index of 3500 to the panels on top of the overlay.

Version 1.0

Released December 20, 2009

  • Adds cookie functionality to allow TranslateThis to translate all the pages on a site with a single click.
  • Adds 'Cancel' link to the translating... overlay. This allows the user to cancel the translation if it is taking a considerable amount of time (like if the Google Language API is down or slow or there is just too much content on the page).
  • Adds a 'This page translated by the TranslateThis Button' message that flashes after the page is translated.
  • Adds undo functionality, and an undo link to the 'translated by' message.
  • The cancel link, 'translated by' message and undo link are all to make it so that the cookie functionality isn't too invasive. For instance on shared computers if one user translates a page, other users are made aware of what happened with the 'translated by' message, and then are able to cancel or undo the action.
  • Adds more multi-language support, with options to control most of the UI text in the widget.

Version 0.1

Released December 8, 2009

  • Initial release of the TranslateThis Button. A 'cut-and-paste' widget that translates any page using Javsacript to leverage the Google Language API.
  • A nice user interface to access the languages, including dropdowns and overlays, as well as a 'Translating...' message.
  • Many user-controlled options including methods to customize the imagery, supported languages, UI text, dimensions and add Google Analytics tracking.
  • This is an expansion of Translate-It, a JavaScript widget that I built a while ago. It's a drastic upgrade that not only provides a much richer interface but also processes the translation on the front-end using JavaScript, rather than booting the user to Google Translate.

Translate-It

Released November 30, 2008 Available here

  • A JavaScript translation widget that translates any page using Google Translate.
  • Builds a flag icon interface, each of which links the user to the translated version of that page on Google Translate.
  • Customizable options including changing the supported languages, imagery and some text options.