Tradutor 3.0: Tradução

Traduz texto.

URL da solicitação

Envie uma solicitação POST para:

https://api.cognitive.microsofttranslator.com/translate?api-version=3.0

Consulte Suporte de Rede Virtual para configuração e suporte de rede e ponto de extremidade privado selecionados do serviço Translator.

Parâmetros da solicitação

Os parâmetros de solicitação passados na cadeia de caracteres de consulta são:

Parâmetros obrigatórios

Parâmetros opcionais

Os cabeçalhos de solicitação incluem:

Corpo da solicitação

O corpo da solicitação é uma matriz JSON. Cada elemento da matriz é um objeto JSON com uma propriedade de cadeia nomeada Text, que representa a cadeia de caracteres a ser traduzida.

[
    {"Text":"I would really like to drive your car around the block a few times."}
]

Para obter informações sobre limites de caracteres e matrizes, consulte Limites de solicitação.

Corpo da resposta

Uma resposta com êxito é uma matriz JSON com um resultado para cada cadeia de caracteres na matriz de entrada. Um objeto de resultado inclui as seguintes propriedades:

• detectedLanguage: um objeto que descreve o idioma detectado por meio das seguintes propriedades:

  • language: uma cadeia de caracteres que representa o código do idioma detectado.

  • score: um valor flutuante indicando a confiança no resultado. A pontuação é entre zero e um, e uma pontuação baixa indica uma baixa confiança.

  A propriedade detectedLanguage somente está presente no objeto de resultado quando a detecção automática de idioma é solicitada.

• translations: uma matriz de resultados de tradução. O tamanho da matriz corresponde ao número de idiomas de destino especificados por meio do parâmetro de consulta to. Cada elemento na matriz inclui:

  • to: uma cadeia de caracteres representando o código de idioma do idioma de destino.

  • text: uma cadeia de caracteres dando o texto traduzido.

  • transliteration: um objeto que fornece o texto traduzido no script especificado pelo parâmetro toScript.

    • script: uma cadeia de caracteres especificando o script de destino.

    • text: uma cadeia de caracteres que fornece o texto traduzido no script de destino.

    O objeto transliteration não será incluído se a transliteração não ocorrer.

    • alignment: um objeto com uma única propriedade de cadeia de caracteres nomeada proj, que mapeia o texto de entrada para o texto traduzido. As informações de alinhamento serão fornecidas somente quando o parâmetro de solicitação includeAlignment for true. O alinhamento é retornado como um valor de cadeia de caracteres do seguinte formato: [[SourceTextStartIndex]:[SourceTextEndIndex]–[TgtTextStartIndex]:[TgtTextEndIndex]]. Os dois-pontos separam o índice inicial e final, o traço separa os idiomas e o espaço separa as palavras. Uma palavra pode ser alinhada com zero, uma ou várias palavras no outro idioma, e as palavras alinhadas podem ser não contíguas. Quando nenhuma informação de alinhamento estiver disponível, o elemento de alinhamento fica vazio. Consulte Obter informações de alinhamento para um exemplo e restrições.

  • sentLen: um objeto retornando limites de sentença nos textos de entrada e saída.

    • srcSentLen: uma matriz inteira representando os comprimentos das sentenças no texto de entrada. O comprimento da matriz é o número de sentenças, e os valores são o comprimento de cada sentença.

    • transSentLen: uma matriz de inteiros representando os comprimentos das sentenças no texto traduzido. O comprimento da matriz é o número de sentenças, e os valores são o comprimento de cada sentença.

    Limites de sentença serão incluídos somente quando o parâmetro de solicitação includeSentenceLength for true.

• sourceText: um objeto com uma única propriedade de cadeia de caracteres nomeada text, que fornece o texto de entrada no script padrão do idioma de origem. sourceText a propriedade está presente apenas quando a entrada é expressa em um script que não é o script usual para o idioma. Por exemplo, se a entrada fosse árabe escrita em alfabeto latino, então sourceText.text seria o mesmo texto árabe convertido em alfabeto árabe.

Exemplos de respostas JSON são fornecidos na seção exemplos.

Cabeçalhos de resposta

Códigos de status de resposta

Veja a seguir os possíveis códigos de status HTTP retornados por uma solicitação.

Se ocorrer um erro, a solicitação também retornará uma resposta de erro JSON. O código de erro é um número de 6 dígitos que combina o código de status HTTP de 3 dígitos seguido por um número de 3 dígitos para categorizar ainda mais o erro. Códigos de erros comuns que podem ser encontrados na página de referência do Tradutor v3.

Exemplos

Traduzir uma única entrada

Este exemplo mostra como traduzir uma única sentença de inglês para chinês simplificado.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

O corpo da resposta é:

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"}
        ]
    }
]

A matriz translations inclui um elemento, que fornece a tradução da única parte do texto na entrada.

Traduzir uma entrada única com detecção automática de idioma

Este exemplo mostra como traduzir uma única sentença de inglês para chinês simplificado. A solicitação não especifica o idioma de entrada. Em vez disso, é usada a detecção automática do idioma de origem.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

O corpo da resposta é:

[
    {
        "detectedLanguage": {"language": "en", "score": 1.0},
        "translations":[
            {"text": "你好, 你叫什么名字？", "to": "zh-Hans"}
        ]
    }
]

A resposta é semelhante à resposta do exemplo anterior. Como a detecção automática de idioma foi solicitada, a resposta também incluirá informações sobre o idioma detectado para o texto de entrada. A detecção automática de idioma funciona melhor com texto de entrada mais longo.

Traduzir com transliteração

Vamos estender o exemplo anterior, adicionando transliteração. A solicitação a seguir pede uma tradução de chinês gravada em script de latim.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=zh-Hans&toScript=Latn" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

O corpo da resposta é:

[
    {
        "detectedLanguage":{"language":"en","score":1.0},
        "translations":[
            {
                "text":"你好, 你叫什么名字？",
                "transliteration":{"script":"Latn", "text":"nǐ hǎo , nǐ jiào shén me míng zì ？"},
                "to":"zh-Hans"
            }
        ]
    }
]

O resultado da tradução agora inclui uma propriedade transliteration que fornece o texto traduzido usando caracteres de latim.

Traduzir várias partes de texto

Traduzir várias cadeias de caracteres de uma vez é simplesmente uma questão de especificar uma matriz de cadeia de caracteres no corpo da solicitação.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}, {'Text':'I am fine, thank you.'}]"

A resposta contém a tradução de todas as partes do texto na mesma ordem que na solicitação. O corpo da resposta é:

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"}
        ]
    },
    {
        "translations":[
            {"text":"我很好，谢谢你。","to":"zh-Hans"}
        ]
    }
]

Traduzir para vários idiomas

Este exemplo mostra como traduzir a mesma entrada para vários idiomas em uma solicitação.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=zh-Hans&to=de" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

O corpo da resposta é:

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"},
            {"text":"Hallo, was ist dein Name?","to":"de"}
        ]
    }
]

Tratar conteúdo ofensivo

Normalmente, o serviço de tradução retém a linguagem obscena presente no texto de origem da tradução. O grau de palavrões e o contexto que torna as palavras profanas diferem entre as culturas e, como resultado, o grau de palavrões no idioma de destino pode ser amplificado ou reduzido.

Se você quiser evitar conteúdo ofensivo na tradução, independentemente da presença de linguagem vulgar no texto de origem, poderá usar a opção de filtragem de linguagem vulgar. A opção permite que você escolha se deseja ver o palavrão excluído, marcado com tags apropriadas (dando a você a opção de adicionar seu próprio pós-processamento) ou sem nenhuma ação tomada. Os valores aceitos de ProfanityAction são Deleted, Markede NoAction (padrão).

Nos exemplos acima, <insert-profane-word> é um espaço reservado para palavras impróprias.

Por exemplo:

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de&profanityAction=Marked" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'This is an <expletive> good idea.'}]"

Essa solicitação retorna:

[
    {
        "translations":[
            {"text":"Das ist eine *** gute Idee.","to":"de"}
        ]
    }
]

Compara com:

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de&profanityAction=Marked&profanityMarker=Tag" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'This is an <expletive> good idea.'}]"

Essa última solicitação retorna:

[
    {
        "translations":[
            {"text":"Das ist eine <profanity>verdammt</profanity> gute Idee.","to":"de"}
        ]
    }
]

Traduzir conteúdo que inclui marcação

É comum traduzir conteúdo que inclui marcação, como conteúdo de uma página HTML ou conteúdo de um documento XML. Inclua o parâmetro de consulta textType=html ao traduzir conteúdo com marcas. Além disso, às vezes é útil excluir conteúdo específico da tradução. É possível usar o atributo class=notranslate para especificar o conteúdo que deve permanecer no idioma original. No exemplo a seguir, o conteúdo dentro do primeiro elemento div não será traduzido, enquanto o conteúdo no segundo elemento div será.

<div class="notranslate">This will not be translated.</div>
<div>This will be translated. </div>

Veja uma solicitação de exemplo para ilustrar.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=zh-Hans&textType=html" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'<div class=\"notranslate\">This will not be translated.</div><div>This will be translated.</div>'}]"

A resposta é:

[
    {
        "translations":[
            {"text":"<div class=\"notranslate\">This will not be translated.</div><div>这将被翻译。</div>","to":"zh-Hans"}
        ]
    }
]

Obter informações de alinhamento

O alinhamento é retornado como um valor de cadeia de caracteres do seguinte formato para cada palavra da fonte. As informações para cada palavra são separadas por um espaço, incluindo para idiomas não separados por espaço (scripts), como o chinês:

[[SourceTextStartIndex]:[SourceTextEndIndex]–[TgtTextStartIndex]:[TgtTextEndIndex]] *

Exemplo de cadeia de caracteres de alinhamento: "0:0-7:10 1:2-11:20 3:4-0:3 3:4-4:6 5:5-21:21".

Em outras palavras, os dois-pontos separam o índice inicial e final, o traço separa os idiomas e o espaço separa as palavras. Uma palavra pode ser alinhada com zero, uma ou várias palavras no outro idioma, e as palavras alinhadas podem ser não contíguas. Quando nenhuma informação de alinhamento estiver disponível, o elemento de alinhamento ficará vazio. Nesse caso, método não retornará nenhum erro.

Para receber informações de alinhamento, especifique includeAlignment=true na cadeia de caracteres de consulta.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=fr&includeAlignment=true" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'The answer lies in machine translation.'}]"

A resposta é:

[
    {
        "translations":[
            {
                "text":"La réponse se trouve dans la traduction automatique.",
                "to":"fr",
                "alignment":{"proj":"0:2-0:1 4:9-3:9 11:14-11:19 16:17-21:24 19:25-40:50 27:37-29:38 38:38-51:51"}
            }
        ]
    }
]

As informações de alinhamento iniciam com 0:2-0:1, significando que os três primeiros caracteres no texto de origem (The) são mapeados para os dois primeiros caracteres no texto traduzido (La).

Limitações

A obtenção de informações de alinhamento é um recurso experimental que habilitamos para pesquisa de prototipagem e experiências com possíveis mapeamentos de frases. Estas são algumas restrições dignas de nota quando alinhamentos não têm suporte:

• O alinhamento não está disponível para texto no formato HTML, ou seja, textType=html
• O alinhamento é retornado apenas para um subconjunto dos pares de idiomas:
  • Inglês de/para qualquer outro idioma, exceto chinês tradicional, cantonês (tradicional) ou sérvio (cirílico)
  • do japonês para o coreano ou do coreano para o japonês
  • do japonês para o chinês simplificado e do chinês simplificado para o japonês
  • de chinês simplificado para chinês tradicional e chinês tradicional para chinês simplificado
• Você não receberá o alinhamento se a sentença for uma tradução predefinida. Exemplo de uma tradução automática é This is a test, I love you, e outras frases de alta frequência
• O alinhamento não fica disponível quando você aplica uma das abordagens para impedir a tradução, conforme descrito aqui

Obter limites de sentença

Para receber informações sobre o comprimento da sentença no texto de origem e no texto traduzido, especifique includeSentenceLength=true na cadeia de caracteres de consulta.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=fr&includeSentenceLength=true" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'The answer lies in machine translation. The best machine translation technology cannot always provide translations tailored to a site or users like a human. Simply copy and paste a code snippet anywhere.'}]"

A resposta é:

[
    {
        "translations":[
            {
                "text":"La réponse se trouve dans la traduction automatique. La meilleure technologie de traduction automatique ne peut pas toujours fournir des traductions adaptées à un site ou des utilisateurs comme un être humain. Il suffit de copier et coller un extrait de code n'importe où.",
                "to":"fr",
                "sentLen":{"srcSentLen":[40,117,46],"transSentLen":[53,157,62]}
            }
        ]
    }
]

Traduzir com dicionário dinâmico

Se você já souber a tradução que deseja aplicar a uma palavra ou frase, poderá fornecê-la como marcação dentro da solicitação. O dicionário dinâmico só é seguro para nomes próprios, como nomes de pessoas e nomes de produtos. Observação: o recurso de dicionário dinâmico diferencia maiúsculas de minúsculas.

A marcação para fornecer usa a seguinte sintaxe.

<mstrans:dictionary translation="translation of phrase">phrase</mstrans:dictionary>

Por exemplo, considere a frase em inglês "A palavra wordomatic é uma entrada de dicionário." Para preservar a palavra wordomatic na tradução, envie a solicitação:

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'The word <mstrans:dictionary translation=\"wordomatic\">wordomatic</mstrans:dictionary> is a dictionary entry.'}]"

O resultado é:

[
    {
        "translations":[
            {"text":"Das Wort \"wordomatic\" ist ein Wörterbucheintrag.","to":"de"}
        ]
    }
]

Esse recurso de dicionário dinâmico funciona da mesma forma com textType=text ou com textType=html. O recurso deve ser usado com moderação. A maneira apropriada e muito melhor de personalizar a tradução é usando o Tradutor Personalizado. O Tradutor Personalizado faz uso total das probabilidades de estatística e contexto. Se você puder criar dados de treinamento que mostrem o trabalho ou a frase no contexto, obterá resultados melhores. Saiba mais sobre o Tradutor Personalizado.

Próximas etapas