Class Reference for Translation API

Table of Contents

Global Methods

Result Objects

Translation Result

• <result>
  • error?
    Present if there was an error loading the feed:
    • code
      An HTTP-style error code.
    • message
      A human readable string description of the error.
  • translation
    The translated text.
  • detectedSourceLanguage?
    If the source language was automatically determined, it will be returned here.

Language Detection Result

• <result>
  • error?
    Present if there was an error loading the feed.
    • code
      An HTTP-style error code.
    • message
      A human readable string description of the error.
  • language
    The language code associated with the given text. See the Language 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.

Languages Enum

The google.language.Languages enumeration provides a mapping from name constants to language codes used as srcLang and destLang arguments to google.language.translate and as the result.language result for google.language.detect. These are the same codes that are 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',
  'BULGARIAN' : 'bg',
  'BURMESE' : 'my',
  'CATALAN' : 'ca',
  'CHEROKEE' : 'chr',
  'CHINESE' : 'zh',
  'CHINESE_SIMPLIFIED' : 'zh-CN',
  'CHINESE_TRADITIONAL' : 'zh-TW',
  'CROATIAN' : 'hr',
  'CZECH' : 'cs',
  'DANISH' : 'da',
  'DHIVEHI' : 'dv',
  'DUTCH': 'nl',  
  'ENGLISH' : 'en',
  'ESPERANTO' : 'eo',
  'ESTONIAN' : 'et',
  'FILIPINO' : 'tl',
  'FINNISH' : 'fi',
  'FRENCH' : 'fr',
  'GALICIAN' : 'gl',
  'GEORGIAN' : 'ka',
  'GERMAN' : 'de',
  'GREEK' : 'el',
  'GUARANI' : 'gn',
  'GUJARATI' : 'gu',
  'HEBREW' : 'iw',
  'HINDI' : 'hi',
  'HUNGARIAN' : 'hu',
  'ICELANDIC' : 'is',
  'INDONESIAN' : 'id',
  'INUKTITUT' : 'iu',
  'IRISH' : 'ga',
  'ITALIAN' : 'it',
  'JAPANESE' : 'ja',
  'KANNADA' : 'kn',
  'KAZAKH' : 'kk',
  'KHMER' : 'km',
  'KOREAN' : 'ko',
  'KURDISH': 'ku',
  'KYRGYZ': 'ky',
  'LAOTHIAN': 'lo',
  'LATVIAN' : 'lv',
  'LITHUANIAN' : 'lt',
  'MACEDONIAN' : 'mk',
  'MALAY' : 'ms',
  'MALAYALAM' : 'ml',
  'MALTESE' : 'mt',
  'MARATHI' : 'mr',
  'MONGOLIAN' : 'mn',
  'NEPALI' : 'ne',
  'NORWEGIAN' : 'no',
  'ORIYA' : 'or',
  'PASHTO' : 'ps',
  'PERSIAN' : 'fa',
  'POLISH' : 'pl',
  'PORTUGUESE' : 'pt-PT',
  'PUNJABI' : 'pa',
  'ROMANIAN' : 'ro',
  'RUSSIAN' : 'ru',
  'SANSKRIT' : 'sa',
  'SERBIAN' : 'sr',
  'SINDHI' : 'sd',
  'SINHALESE' : 'si',
  'SLOVAK' : 'sk',
  'SLOVENIAN' : 'sl',
  'SPANISH' : 'es',
  'SWAHILI' : 'sw',
  'SWEDISH' : 'sv',
  'TAJIK' : 'tg',
  'TAMIL' : 'ta',
  'TAGALOG' : 'tl',
  'TELUGU' : 'te',
  'THAI' : 'th',
  'TIBETAN' : 'bo',
  'TURKISH' : 'tr',
  'UKRAINIAN' : 'uk',
  'URDU' : 'ur',
  'UZBEK' : 'uz',
  'UIGHUR' : 'ug',
  'VIETNAMESE' : 'vi',
  'WELSH' : 'cy',
  'YIDDISH' : 'yi',
  'UNKNOWN' : ''
};

Languages ContentType Enum

The google.language.ContentType enumeration provides acceptable type values for the content type of the text to be translated. By default the system treats the text to be translated as HTML and will preserve the appropriate markup in the resulting translation.

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

Font Rendering Status Enum

The google.language.FontRenderingStatus enumeration provides a mapping from name constants to values indicating whether the font detection support is present or not. The "UNKNOWN" value indicates that the font rendering support detection API does not support the specified language.

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

Flash and other Non-Javascript Environments

For Flash developers, and those developers that have a need to access the AJAX Language API from other Non-Javascript environments, the API exposes a simple RESTful interface. In all cases, the method supported is GET, and the response format is a JSON encoded result with embedded status codes. For google.language.translate, the POST method is available. Applications that use this interface must abide by all existing terms of use. An area to pay special attention to relates to correctly identifying yourself in your requests. Applications MUST always include a valid and accurate http referer header in their requests. In addition, we ask, but do not require, that each request contains a valid API Key. By providing a key, your application provides us with a secondary identification mechanism that is useful should we need to contact you in order to correct any problems.

Like the core Javascript interface, this interface is exposed through a uniform URL containing a mix of both standard and method specific CGI arguments. Your application can use an http stack of it's choosing. The only requirements are that you must be able to construct a properly constructed URL with all necessary CGI arguments, that you send an http referer header that accurately identifies your application, and that you are able to process the JSON encoded response.

Standard URL Base Address'

Each Language API method is accessed through a standard URL. The following table lists the URL used to access each method.

Standard URL Arguments

Each request contains a mix of standard URL arguments as well as an optional set of method specific arguments. This section describes the standard arguments that are uniform accross all methods and that convey virtually identical semantic information to each method. In some cases, an argument is optional. This is indicated with a ? following the name of the argument. In all cases, the value of a CGI argument must be properly escaped (e.g., via the functional equivalent of Javascript's encodeURIComponent() method).

The following table lists the standard URL arguments. Additional sections appear below that highlight method specific arguments.

callbackFunction(
  {"responseData" : {
    "translatedText" : the-translated-text,
    "detectedSourceLanguage"? : the-source-language
  },
  "responseDetails" : null | string-on-error,
  "responseStatus" : 200 | error-code
})
      

callbackFunction(
  contextValue,    // the context arg value
  responseObject,  // the method result
  responseStatus,  // 200 on success, non-200 on failure
  errorDetails)    // error string for non-200 response
      

Standard Response Format

As discussed briefly in the previous section, there are two major variations in the response format. When the callback and context arguments are not supplied, the response format is a simple JSON object similar to the snippets shown below:

JSON Response for Translate Language

{
  "responseData" : {
    "translatedText" : the-translated-text,
    "detectedSourceLanguage"? : the-source-language
  },
  "responseDetails" : null | string-on-error,
  "responseStatus" : 200 | error-code
}

JSON Response for Detect Language

{
  "responseData" : {
    "language" : the-detected-language,
    "isReliable" : the-reliability-of-the-detect,
    "confidence" : the-confidence-level-of-the-detect
  },
  "responseDetails" : null | string-on-error,
  "responseStatus" : 200 | error-code
}

In the JSON fragment above, note that the responseData property contains method specific properties that are identical to the properties available in the JavaScript binding. For additional information please review the Result Objects discussion. Note that in this portion of the document, there is an optional error object described. When using the URL based protocol, the error property is never present. Instead, the responseStatus and responseDetails properties are used. The responseStatus property contains a value of 200 on success and a non-200 http error status code on failure. If there is a failure, responseDetails contains a diagnostic string.

By using the callback argument, applications can easily request a JavaScript callback:

callbackFunction(
  {"responseData" : {
    "language" : the-detected-language,
    "isReliable" : the-reliability-of-the-detect,
    "confidence" : the-confidence-level-of-the-detect
  },
  "responseDetails" : null | string-on-error,
  "responseStatus" : 200 | error-code
})

If the application supplies both callback and context arguments, the response is encoded as a JavaScript procedure call. In this mode of operation, the value of callback becomes the procedure call target, the value of context is passed as the first argument, the value of responseData from above is passed as the second argument, the response status is passed as the third argument, and the final argument is either null or a diagnostic string.

foo('bar',{"translatedText":"Ciao mondo","detectedSourceLanguage":"en"},
    200, null)

Translate Language Specific Arguments

The Translate method supports a number of optional arguments which are all listed below:

Detect Language Specific Arguments

The Detect Language method has no additional arguments. All arguments are listed above.

Batch Interface

The batch interface, which is only available with the RESTful framework, allows for multiple translations to occur in a single call through the use of multiple q and/or langpair arguments. The response consists of an array of responsData, as shown in the following examples. There are three valid combinations of batch calls:

1. Translate several strings, all from the same source language to the same target language. This is accomplished through the use of multiple q arguments. For example:
   
   Translate two strings
   
   
2. Translate one string into several languages. This is accomplished through the use of multiple langpair arguments. For example:
   
   Translate into two languages
   
   
3. Translate several strings, each into a different language. In this case, there must be the same number of q arguments as there are langpair arguments, with them paired up in order:
   
   Translate two strings (each into a different language)