Tradutor 3.0: Idiomas

  • Artigo

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, transliteratione 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 quais Dictionary 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 propriedade

    O 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çalho Accept-Language .

    • nativeName: nome a apresentar do idioma na região nativa deste idioma.

    • dir: Direcionalidade, que se destina rtl a 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 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çalho Accept-Language .

    • nativeName: nome a apresentar do idioma na região nativa deste idioma.

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

      • code: Código que identifica o script.

      • name: nome a apresentar do script na região pedida por cabeçalho Accept-Language .

      • nativeName: nome a apresentar do idioma na região nativa do idioma.

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

      • toScripts: lista de scripts disponíveis para converter texto em. Cada elemento da toScripts lista tem as propriedades code, name, nativeNamee 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 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çalho Accept-Language .

    • nativeName: nome a apresentar do idioma na região nativa deste idioma.

    • dir: Direcionalidade, que se destina rtl a idiomas da direita para a esquerda ou ltr 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 da translations lista tem propriedades:

      • name: nome a apresentar do idioma de destino na região pedida por cabeçalho Accept-Language .

      • nativeName: nome a apresentar do idioma de destino na região nativa do idioma de destino.

      • dir: Direcionalidade, que se destina rtl a 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 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-Matchde 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-RequestIdde resposta e identificador do cliente do cabeçalho X-ClientTraceIddo 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-RequestIdde resposta e identificador do cliente do cabeçalho X-ClientTraceIddo 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"