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, // Gallician
        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, // Ukranian
        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

Version 1.0.7

Released November 3, 2010

Version 1.0.6

Released October 19, 2010

Version 1.0.5

Released May 10, 2010

Version 1.0.4

Released April 22, 2010

Version 1.0.3

Released April 21, 2010

Version 1.0.2

Released February 11, 2010

Version 1.0.1

Released January 21, 2010

Version 1.0

Released December 20, 2009

Version 0.1

Released December 8, 2009

Translate-It

Released November 30, 2008 Available here