Compartilhar via

Tradutor 3.0: Idiomas

  • Artigo

Obtém o conjunto de idiomas atualmente compatíveis com outras operações do Tradutor.

URL da solicitação

Envie uma solicitação 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 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 de consulta Descrição
api-version Parâmetro obrigatório

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

Uma lista separada por vírgula de nomes que definem o grupo de idiomas a ser retornado. Os nomes de grupo permitidos são: translation, transliteration e dictionary. Se nenhum escopo é fornecido, todos os grupos são retornados, o que é equivalente a passar scope=translation,transliteration,dictionary.

Consulte o corpo da resposta.

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

Cabeçalhos Descrição
Accept-Language Cabeçalho de solicitação opcional.

O idioma a ser usado para cadeias de caracteres de interface do usuário. 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 marca de idioma 47 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 em 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 obtenção de recursos de idioma.

Corpo da resposta

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

  • scope=translation fornece os idiomas compatíveis para traduzir o texto de um idioma em outro;

  • scope=transliteration fornece as funcionalidades para converter o texto em um idioma de um script em outro;

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

Um cliente pode recuperar vários grupos simultaneamente especificando uma lista separada por vírgula de nomes. Por exemplo, scope=translation,transliteration,dictionary retorna os idiomas compatíveis com 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 de cada propriedade é mostrado a seguir.

  • Propriedade translation

    O valor da propriedade translation é um dicionário de pares (chave, valor). Cada chave é uma tag de BCP 47 idiomas. Uma chave identifica um idioma no qual o texto pode ser convertido ou traduzido. O valor associado à chave é um objeto JSON com propriedades que descrevem o idioma:

    • name: nome de exibição do idioma na localidade solicitada por meio do cabeçalho Accept-Language.

    • nativeName: nome de exibição do idioma na localidade nativa desse 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"
    },
    ...
  }
}

  • Propriedade transliteration

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

    • name: nome de exibição do idioma na localidade solicitada por meio do cabeçalho Accept-Language.

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

    • scripts: lista de scripts dos quais converter. Cada elemento da lista scripts tem propriedades:

      • code: código que identifica o script.

      • name: nome de exibição do script na localidade solicitada por meio do cabeçalho Accept-Language.

      • 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 nos quais converter o texto. Cada elemento da lista toScripts 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"
            }
          ]
        }
      ]
    },
    ...
  }
}

  • Propriedade dictionary

    O valor da propriedade dictionary é um dicionário de pares (chave, valor). Cada chave é uma tag de BCP 47 idiomas. A chave identifica um idioma para o qual traduções alternativas e traduções reversas estão disponíveis. 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 por meio do cabeçalho Accept-Language.

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

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

    • translations: lista de idiomas com traduções alternativas e exemplos para a consulta expressa no idioma de origem. Cada elemento da lista translations tem propriedades:

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

      • nativeName: nome de exibição do idioma de destino na localidade nativa do 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 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 ser alterada ao longo do tempo, porque o Microsoft Translator estende continuamente a lista de idiomas compatíveis com seus serviços.

A lista de idiomas compatíveis não é alterada 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 dos recursos de idioma e da marca da entidade correspondente (ETag). Em seguida, o aplicativo cliente pode periodicamente (por exemplo, uma vez a cada 24 horas) consultar o serviço para buscar o último conjunto de idiomas compatíveis. Passar o valor ETag atual em um campo de cabeçalho If-None-Match 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 Descrição
ETag Valor atual da marca da entidade para os grupos solicitados de idiomas compatíveis. Para tornar as solicitações seguintes mais eficientes, o cliente pode enviar o valor ETag em um campo de cabeçalho If-None-Match.
X-RequestId Valor gerado pelo serviço para identificar a solicitação. É usado para fins de solução de problemas.

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.
304 O recurso não é modificado e se alinha com a versão especificada pelos cabeçalhos de If-None-Matchsolicitação.
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.
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

O exemplo a seguir mostra como recuperar os idiomas compatíveis para a tradução de texto.

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