Tradutor do Azure nas Ferramentas de Pesquisa 3.0: Traduzir

Converte texto.

URL de solicitação

Envie uma solicitação POST para:

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

Consultesuporte de rede virtual para tradução de rede selecionada e configuração de ponto de extremidade privado e suporte.

Parâmetros de 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 de matriz é um objeto JSON com uma propriedade de cadeia de caracteres chamada 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, consulteOs limites de solicitação.

Corpo da resposta

Uma resposta bem-sucedida é 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 que indica a confiança no resultado. A pontuação está entre zero e um e uma pontuação baixa indica uma baixa confiança.

  A detectedLanguage propriedade só está presente no objeto de resultado quando a autodetecção de linguagem é 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 to parâmetro de consulta. Cada elemento na matriz inclui:

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

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

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

    • script: uma cadeia de caracteres que especifica o script de destino.

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

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

    • alignment: um objeto com uma única propriedade de cadeia de caracteres chamada proj, que mapeia o texto de entrada para o texto traduzido. As informações de alinhamento só são fornecidas quando o parâmetro includeAlignment de solicitação é 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 se alinhar com zero, uma ou várias palavras na outra linguagem, e as palavras alinhadas podem ser nãotiguosas. Quando nenhuma informação de alinhamento está disponível, o elemento de alinhamento está vazio. Consulte Obter informações de alinhamento para obter um exemplo e restrições.

  • sentLen: um objeto que retorna limites de frase nos textos de entrada e saída.

    • srcSentLen: uma matriz de inteiros que representa os comprimentos das frases no texto de entrada. O comprimento da matriz é o número de frases e os valores são o comprimento de cada frase.

    • transSentLen: uma matriz de inteiros que representa os comprimentos das frases no texto traduzido. O comprimento da matriz é o número de frases e os valores são o comprimento de cada frase.

    Os limites de sentença só são incluídos quando o parâmetro includeSentenceLength de solicitação é true.

• sourceText: um objeto com uma única propriedade de cadeia de caracteres chamada text, que fornece o texto de entrada no script padrão do idioma de origem. sourceText a propriedade está presente somente 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 script latino, seria sourceText.text o mesmo texto árabe convertido em script árabe.

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

Cabeçalhos de resposta

Códigos de status de resposta

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

Se ocorrer um erro, a solicitação retornará uma resposta de erro JSON. O código de erro é um número de 6 dígitos combinando 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 erro comuns podem ser encontrados na página de referência do Tradutor v3.

Exemplos

Traduzir uma única entrada

Este exemplo mostra como traduzir uma única frase do inglês para o 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 translations matriz inclui um elemento, que fornece a tradução da única parte do texto na entrada.

Traduzir uma única entrada com a autodeteção de idioma

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

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 autodeteção de idioma foi solicitada, a resposta também inclui informações sobre o idioma detectado para o texto de entrada. A autodeteção 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 solicita uma tradução em chinês escrita em script latino.

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 transliteration propriedade, que fornece o texto traduzido usando caracteres latinos.

Traduzir várias partes de texto

Traduzir várias cadeias de caracteres ao mesmo tempo é simplesmente uma questão de especificar uma matriz de cadeias 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 de 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"}
        ]
    }
]

Manipular palavrões

Normalmente, o Tradutor retém palavrões que estão presentes na origem na 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 na linguagem de destino pode ser amplificado ou reduzido.

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

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

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.'}]"

Esta solicitação retorna:

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

Comparar 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 textType=html de consulta ao traduzir conteúdo com marcas. Além disso, às vezes é útil excluir conteúdo específico da tradução. Você pode usar o atributo class=notranslate para especificar o conteúdo que deve permanecer em seu idioma original. No exemplo a seguir, o conteúdo dentro do primeiro div elemento não é traduzido, enquanto o conteúdo no segundo div elemento é traduzido.

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

Aqui está 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 origem. As informações de cada palavra são separadas por um espaço, inclusive para idiomas separados por espaço (scripts) como 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 se alinhar com zero, uma ou várias palavras na outra linguagem, e as palavras alinhadas podem ser nãotiguosas. Quando nenhuma informação de alinhamento está disponível, o elemento Alignment está vazio. O método não retorna nenhum erro nesse caso.

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 começam com 0:2-0:1, o que significa 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

Obter informações de alinhamento é um recurso experimental que habilitamos para a criação de pesquisas e experiências com mapeamentos de frases em potencial. Aqui estão algumas das restrições notáveis em que não há suporte para alinhamentos:

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

Obter limites de sentença

Para receber informações sobre o comprimento da frase no texto de origem e o 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 substantivos adequados, como nomes pessoais e nomes de produtos. Observação: o recurso de dicionário dinâmico diferencia maiúsculas de minúsculas.

A marcação a ser fornecida usa a sintaxe a seguir.

<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 maneira 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 do contexto e das probabilidades estatísticas. Se você puder criar dados de treinamento que mostram seu trabalho ou frase no contexto, obterá melhores resultados. Saiba mais sobre o Tradutor Personalizado.

Próximas etapas