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
ConfiraSuporte à Rede Virtual para ver a configuração e o suporte de ponto de extremidade privado e de rede selecionado do serviço de Tradução.
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 category. 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), Markedou 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 | Cabeçalho de solicitação obrigatório. 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, confiraLimites 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
detectedLanguagesomente 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 consultato. 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âmetrotoScript.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
transliterationnão será incluído se a transliteração não ocorrer.alignment: um objeto com uma única propriedade de cadeia de caracteres nomeadaproj, 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çãoincludeAlignmentfortrue. 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
includeSentenceLengthfortrue.
sourceText: um objeto com uma única propriedade de cadeia de caracteres nomeadatext, que fornece o texto de entrada no script padrão do idioma de origem.sourceTexta 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ãosourceText.textseria o mesmo texto árabe convertido em escrita á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 na língua-alvo 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).
| ProfanityAction | Ação |
|---|---|
NoAction |
NoAction é o comportamento padrão. A linguagem obscena passa do texto de origem para o texto de destino. Example Source (japonês): 彼はジャッカスです。 Tradução de exemplo (português): Ele é um filho da---. |
Deleted |
Palavras impróprias são removidas da saída sem substituição. Example Source (japonês): 彼はジャッカスです。 Tradução de exemplo (português): Ele é um ** |
Marked |
Um marcador substitui a palavra marcada na saída. O marcador depende do parâmetro ProfanityMarker. Para ProfanityMarker=Asterisk, as palavras profanas são substituídas por ***: Example Source (japonês): 彼はジャッカスです。 Tradução de exemplo (português): Ele é um \\\*. Para ProfanityMarker=Tag, palavras profanas são cercadas por marcas <XML palavrões e </palavrões>>:Example Source (japonês): 彼はジャッカスです。 Exemplo de tradução (português): ele é um <obsceno>filho da---</obsceno>. |
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 possibilitamos para pesquisas de prototipagem e experiências com mapeamentos de frases potenciais. 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 só é retornado 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
- de japonês para chinês simplificado e chinês simplificado para japonês
- do chinês simplificado ao chinês tradicional e do chinês tradicional ao chinês simplificado
- Você não receberá o alinhamento se a sentença for uma tradução predefinida. Exemplo de uma tradução enlatada é
This is a test,I love youe 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.