Tradutor 3.0: Idiomas
Obtém o conjunto de idiomas atualmente suportado por outras operações do Tradutor.
URL do Pedido
Envie um pedido GET
para:
https://api.cognitive.microsofttranslator.com/languages?api-version=3.0
ConsulteRede Virtual Suporte para o suporte e configuração de pontos finais privados e de rede selecionados do serviço Translator.
Parâmetros do pedido
Os parâmetros de pedido transmitidos na cadeia de consulta são:
Parâmetros de consulta | Description |
---|---|
api-version | Parâmetro obrigatório A versão da API pedida pelo cliente. O valor tem de ser 3.0 . |
scope | Parâmetro opcional. Uma lista separada por vírgulas de nomes que definem o grupo de idiomas a devolver. Os nomes de grupos permitidos são: translation , transliteration e dictionary . Se não for dado nenhum âmbito, todos os grupos serão devolvidos, o que equivale a transmitir scope=translation,transliteration,dictionary . |
Veja ocorpo da resposta.
Os cabeçalhos do pedido são:
Cabeçalhos | Description |
---|---|
Accept-Language | Cabeçalho de pedido opcional. O idioma a utilizar nas cadeias da interface de utilizador. Alguns dos campos na resposta são nomes de idiomas ou nomes de regiões. Utilize este parâmetro para definir o idioma no qual estes nomes são devolvidos. O idioma é especificado ao fornecer uma etiqueta de idioma BCP 47 bem formada. Por exemplo, utilize o valor fr para pedir nomes em francês ou utilize o valor zh-Hant para pedir nomes em Chinês Tradicional.Os nomes são fornecidos no idioma inglês quando um idioma de destino não é especificado ou quando a localização não está disponível. |
X-ClientTraceId | Cabeçalho de pedido opcional. Um GUID gerado pelo cliente para identificar exclusivamente o pedido. |
A autenticação não é necessária para obter recursos de idioma.
Corpo da resposta
Um cliente utiliza o scope
parâmetro de consulta para definir em que grupos de idiomas está interessado.
scope=translation
fornece idiomas suportados para traduzir texto de um idioma para outro idioma;scope=transliteration
fornece capacidades para converter texto num idioma de um script para outro script;scope=dictionary
fornece pares de idiomas para os quaisDictionary
as operações devolvem dados.
Um cliente pode obter vários grupos em simultâneo ao especificar uma lista de nomes separada por vírgulas. Por exemplo, scope=translation,transliteration,dictionary
devolveria idiomas suportados para todos os grupos.
Uma resposta bem-sucedida é um objeto JSON com uma propriedade para cada grupo pedido:
{
"translation": {
//... set of languages supported to translate text (scope=translation)
},
"transliteration": {
//... set of languages supported to convert between scripts (scope=transliteration)
},
"dictionary": {
//... set of languages supported for alternative translations and examples (scope=dictionary)
}
}
O valor de cada propriedade é o seguinte.
translation
propriedadeO valor da
translation
propriedade é um dicionário de pares (chave, valor). Cada chave é uma etiqueta de idioma BCP 47. Uma chave identifica um idioma para o qual o texto pode ser traduzido ou traduzido. O valor associado à chave é um objeto JSON com propriedades que descrevem o idioma:name
: nome a apresentar do idioma na região pedido por cabeçalhoAccept-Language
.nativeName
: nome a apresentar do idioma na região nativa deste idioma.dir
: Direcionalidade, que se destinartl
a idiomas da direita para a esquerda oultr
para idiomas da esquerda para a direita.
Um exemplo é:
{ "translation": { ... "fr": { "name": "French", "nativeName": "Français", "dir": "ltr" }, ... } }
transliteration
propriedadeO valor da
transliteration
propriedade é um dicionário de pares (chave, valor). Cada chave é uma etiqueta de idioma BCP 47. Uma chave identifica um idioma para o qual o texto pode ser convertido de um script para outro script. O valor associado à chave é um objeto JSON com propriedades que descrevem o idioma e os scripts suportados:name
: nome a apresentar do idioma na região pedido por cabeçalhoAccept-Language
.nativeName
: nome a apresentar do idioma na região nativa deste idioma.scripts
: Lista de scripts para converter. Cada elemento dascripts
lista tem propriedades:code
: Código que identifica o script.name
: nome a apresentar do script na região pedida por cabeçalhoAccept-Language
.nativeName
: nome a apresentar do idioma na região nativa do idioma.dir
: Direcionalidade, que se destinartl
a idiomas da direita para a esquerda oultr
para idiomas da esquerda para a direita.toScripts
: lista de scripts disponíveis para converter texto em. Cada elemento datoScripts
lista tem as propriedadescode
,name
,nativeName
edir
, conforme descrito anteriormente.
Um exemplo é:
{ "transliteration": { ... "ja": { "name": "Japanese", "nativeName": "日本語", "scripts": [ { "code": "Jpan", "name": "Japanese", "nativeName": "日本語", "dir": "ltr", "toScripts": [ { "code": "Latn", "name": "Latin", "nativeName": "ラテン語", "dir": "ltr" } ] }, { "code": "Latn", "name": "Latin", "nativeName": "ラテン語", "dir": "ltr", "toScripts": [ { "code": "Jpan", "name": "Japanese", "nativeName": "日本語", "dir": "ltr" } ] } ] }, ... } }
dictionary
propriedadeO valor da
dictionary
propriedade é um dicionário de pares (chave, valor). Cada chave é uma etiqueta de idioma BCP 47. A chave identifica um idioma para o qual estão disponíveis traduções alternativas e traduções anteriores. O valor é um objeto JSON que descreve o idioma de origem e os idiomas de destino com traduções disponíveis:name
: nome a apresentar do idioma de origem na região pedida por cabeçalhoAccept-Language
.nativeName
: nome a apresentar do idioma na região nativa deste idioma.dir
: Direcionalidade, que se destinartl
a idiomas da direita para a esquerda oultr
para idiomas da esquerda para a direita.translations
: lista de idiomas com traduções alterativas e exemplos para a consulta expressa no idioma de origem. Cada elemento datranslations
lista tem propriedades:name
: nome a apresentar do idioma de destino na região pedida por cabeçalhoAccept-Language
.nativeName
: nome a apresentar do idioma de destino na região nativa do idioma de destino.dir
: Direcionalidade, que se destinartl
a idiomas da direita para a esquerda oultr
para idiomas da esquerda para a direita.code
: código de idioma que identifica o idioma de destino.
Um exemplo é:
"es": { "name": "Spanish", "nativeName": "Español", "dir": "ltr", "translations": [ { "name": "English", "nativeName": "English", "dir": "ltr", "code": "en" } ] },
A estrutura do objeto de resposta não é alterada sem uma alteração na versão da API. Para a mesma versão da API, a lista de idiomas disponíveis pode mudar ao longo do tempo, uma vez que o Microsoft Translator alarga continuamente a lista de idiomas suportados pelos respetivos serviços.
A lista de idiomas suportados não muda frequentemente. Para guardar a largura de banda de rede e melhorar a capacidade de resposta, uma aplicação cliente deve considerar a colocação em cache de recursos de linguagem e a etiqueta de entidade correspondente (ETag
). Em seguida, a aplicação cliente pode consultar periodicamente (por exemplo, uma vez a cada 24 horas) o serviço para obter o conjunto mais recente de idiomas suportados. Transmitir o valor atual ETag
num If-None-Match
campo de cabeçalho permite ao serviço otimizar a resposta. Se o recurso não tiver sido modificado, o serviço devolve o código de estado 304 e um corpo de resposta vazio.
Cabeçalhos de resposta
Cabeçalhos | Description |
---|---|
ETag | Valor atual da etiqueta de entidade para os grupos pedidos de idiomas suportados. Para tornar os pedidos subsequentes mais eficientes, o cliente pode enviar o ETag valor num If-None-Match campo de cabeçalho. |
X-RequestId | Valor gerado pelo serviço para identificar o pedido. É utilizado para fins de resolução de problemas. |
Códigos de estado de resposta
Seguem-se os possíveis códigos de estado HTTP devolvidos por um pedido.
Código de Estado | Description |
---|---|
200 | Com êxito. |
304 | O recurso não foi modificado desde a versão especificada pelos cabeçalhos If-None-Match de pedido. |
400 | Um dos parâmetros de consulta está em falta ou não é válido. Corrija os parâmetros do pedido antes de tentar novamente. |
429 | O servidor rejeitou o pedido porque o cliente excedeu os limites de pedidos. |
500 | Ocorreu um erro inesperado. Se o erro persistir, comunique-o com: data e hora da falha, identificador do pedido do cabeçalho X-RequestId de resposta e identificador do cliente do cabeçalho X-ClientTraceId do pedido . |
503 | Servidor temporariamente indisponível. Repita o pedido. Se o erro persistir, comunique-o com: data e hora da falha, identificador do pedido do cabeçalho X-RequestId de resposta e identificador do cliente do cabeçalho X-ClientTraceId do pedido . |
Se ocorrer um erro, o pedido também devolve uma resposta de erro JSON. O código de erro é um número de 6 dígitos que combina o código de estado HTTP de 3 dígitos seguido de 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
O exemplo seguinte mostra como obter idiomas suportados para tradução de texto.
curl "https://api.cognitive.microsofttranslator.com/languages?api-version=3.0&scope=translation"