Tradutor 3.0: Idiomas

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:

Consulte o corpo da resposta.

Os cabeçalhos de solicitação sã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

Códigos de status de resposta

Veja a seguir os possíveis códigos de status HTTP retornados por uma 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. 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"