Compartilhar via

Tradutor 3.0: Tradução

  • Artigo

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âmetro de consulta Descrição
api-version Parâmetro obrigatório.
Versão da API solicitada pelo cliente. O valor precisa ser 3.0.
como Parâmetro obrigatório.
Especifica o idioma do texto de saída. O idioma de destino deve ser um dos idiomas com suporte incluídos no escopo translation. Por exemplo, use to=de para traduzir para alemão.
É possível traduzir para vários idiomas simultaneamente, repetindo o parâmetro na cadeia de caracteres de consulta. Por exemplo, use to=de&to=it para traduzir para alemão e italiano.

Parâmetros opcionais

Parâmetro de consulta Descrição
de Parâmetro opcional.
Especifica o idioma do texto de entrada. Localize quais idiomas estão disponíveis para tradução, consultando idiomas com suporte usando o escopo translation. Se o parâmetro from não for especificado, a detecção automática de idioma será aplicada para determinar o idioma de origem.

É necessário usar o parâmetro from em vez da detecção automática ao usar o recurso de dicionário dinâmico. Observação: o recurso de dicionário dinâmico diferencia maiúsculas de minúsculas.
textType Parâmetro opcional.
Define se o texto que está sendo traduzido é texto sem formatação ou texto HTML. Qualquer HTML precisa ser um elemento bem formado e completo. Os valores possíveis são: plain (padrão) ou html.
category Parâmetro opcional.
Uma cadeia de caracteres especificando a categoria (domínio) da tradução. Esse parâmetro é usado para obter traduções de um sistema personalizado compilado com Tradutor Personalizado. Para usar o sistema personalizado implantado, adicione a ID da categoria dos detalhes do projeto do Tradutor Personalizado ao parâmetro de categoria. O valor padrão é: general.
profanityAction Parâmetro opcional.
Especifica como os conteúdos ofensivos devem ser tratados nas traduções. Os valores possíveis são: NoAction (padrão), Marked, ou Deleted. Para reconhecer maneiras de tratar conteúdo ofensivo, consulte Tratamento de conteúdo ofensivo.
profanityMarker Parâmetro opcional.
Especifica como os conteúdos ofensivos devem ser marcados nas traduções. Os valores possíveis são: Asterisk (padrão) ou Tag. Para reconhecer maneiras de tratar conteúdo ofensivo, consulte Tratamento de conteúdo ofensivo.
includeAlignment Parâmetro opcional.
Especifica se deve incluir a projeção de alinhamento do texto de origem para texto traduzido. Os valores possíveis são: true ou false (padrão).
includeSentenceLength Parâmetro opcional.
Especifica se deve incluir limites de sentença para o texto de entrada e o texto traduzido. Os valores possíveis são: true ou false (padrão).
suggestedFrom Parâmetro opcional.
Especifica um idioma de fallback se o idioma do texto de entrada não pode ser identificado. A detecção automática de idioma é aplicada quando o parâmetro from é omitido. Se a detecção falhar, o idioma suggestedFrom é assumido.
fromScript Parâmetro opcional.
Especifica o script do texto de entrada.
toScript Parâmetro opcional.
Especifica o script do texto traduzido.
allowFallback Parâmetro opcional.
Especifica que o serviço tem permissão para fazer fallback para um sistema geral quando um sistema personalizado não existe. Os valores possíveis são: true (padrão) ou false.

allowFallback=false especifica que a tradução deve usar somente sistemas treinados para o category especificado pela solicitação. Se uma tradução do idioma X para a o idioma Y requer encadeamento por meio de um idioma dinâmico E, todos os sistemas da cadeia (X → E and E → Y) precisam ser personalizados e ter a mesma categoria. Se nenhum sistema for encontrado com a categoria específica, a solicitação retorna um código de 400 status. allowFallback=true especifica que o serviço tem permissão para fazer fallback para um sistema geral quando um sistema personalizado não existe.

Os cabeçalhos de solicitação incluem:

Cabeçalhos Descrição
Cabeçalhos de autenticação Cabeçalho de solicitação obrigatório.
Veja Opções disponíveis para autenticação.
Tipo de conteúdo Cabeçalho de solicitação obrigatório.
Especifica o tipo de conteúdo da carga.
O valor aceito é application/json; charset=UTF-8.
Content-Length Opcional.
O tamanho do corpo da solicitação.
X-ClientTraceId Opcional.
Um GUID gerado pelo cliente para identificar exclusivamente a solicitação. É possível omitir esse cabeçalho se incluir a ID de rastreamento na cadeia de caracteres de consulta usando um parâmetro de consulta nomeado ClientTraceId.

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

Cabeçalhos Descrição
X-requestid Valor gerado pelo serviço para identificar a solicitação usada para fins de solução de problemas.
Sistema-X-mt Especifica o tipo de sistema usado para tradução para cada idioma de destino solicitado para tradução. O valor é uma lista separada por vírgulas de cadeia de caracteres. Cada cadeia de caracteres indica um tipo:

Personalizado – a solicitação inclui um sistema personalizado e, no mínimo, um sistema personalizado foi usado durante a tradução.
Equipe – todas as outras solicitações
X-metered-usage Especifica o consumo (o número de caracteres para os quais o usuário é cobrado) para a solicitação de trabalho de tradução. Por exemplo, se a palavra “Hello” for traduzida de inglês (en) para francês (fr), esse campo retorna o valor 5.

Códigos de status de resposta

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

Código de status Descrição
200 Êxito.
400 Um dos parâmetros de consulta está ausente ou não é válido. Corrija os parâmetros de solicitação antes de tentar novamente.
401 A solicitação não pôde ser autenticada. Verifique se as credenciais estão especificadas e são válidas.
403 A solicitação não está autorizada. Verifique os detalhes da mensagem de erro. Esse código de status geralmente indica que você usou todas as traduções gratuitas fornecidas com uma assinatura de avaliação.
408 A solicitação não pôde ser atendida porque um recurso está ausente. Verifique os detalhes da mensagem de erro. Quando a solicitação inclui uma categoria personalizada, esse código de status geralmente indica que o sistema de tradução personalizado ainda não está disponível para atender solicitações. A solicitação deve ser repetida após um período de espera (por exemplo, 1 minuto).
429 O servidor rejeitou a solicitação porque o cliente excedeu os limites de solicitação.
500 Erro inesperado. Se o erro persistir, relate-o com: data e hora da falha, identificador da solicitação do cabeçalho de resposta X-RequestId e identificador do cliente do cabeçalho de solicitação X-ClientTraceId.
503 Servidor temporariamente não disponível. Tente novamente a solicitação. Se o erro persistir, relate-o com: data e hora da falha, identificador da solicitação do cabeçalho de resposta X-RequestId e identificador do cliente do cabeçalho de solicitação X-ClientTraceId.

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

Valor de ProfanityAction aceito Valor de ProfanityMarker Ação Exemplo: Origem – Espanhol Exemplo: Destino - Inglês
NoAction Padrão. O mesmo que não configurar a opção. A linguagem obscena passa do texto de origem para o texto de destino. Que coche de<insert-profane-word> Que carro <insert-profane-word>
Marked Asterisk Os asteriscos substituem as palavras impróprias (padrão). Que coche de<insert-profane-word> Que carro ***
Marked Marca As palavras impróprias são cercadas por marcas XML <profanity>...</profanity>. Que coche de<insert-profane-word> Que carro <profanity><insert-profane-word></profanity>
Excluído Palavras impróprias são removidas da saída sem substituição. Que coche de<insert-profane-word> Que carro

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

Experimentar o Guia de início rápido do Tradutor