Tradutor 3.0: Traduzir
Traduz texto.
URL do Pedido
Envie um pedido POST para:
https://api.cognitive.microsofttranslator.com/translate?api-version=3.0
Consulte Suporte de rede virtual para configuração e suporte de rede selecionada e ponto final privado e de rede selecionada.
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âmetro de consulta | Description |
|---|---|
| api-version | Parâmetro necessário. Versão da API solicitada pelo cliente. O valor deve ser 3.0. |
| para | Parâmetro necessário. Especifica o idioma do texto de saída. O idioma de destino deve ser um dos idiomas suportados incluídos no translation escopo. 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 | Description |
|---|---|
| de | Parâmetro opcional. Especifica o idioma do texto de entrada. Descubra quais idiomas estão disponíveis para tradução pesquisando os idiomas suportados usando o translation escopo. Se o parâmetro não for especificado, a from deteção automática de idioma será aplicada para determinar o idioma de origem. Você deve usar o from parâmetro em vez de deteção automática ao usar o recurso de dicionário dinâmico. Nota: 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. Este parâmetro é usado para obter traduções de um sistema personalizado construído com o Tradutor Personalizado. Para usar seu sistema personalizado implantado, adicione o ID da categoria dos detalhes do projeto do Tradutor personalizado ao parâmetro category. O valor padrão é: general. |
| palavrõesAção | Parâmetro opcional. Especifica como os palavrões devem ser tratados nas traduções. Os valores possíveis são: NoAction (padrão), Marked, ou Deleted. Para compreender formas de tratar os palavrões, consulte Manuseamento de palavrões. |
| profanityMarker | Parâmetro opcional. Especifica como os palavrões devem ser marcados nas traduções. Os valores possíveis são: Asterisk (padrão) ou Tag. Para compreender formas de tratar os palavrões, consulte Manuseamento de palavrões. |
| incluirAlinhamento | Parâmetro opcional. Especifica se a projeção de alinhamento deve ser incluída do texto de origem para o texto traduzido. Os valores possíveis são: true ou false (padrão). |
| includeSentenceLength | Parâmetro opcional. Especifica se os limites de frase devem ser incluídos para o texto de entrada e o texto traduzido. Os valores possíveis são: true ou false (padrão). |
| sugeridoDe | Parâmetro opcional. Especifica um idioma de fallback se o idioma do texto de entrada não puder ser identificado. A deteção automática de idioma é aplicada quando o from parâmetro é omitido. Se a deteção falhar, o suggestedFrom idioma será 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 retornar a 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 só deve utilizar sistemas treinados para o category especificado pelo pedido. Se uma tradução da língua X para a língua Y requer encadeamento através de uma linguagem pivot E, então todos os sistemas na cadeia (X → E e E → Y) precisam ser personalizados e ter a mesma categoria. Se nenhum sistema for encontrado com a categoria específica, a solicitação retornará um código de status 400. allowFallback=true Especifica que o serviço tem permissão para retornar a um sistema geral quando um sistema personalizado não existe. |
Os cabeçalhos de solicitação incluem:
| Cabeçalhos | Description |
|---|---|
| Cabeçalhos de autenticação | Cabeçalho de solicitação obrigatório. Consulte as 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 útil. O valor aceito é application/json; charset=UTF-8. |
| Comprimento do conteúdo | Opcional. O comprimento do corpo do pedido. |
| X-ClientTraceId | Opcional. Um GUID gerado pelo cliente para identificar exclusivamente a solicitação. Você pode omitir esse cabeçalho se incluir a ID de rastreamento na cadeia de caracteres de consulta usando um parâmetro de consulta chamado ClientTraceId. |
Corpo do pedido
O corpo da solicitação é uma matriz JSON. Cada elemento de matriz é um objeto JSON com uma propriedade string 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, consulte 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 result inclui as seguintes propriedades:
detectedLanguage: Um objeto que descreve o idioma detetado através das seguintes propriedades:language: Uma cadeia de caracteres que representa o código do idioma detetado.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
detectedLanguagepropriedade só está presente no objeto de resultado quando a deteção automática de idioma é solicitada.translations: Uma série de resultados de tradução. O tamanho da matriz corresponde ao número de idiomas de destino especificados através dotoparâmetro query. Cada elemento na matriz inclui:to: Uma cadeia de caracteres que representa o código do idioma do idioma de destino.text: Uma string que dá o texto traduzido.transliteration: Um objeto que fornece o texto traduzido no script especificado pelotoScriptparâmetro.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
transliterationobjeto não será incluído se a transliteração não ocorrer.alignment: Um objeto com uma única propriedade string chamadaproj, que mapeia o texto de entrada para o texto traduzido. As informações de alinhamento só são fornecidas quando o parâmetroincludeAlignmentrequest é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 no outro idioma, e as palavras alinhadas podem ser não contíguas. 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 inteira 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 inteira 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 frase só são incluídos quando o parâmetro
includeSentenceLengthrequest étrue.
sourceText: Um objeto com uma única propriedade string chamadatext, que fornece o texto de entrada no script padrão do idioma de origem.sourceTextpropriedade está presente somente quando a entrada é expressa em um script que não é o script usual para a linguagem. Por exemplo, se a entrada fosse escrita em árabe em alfabeto latino, entãosourceText.textseria o mesmo texto árabe convertido em alfabeto árabe.
Exemplos de respostas JSON são fornecidos na seção de exemplos .
Cabeçalhos de resposta
| Cabeçalhos | Description |
|---|---|
| X-solicitante | 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 que foi usado para tradução para cada idioma 'para' solicitado para tradução. O valor é uma lista de cadeias de caracteres separadas por vírgula. Cada string indica um tipo: Custom - Request inclui um sistema personalizado e pelo menos um sistema personalizado foi usado durante a tradução. Equipa - Todos os outros pedidos |
| Utilização com medição X | Especifica o consumo (o número de caracteres pelos quais o usuário é cobrado) para a solicitação de trabalho de tradução. Por exemplo, se a palavra "Olá" for traduzida do inglês (en) para o francês (fr), este campo devolverá o valor 5. |
Códigos de status de resposta
A seguir estão os possíveis códigos de status HTTP que uma solicitação retorna.
| Código de estado | Description |
|---|---|
| 200 | Êxito. |
| 400 | Um dos parâmetros de consulta está em falta ou não é válido. Corrija os parâmetros de solicitação antes de tentar novamente. |
| 401 | Não foi possível autenticar o pedido. Verifique se as credenciais são especificadas e válidas. |
| 403 | O pedido não está autorizado. Verifique a mensagem de erro de detalhes. 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á faltando. Verifique a mensagem de erro de detalhes. 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. O pedido deve ser repetido 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, informe-o com: data e hora da falha, identificador de solicitação do cabeçalho de resposta X-RequestId e identificador de cliente do cabeçalho de solicitação X-ClientTraceId. |
| 503 | Servidor temporariamente indisponível. Repita o pedido. Se o erro persistir, informe-o com: data e hora da falha, identificador de solicitação do cabeçalho de resposta X-RequestId e identificador de cliente do cabeçalho de solicitação X-ClientTraceId. |
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 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. Os 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 do único pedaço de texto na entrada.
Traduzir uma única entrada com deteção automática 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, usa-se a deteçã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 deteção automática de idioma foi solicitada, a resposta também inclui informações sobre o idioma detetado para o texto de entrada. A deteçã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. O seguinte pedido pede uma tradução chinesa escrita em alfabeto 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 dá o texto traduzido usando caracteres latinos.
Traduzir vários pedaços de texto
Traduzir várias cadeias de caracteres de uma só vez é 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 todos os pedaços de texto exatamente na mesma ordem que no pedido. 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"}
]
}
]
Lidar com palavrões
Normalmente, o serviço de Tradutor mantém palavrões que estão presentes na fonte na tradução. O grau de palavrões e o contexto que torna as palavras profanas diferem entre culturas e, como resultado, o grau de palavrões na língua-alvo pode ser amplificado ou reduzido.
Se você quiser evitar ficar com palavrões na tradução, independentemente da presença de palavrões no texto de origem, você pode usar a opção de filtragem de palavrões. A opção permite que você escolha se deseja ver os palavrões excluídos, marcados com tags apropriadas (dando-lhe 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 ação de palavrões aceito | Valor ProfanityMarker | Ação | Exemplo: Origem – Português | Exemplo: Destino – Inglês |
|---|---|---|---|---|
| NoAction | Predefinição. O mesmo que não definir a opção. A linguagem obscena é traduzida do texto de origem para o de destino. | Que coche de<inserir-profano-palavra> |
<Que carro de inserção-profana-palavra> | |
| Marcado | Asterisk | Asteriscos substituem palavras profanas (padrão). | Que coche de<inserir-profano-palavra> |
What a *** car |
| Marcado | Etiqueta | Palavras profanas> são cercadas por tags <XML, palavrões...</palavrões>. | Que coche de<inserir-profano-palavra> |
<Que carro de palavrões><insert-profane-word></profanity> |
| Eliminado | As palavras obscenas são removidas do texto traduzido sem serem substituídas. | Que coche de<inserir-profano-palavra> |
What a car |
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.'}]"
Este pedido devolve:
[
{
"translations":[
{"text":"Das ist eine *** gute Idee.","to":"de"}
]
}
]
Compare 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.'}]"
Este último pedido devolve:
[
{
"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 tags. 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 do 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 é devolvido como um valor de cadeia do seguinte formato para cada palavra da origem. As informações de 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]] *
Cadeia de alinhamento de exemplo: "0:0-7:10 1:2-11:20 3:4-0:3 3:4-4:6 5:5-21:21".
Por outras palavras, os dois pontos separam o índice de início e fim, 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 no outro idioma, e as palavras alinhadas podem ser não contíguas. Quando nenhuma informação de alinhamento está disponível, o elemento Alinhamento fica vazio. O método não devolve erros 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 do texto de partida (The) são mapeados para os dois primeiros caracteres do texto traduzido (La).
Limitações
A obtenção de informações de alinhamento é um recurso experimental que habilitamos para pesquisas de prototipagem e experiências com possíveis mapeamentos de frases. Aqui estão algumas das restrições notáveis em que os alinhamentos não são suportados:
- 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 se alinha se a frase for uma tradução enlatada. Exemplo de uma tradução enlatada é
This is a test,I love you, e 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 frase
Para receber informações sobre o comprimento da frase 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 já sabe a tradução que pretende aplicar a uma palavra ou expressão, pode fornecê-la como marcação no pedido. O dicionário dinâmico só é seguro para nomes próprios, como nomes pessoais e nomes de produtos. Nota: o recurso de dicionário dinâmico diferencia maiúsculas de minúsculas.
A marcação para fornecer 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 o pedido:
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"}
]
}
]
Este recurso de dicionário dinâmico funciona da mesma maneira com textType=text ou com textType=htmlo . 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 pleno do contexto e das probabilidades estatísticas. Se você puder criar dados de treinamento que mostrem seu trabalho ou frase no contexto, obterá melhores resultados. Saiba mais sobre o Tradutor Personalizado.