Referência de classe para a API de tradução

Sumário

Métodos globais

Objetos de resultado

Resultado da tradução

• <result>
  • error?
    Presente se houve um erro ao carregar o feed:
    • code
      Um código de erro em estilo HTTP.
    • message
      Uma descrição da string do erro que pode ser lida.
  • translation
    O texto traduzido.
  • detectedSourceLanguage?
    Se o idioma de origem foi determinado automaticamente, ele será retornado aqui.

Resultado da detecção do idioma

• <result>
  • error?
    Presente se houve um erro ao carregar o feed.
    • code
      Um código de erro em estilo HTTP.
    • message
      Uma descrição da string do erro que pode ser lida.
  • language
    O código de idioma associado ao texto fornecido. Consulte Enumeração de idiomas para obter exemplos.
  • isReliable
    Um valor booleano representando se o intervalo de detecção confia no código de idioma para o texto fornecido.
  • confidence
    Um valor numérico entre 0 e 1.0 que representa o nível de confiança no código do idioma para o texto fornecido.

Enumeração de idiomas

A enumeração google.language.Languages fornece um mapeamento de constantes de nome para códigos de idioma usados como argumentos srcLang e destLang para google.language.translate e como o resultado result.language para google.language.detect. Estes são os mesmo códigos usados no Google Tradutor.

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',
  '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',
  'UNKNOWN' : ''
};

Enumeração de ContentType dos idiomas

A enumeração google.language.ContentType fornece valores de tipo aceitáveis para o tipo de conteúdo do texto a ser traduzido. Por padrão, o sistema trata o texto a ser traduzido como HTML e preservará a marcação apropriada na tradução resultante.

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

Enumeração de status de exibição de fonte

A enumeração google.language.FontRenderingStatus fornece um mapeamento das constantes de nome para valores indicando se o suporte para detecção de fonte está presente ou não. O valor "UNKNOWN" indica que a API de detecção do suporte para exibição de fonte não suporta o idioma especificado.

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

Flash e outros ambientes que não são de Javascript

Para os desenvolvedores de Flash e para desenvolvedores que precisam acessar a API AJAX de idioma do Google a partir de outros ambientes que não sejam Javascript, a API oferece uma interface RESTful simples. Em todos os casos, GET é o método suportado e o formato de resposta é um resultado codificado JSON com códigos de status incorporados. Para google.language.translate, o método POST está disponível. Os aplicativos que usam esta interface devem obedecer a todos os termos de uso existentes. Você deve ter atenção especial quanto a se identificar corretamente em suas solicitações. Os aplicativos sempre DEVEM incluir um cabeçalho de referência http em suas solicitações. Além disso, pedimos que cada solicitação contenha uma chave de API válida, mas isso não é obrigatório. Ao fornecer uma chave, seu aplicativo nos fornece um mecanismo secundário de identificação. Isso é útil para o caso de ser necessário entrar em contato com você para corrigir algum problema.

Assim como a interface JavaScript principal, esta interface é exposta por meio de um URL uniforme que contém uma mistura de argumentos CGI padrão e específicos do método. Seu aplicativo pode usar uma pilha HTTP de sua própria escolha. Os únicos requisitos são que você deve ser capaz de construir apropriadamente um URL com todos os argumentos CGI necessários, deve enviar um cabeçalho de referência http identificando precisamente seu aplicativo e deve processar a resposta codificada JSON.

Endereço URL básico padrão

Cada método da API de idioma é acessado por um URL padrão. A tabela a seguir indica o URL usado para acessar cada método.

Argumentos padrão de URL

Cada solicitação contém uma mistura de argumentos padrão de URL, além de um conjunto opcional de argumentos específicos do método. Esta seção descreve os argumentos padrão uniformizados entre todos o métodos e que transmitem informações semânticas virtualmente idênticas a cada método. Em alguns casos, o uso de um argumento é opcional. Isso é indicado por um sinal ? ao lado do nome do argumento. Em todos os casos, o valor do argumento CGI deve estar devidamente seguido dos códigos de escape (por ex., através da função equivalente do método JavaScript encodeURIComponent()).

A tabela a seguir lista os argumentos padrão de URL. Há seções adicionais abaixo que destacam argumentos específicos do método.

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
      

Formato de resposta padrão

Como discutido rapidamente na seção anterior, há duas variações principais do formato de resposta. Quando os argumentos callback e context não são fornecidos, o formato de resposta é um objeto JSON simples, semelhante aos snippets mostrados abaixo:

Resposta JSON para o idioma de tradução

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

Resposta JSON para o idioma de detecção

{
  "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
}

No fragmento JSON acima, observe que a propriedade responseData contém propriedades específicas do método que são idênticas às propriedades disponíveis no vínculo JavaScript. Para obter informações adicionais, leia a discussão sobre os Objetos dos resultados. Observe que, nesta parte do documento, há um objeto error opcional descrito. Ao usar o protocolo com base em URL, a propriedade error nunca está presente. Em vez disso, as propriedades responseStatus e responseDetails são usadas. A propriedade responseStatus contém o valor 200 para sucesso e um código de status de erro http diferente de 200 para falha. Se houver uma falha, a propriedade responseDetails contém uma string de diagnóstico.

Ao usar o argumento callback, os aplicativos podem facilmente solicitar um retorno de chamada do JavaScript:

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
})

Se o aplicativo fornecer ambos os argumentos callback e context, a resposta será codificada como uma chamada de procedimento JavaScript. Neste modo de operação, o valor de callback torna-se o destino da chamada do procedimento, o valor de context é passado como primeiro argumento, o valor de responseData acima é passado como segundo argumento, o status da resposta é passado como terceiro argumento e o argumento final é null ou uma string de diagnóstico.

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

Argumentos específicos do idioma de tradução

O método Tradução suporta os diversos argumentos opcionais listados abaixo:

Argumentos específicos da detecção de idioma

O método Detecção de idioma não possui argumentos adicionais. Todos os argumentos foram listados acima.

Interface em lote

A interface em lote, disponível apenas com a estrutura RESTful, permite a realização de múltiplas traduções em uma única chamada com o uso de diversos argumentos q e/ou langpair. A resposta é composta por uma matriz de responsData, conforme mostra os exemplos abaixo. Há três combinações válidas de chamadas em lote:

1. Traduzir diversas strings, todas do mesmo idioma de origem para o mesmo idioma de destino. Isso é obtido usando diversos argumentos q. Por exemplo:
   
   Traduzir duas strings
   
   
2. Traduzir uma string para diversos idiomas. Isso é obtido usando diversos argumentos langpair. Por exemplo:
   
   Traduzir para dois idiomas
   
   
3. Traduzir diversas strings, cada uma para um idioma diferente. Nesse caso, deve haver o mesmo número de argumentos q e argumentos langpair, pareados em ordem:
   
   Traduzir duas strings (cada uma para um idioma diferente)