Partilhar via

Tradutor 3.0: Idiomas

  • Artigo

Obtém o conjunto de idiomas atualmente suportados por outras operações do Tradutor.

URL do Pedido

Envie um pedido GET para:

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

Para redes virtuais, use seu ponto de extremidade de domínio personalizado:

https://<your-custom-domain>.cognitiveservices.azure.com/languages?api-version=3.0

Para obter mais informações, consulte Suporte de rede virtual para serviço de tradutor selecionado configuração e suporte de rede e ponto final privado.

Parâmetros de solicitação

Os parâmetros de solicitação passados na cadeia de caracteres de consulta são:

Parâmetros de consultas Description
api-version Parâmetro necessário

A versão da API solicitada pelo cliente. O valor deve ser 3.0.
âmbito Parâmetro opcional.

Uma lista separada por vírgulas de nomes que definem o grupo de idiomas a serem retornados. Os nomes de grupo permitidos são: translation, transliteratione dictionary. Se nenhum escopo for dado, todos os grupos serão retornados, o que equivale a passar scope=translation,transliteration,dictionary.

Ver corpo da resposta.

Os cabeçalhos de solicitação são:

Cabeçalhos Description
Accept-Language Cabeçalho de solicitação 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. Use esse parâmetro para definir o idioma no qual esses nomes são retornados. O idioma é especificado fornecendo uma tag de 47 idiomas bem formada BCP . Por exemplo, use o valor fr para solicitar nomes em francês ou use o valor zh-Hant para solicitar 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 solicitação opcional.
Um GUID gerado pelo cliente para identificar exclusivamente a solicitação.

A autenticação não é necessária para obter recursos linguísticos.

Corpo da resposta

Um cliente usa o scope parâmetro query para definir quais grupos de idiomas listar.

  • scope=translation fornece idiomas suportados para traduzir texto de um idioma para outro;

  • scope=transliteration fornece recursos para converter texto em um idioma de um script para outro;

  • scope=dictionary Fornece pares de idiomas para os quais Dictionary as operações retornam dados.

Um cliente pode recuperar vários grupos simultaneamente especificando uma lista de nomes separados por vírgula. Por exemplo, scope=translation,transliteration,dictionary retornaria idiomas suportados para todos os grupos.

Uma resposta bem-sucedida é um objeto JSON com uma propriedade para cada grupo solicitado:

{
    "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 para cada propriedade é o seguinte.

  • translation propriedade

    O valor da translation propriedade é um dicionário de pares (chave, valor). Cada tecla é uma etiqueta de BCP 47 idiomas. 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 a linguagem:

    • name: Nome de exibição do idioma na localidade solicitada via Accept-Language cabeçalho.

    • nativeName: Nome de exibição do idioma na localidade nativa para este idioma.

    • dir: Direcionalidade, que é rtl para idiomas da direita para a esquerda ou ltr para idiomas da esquerda para a direita.

    Um exemplo é:

    {
  "translation": {
    ...
    "fr": {
      "name": "French",
      "nativeName": "Français",
      "dir": "ltr"
    },
    ...
  }
}

  • transliteration propriedade

    O valor da transliteration propriedade é um dicionário de pares (chave, valor). Cada tecla é uma etiqueta de BCP 47 idiomas. Uma chave identifica um idioma para o qual o texto pode ser convertido de um script para outro. O valor associado à chave é um objeto JSON com propriedades que descrevem a linguagem e seus scripts suportados:

    • name: Nome de exibição do idioma na localidade solicitada via Accept-Language cabeçalho.

    • nativeName: Nome de exibição do idioma na localidade nativa para este idioma.

    • scripts: Lista de scripts para converter. Cada elemento da scripts lista tem propriedades:

      • code: Código que identifica o script.

      • name: Nome de exibição do script na localidade solicitada via Accept-Language cabeçalho.

      • nativeName: Nome de exibição do idioma na localidade nativa do idioma.

      • dir: Direcionalidade, que é rtl para idiomas da direita para a esquerda ou ltr para idiomas da esquerda para a direita.

      • toScripts: Lista de scripts disponíveis para converter texto. Cada elemento da toScripts lista tem propriedades code, name, nativeName, e dir 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 propriedade

    O valor da dictionary propriedade é um dicionário de pares (chave, valor). Cada tecla é uma etiqueta de BCP 47 idiomas. A chave identifica uma língua para a qual estão disponíveis traduções e retrotraduções alternativas. O valor é um objeto JSON que descreve o idioma de origem e os idiomas de destino com traduções disponíveis:

    • name: Nome de exibição do idioma de origem na localidade solicitada via Accept-Language cabeçalho.

    • nativeName: Nome de exibição do idioma na localidade nativa para este idioma.

    • dir: Direcionalidade, que é rtl para idiomas da direita para a esquerda ou ltr para idiomas da esquerda para a direita.

    • translations: Lista de línguas com traduções alterativas e exemplos para a consulta expressa na língua de partida. Cada elemento da translations lista tem propriedades:

      • name: Nome de exibição do idioma de destino na localidade solicitada via Accept-Language cabeçalho.

      • nativeName: Nome de exibição do idioma de destino na localidade nativa para o idioma de destino.

      • dir: Direcionalidade, que é rtl para idiomas da direita para a esquerda ou ltr para idiomas da esquerda para a direita.

      • code: Código linguístico que identifica a língua de chegada.

    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 muda 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 porque o Microsoft Translator estende continuamente a lista de idiomas suportados pelos seus serviços.

A lista de idiomas suportados não muda com frequência. Para economizar largura de banda de rede e melhorar a capacidade de resposta, um aplicativo cliente deve considerar o armazenamento em cache de recursos de idioma e a marca de entidade correspondente (ETag). Em seguida, o aplicativo cliente pode consultar periodicamente (por exemplo, uma vez a cada 24 horas) o serviço para buscar o conjunto mais recente de idiomas suportados. Passar o valor atual ETag em um If-None-Match campo de cabeçalho permite que o serviço otimize a resposta. Se o recurso não for modificado, o serviço retornará o código de status 304 e um corpo de resposta vazio.

Cabeçalhos de resposta

Cabeçalhos Description
ETag Valor atual da marca de entidade para os grupos solicitados de idiomas suportados. Para tornar as solicitações subsequentes mais eficientes, o cliente pode enviar o ETag valor em um If-None-Match campo de cabeçalho.
X-RequestId Valor gerado pelo serviço para identificar a solicitação. Ele é usado para fins de solução de problemas.

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.
304 O recurso não é modificado e está alinhado com a versão especificada pelos cabeçalhos de If-None-Matchsolicitação.
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.
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 X-RequestIdda resposta e identificador do cliente do cabeçalho X-ClientTraceIdda solicitação.
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 X-RequestIdda resposta e identificador do cliente do cabeçalho X-ClientTraceIdda solicitação.

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. Os códigos de erro comuns podem ser encontrados na página de referência do Tradutor V3.

Exemplos

O exemplo a seguir mostra como recuperar idiomas suportados para tradução de texto.

curl "https://api.cognitive.microsofttranslator.com/languages?api-version=3.0&scope=translation"