My favorites ▼ | English ▼ | Sign in

Google Translate API v1 (No Longer Available)

Google Translate API v1 JavaScript Reference

Important: Google Translate API v1 was officially deprecated on May 26, 2011; it was shut off completely on December 1, 2011. For text translations, you can use the Google Translate API v2, which is now available as a paid service. For website translations, we encourage you to use the Google Website Translator gadget.

Table of Contents

  1. Google Translate API JavaScript Reference
  2. Result properties
    1. Translation
    2. Language detection
  3. Enums
    1. Language enum
    2. ContentType enum
    3. FontRenderingStatus enum
    4. List of translatable languages
  4. Troubleshooting

Google Translate API JavaScript reference

The methods described in this section are built on the google.language namespace.

Method Description

.detect(text, callback)

.detect(text, callback) is a global method that returns the BCP47 language code (such as "en" for English) describing the language of the given text. The language code is supplied asynchronously to the given callback function as the result object. This method utilizes the Languages enum. This method is defined as follows:

  • text is the text block whose language you wish to detect.
  • callback is the callback function that receives the result.

google.language.detect() has no return value.

.isFontRenderingSupported(langCode)

.isFontRenderingSupported(langCode) is a global method that detects if the user's browser supports Unicode font rendering for a language supplied by the langCode argument. The langCode is derived from the Languages enum.

isFontRenderingSupported() returns one of the following values from the FontRenderingStatus enum:

  • google.language.FontRenderingStatus.UNSUPPORTED indicates that font rendering is not supported
  • google.language.FontRenderingStatus.SUPPORTED indicates that font rendering is supported
  • google.language.FontRenderingStatus.UNKNOWN indicates that font rendering support cannot be determined for this language, and is therefore unsupported.

.isTranslatable(langCode)

.isTranslatable(langCode) analyzes a language code and returns a boolean value (true or false) indicating whether the text can be translated based on the Languages enum.

.translate(text|content, srcLang, destLang, callback)

.translate(text|content, srcLang, destLang, callback) is a global method that returns the translation of a text block. The API supplies a result object containing translated text asynchronously via the result function. This method is defined as follows:

  • text|content specifies the text to be translated, either as a string or an object, as follows:
    • To supply a string, specify the text argument as a string. The system preserves HTML markup in strings on the assumption that the input and the result are web-based. 
      google.language.translate
  ('<p>text string to translate</p>')
    • To supply an object, specify a <content> text and type. text supplies the text string to be translated and type specifies the content type (either html or text), as specified in the ContentType enum. The following code snippet demonstrates how to supply content text and type: 
      translate(
  {text: 'text string to translate', type: 'html'})
      The type property corresponds to the format URL parameter as described in the JSON Developer's Guide. The default behavior for HTML content is to not translate the strings that are part of an HTML tag, but rather to translate only the text nodes in the HTML.
  • srcLang specifies the BCP47 code for the language of the text to be translated. See the Languages enum for examples. To auto-detect the source language, do not enter srcLang; instead, specify ''.
  • destLang specifies the code for the translation language.
  • callback specifies the callback function that receives the result.

.translate() has no return value.

Static methods

Static method Description

.getBranding(opt_element?, opt_orientation?)

.getBranding(opt_element?, opt_orientation?) is a static helper function that returns a "powered by Google" HTML DOM branding node to your application, and optionally attaches it to your document as the only child of the specified optional element. The purpose of this method is to ensure that your application has a simple way to comply with branding requirements. Including branding also lets users know that text is machine-translated, which helps set expectations and improve the user experience.

The branding node, by default, is designed for a horizontal orientation and works well underneath a text field, above or below a collection of results, etc.

  • opt_element is an optional argument which, if supplied, specifies the HTML DOM node that will be populated with a "powered by Google" branding element.
  • opt_orientation - an optional argument which, if supplied, specifies the orientation of the branding node. Valid values include:
    • horizontal requests horizontal orientation. This is the default behavior.
    • vertical requests vertical orientation.

.getBranding() returns a "powered by Google" HTML DOM node that you can attach or clone onto your document.

Warning! This API requires displaying attribution near any API input boxes and the display of results, indicating that it is "Powered by Google". If you choose not to use .getBranding(), you are obligated to provide this branding yourself.

.getBranding() is implemented on the google.language namespace (as in google.language.getBranding()).

.setOnLoadCallback(callback)

.setOnLoadCallback(callback) is a static function that registers the specified handler function to be called once the page containing this call loads, where callback is a required function called when the containing document is loaded and the API is ready for use (e.g., after onLoad). This function is implemented on the google namespace (i.e., google.setOnLoadCallback(callback);)

.setOnLoadCallback() has no return value.

Note: Previous documentation recommended that you use the body element's onload attribute (<body onload="OnLoad()">). While this is a fine way to go when you are in complete control of the page and all code loaded by the page, this approach can cause problems with some runtimes that destroy your body.onload handler. setOnLoadCallback() does not have these problems, and therefore is the recommended method of registering a callback that calls your code when the API is fully loaded and ready for use.

Result properties

Result objects are produced using a JSON encoding of server search requests. Consequently, we have chosen not to implement formal JavaScript objects, and instead dynamically create these objects from their serialized form.

While there is no formal implementation of the objects, they exist, and we document them as if there was a backing JavaScript implementation. The impact of all this is minimal. All that it means is that there is no named constructor. For each result, it's as if the system called new Object() and then set formal properties on that object. These properties are documented below.

Translation

  • <result>
    • error?
      Present if there was an error in translating the text:
    • translation
      The translated text.
    • detectedSourceLanguage?
      If the source language was automatically determined, it will be returned here.

Language detection

  • <result>
    • error?
      Present if there was an error in detecting the language type.
    • language
      The language code associated with the given text. See the Languages enum for examples.
    • isReliable
      A boolean representing whether or not the detection interval believes the language code is reliable for the given text.
    • confidence
      A numeric value between 0-1.0 that represents the confidence level in the language code for the given text.

Enums

Languages enum

The google.language.Languages enumeration maps name constants to language codes. This enum supplies language codes for srcLang and destLang arguments to google.language.translate. It also supplies the result.language result for google.language.detect. These are the same codes used on Google Translate. 

var google.language.Languages = {
  'AFRIKAANS' : 'af',
  'ALBANIAN' : 'sq',
  'AMHARIC' : 'am',
  'ARABIC' : 'ar',
  'ARMENIAN' : 'hy',
  'AZERBAIJANI' : 'az',
  'BASQUE' : 'eu',
  'BELARUSIAN' : 'be',
  'BENGALI' : 'bn',
  'BIHARI' : 'bh',
  'BRETON' : 'br',
  'BULGARIAN' : 'bg',
  'BURMESE' : 'my',
  'CATALAN' : 'ca',
  'CHEROKEE' : 'chr',
  'CHINESE' : 'zh',
  'CHINESE_SIMPLIFIED' : 'zh-CN',
  'CHINESE_TRADITIONAL' : 'zh-TW',
  'CORSICAN' : 'co',
  'CROATIAN' : 'hr',
  'CZECH' : 'cs',
  'DANISH' : 'da',
  'DHIVEHI' : 'dv',
  'DUTCH': 'nl',  
  'ENGLISH' : 'en',
  'ESPERANTO' : 'eo',
  'ESTONIAN' : 'et',
  'FAROESE' : 'fo',
  'FILIPINO' : 'tl',
  'FINNISH' : 'fi',
  'FRENCH' : 'fr',
  'FRISIAN' : 'fy',
  'GALICIAN' : 'gl',
  'GEORGIAN' : 'ka',
  'GERMAN' : 'de',
  'GREEK' : 'el',
  'GUJARATI' : 'gu',
  'HAITIAN_CREOLE' : 'ht',
  'HEBREW' : 'iw',
  'HINDI' : 'hi',
  'HUNGARIAN' : 'hu',
  'ICELANDIC' : 'is',
  'INDONESIAN' : 'id',
  'INUKTITUT' : 'iu',
  'IRISH' : 'ga',
  'ITALIAN' : 'it',
  'JAPANESE' : 'ja',
  'JAVANESE' : 'jw',
  'KANNADA' : 'kn',
  'KAZAKH' : 'kk',
  'KHMER' : 'km',
  'KOREAN' : 'ko',
  'KURDISH': 'ku',
  'KYRGYZ': 'ky',
  'LAO' : 'lo',
  'LATIN' : 'la',
  'LATVIAN' : 'lv',
  'LITHUANIAN' : 'lt',
  'LUXEMBOURGISH' : 'lb',
  'MACEDONIAN' : 'mk',
  'MALAY' : 'ms',
  'MALAYALAM' : 'ml',
  'MALTESE' : 'mt',
  'MAORI' : 'mi',
  'MARATHI' : 'mr',
  'MONGOLIAN' : 'mn',
  'NEPALI' : 'ne',
  'NORWEGIAN' : 'no',
  'OCCITAN' : 'oc',
  'ORIYA' : 'or',
  'PASHTO' : 'ps',
  'PERSIAN' : 'fa',
  'POLISH' : 'pl',
  'PORTUGUESE' : 'pt',
  'PORTUGUESE_PORTUGAL' : 'pt-PT',
  'PUNJABI' : 'pa',
  'QUECHUA' : 'qu',
  'ROMANIAN' : 'ro',
  'RUSSIAN' : 'ru',
  'SANSKRIT' : 'sa',
  'SCOTS_GAELIC' : 'gd',
  'SERBIAN' : 'sr',
  'SINDHI' : 'sd',
  'SINHALESE' : 'si',
  'SLOVAK' : 'sk',
  'SLOVENIAN' : 'sl',
  'SPANISH' : 'es',
  'SUNDANESE' : 'su',
  'SWAHILI' : 'sw',
  'SWEDISH' : 'sv',
  'SYRIAC' : 'syr',
  'TAJIK' : 'tg',
  'TAMIL' : 'ta',
  'TATAR' : 'tt',
  'TELUGU' : 'te',
  'THAI' : 'th',
  'TIBETAN' : 'bo',
  'TONGA' : 'to',
  'TURKISH' : 'tr',
  'UKRAINIAN' : 'uk',
  'URDU' : 'ur',
  'UZBEK' : 'uz',
  'UIGHUR' : 'ug',
  'VIETNAMESE' : 'vi',
  'WELSH' : 'cy',
  'YIDDISH' : 'yi',
  'YORUBA' : 'yo',
  'UNKNOWN' : ''
};

ContentType enum

The google.language.ContentType enumeration provides acceptable type values for the content type (plain text or HTML) of the text to be translated. By default, the system treats the text to be translated as HTML and preserves the appropriate markup in the resulting translation.

var google.language.ContentType = {
  'TEXT' : 'text',
  'HTML' : 'html'
};

FontRenderingStatus enum

The google.language.FontRenderingStatus enumeration maps name constants to values indicating whether the user's browser supports Unicode font rendering for a given language. The method google.language.isFontRenderingSupported uses this enum.

Note: The value UNKNOWN indicates that the API does not support the specified language.

var google.language.FontRenderingStatus = {
  UNSUPPORTED: 0,
  SUPPORTED: 1,
  UNKNOWN: 2
};

List of translatable languages

The following list provides all of the translatable languages and language codes supported by the API.

Language Code   Language Code
AFRIKAANS af   ITALIAN it
ALBANIAN sq   JAPANESE ja
ARABIC ar   KOREAN ko
BELARUSIAN be   LATVIAN lv
BULGARIAN bg   LITHUANIAN lt
CATALAN ca   MACEDONIAN mk
CHINESE zh   MALAY ms
CHINESE_SIMPLIFIED zh-CN   MALTESE mt
CHINESE_TRADITIONAL zh-TW   NORWEGIAN no
CROATIAN hr   PERSIAN fa
CZECH cs   POLISH pl
DANISH da   PORTUGUESE pt
DUTCH nl   PORTUGUESE_PORTUGAL pt-PT
ENGLISH en   ROMANIAN ro
ESTONIAN et   RUSSIAN ru
FILIPINO tl   SERBIAN sr
FINNISH fi   SLOVAK sk
FRENCH fr   SLOVENIAN sl
GALICIAN gl   SPANISH es
GERMAN de   SWAHILI sw
GREEK el   SWEDISH sv
HAITIAN_CREOLE ht   TAGALOG tl
HEBREW iw   THAI th
HINDI hi   TURKISH tr
HUNGARIAN hu   UKRAINIAN uk
ICELANDIC is   VIETNAMESE vi
INDONESIAN id   WELSH cy
IRISH ga   YIDDISH yi

Troubleshooting

If you encounter problems:

  • Look for typos. Remember that JavaScript is a case-sensitive language.
  • Use a JavaScript debugger. Google Chrome has a full set of developer tools. In Firefox, you can use the JavaScript console or the Firebug. In IE, you can use the Microsoft Script Debugger.
  • Search the discussion group. If you can't find a post that answers your question, post your question to the group along with a link to a web page that demonstrates the problem.