Translator 3.0 : Languages

  • Article

Permet d’obtenir l’ensemble des langues actuellement prises en charge par d’autres opérations de Translator.

URL de la demande

Envoyez une demande GET à :

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

ConsultezPrise en charge de réseau virtuel du service Translator sélectionné pour la configuration et la prise en charge du point de terminaison privé et du réseau.

Paramètres de la demande

Les paramètres de demande transmis à la chaîne de requête sont les suivants :

Paramètres de requête Description
api-version Paramètre obligatoire

La version de l’API demandée par le client. La valeur doit être 3.0.
scope Paramètre facultatif.

Liste de noms séparée par des virgules définissant le groupe de langues à renvoyer. Les noms de groupe autorisés sont les suivants : translation, transliteration et dictionary. Si aucune étendue n’est fournie, tous les groupes sont renvoyés, ce qui équivaut à transmettre scope=translation,transliteration,dictionary.

Consultezcorps de réponse.

Les en-têtes de requête sont les suivants :

headers Description
Accept-Language En-tête de requête facultatif.

Langue à utiliser pour les chaînes de l’interface utilisateur. Certains des champs dans cette réponse sont les noms de langue ou de région. Utilisez ce paramètre pour définir la langue dans laquelle ces noms sont renvoyés. La langue est spécifiée en fournissant une balise de langue BCP 47 bien formée. Par exemple, utilisez la valeur fr pour demander des noms en français, ou la valeur zh-Hant pour demander des noms en chinois traditionnel.
Les noms sont fournis en anglais lorsqu’aucune langue cible n’est indiquée ou lorsqu’aucune traduction n’est pas disponible.
X-ClientTraceId En-tête de requête facultatif.
GUID généré par le client pour identifier de façon unique la demande.

L’authentification n’est pas nécessaire pour obtenir les ressources de langue.

Response body

Un client utilise le paramètre de requête scope pour définir les groupes de langues qui l’intéresse.

  • scope=translation fournit les langues prises en charge pour traduire le texte d’une langue dans une autre.

  • scope=transliteration fournit des fonctions de conversion de texte dans une langue, d’un script à l’autre.

  • scope=dictionary fournit des paires de langues pour lesquelles les opérations Dictionary renvoient des données.

Un client peut récupérer plusieurs groupes simultanément en indiquant une liste de noms séparée par des virgules. Par exemple, scope=translation,transliteration,dictionary peut renvoyer les langues prises en charge pour tous les groupes.

Une réponse correcte est un objet JSON avec une propriété pour chaque groupe demandé :

{
    "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)
    }
}

La valeur de chaque propriété prend la forme suivante.

  • Propriété translation

    La valeur de la propriété translation est un dictionnaire composé de paires (clé, valeur). Chaque clé est une balise de langue BCP 47. Une clé identifie une langue pour laquelle du texte peut être traduit de ou vers une autre langue. La valeur associée à cette clé est un objet JSON avec des propriétés décrivant la langue :

    • name: nom d’affichage de la langue dans les paramètres régionaux demandés via l’en-tête Accept-Language.

    • nativeName: nom d’affichage de la langue dans les paramètres régionaux natifs de cette langue.

    • dir: sens de l’écriture, rtl pour les langues qui se lisent de droite à gauche, ou ltr pour les langues qui se lisent de gauche à droite.

    Voici un exemple :

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

  • Propriété transliteration

    La valeur de la propriété transliteration est un dictionnaire composé de paires (clé, valeur). Chaque clé est une balise de langue BCP 47. Une clé identifie une langue pour laquelle du texte peut être converti d’un script à l’autre. La valeur associée à cette clé est un objet JSON avec des propriétés décrivant la langue et ses scripts pris en charge :

    • name: nom d’affichage de la langue dans les paramètres régionaux demandés via l’en-tête Accept-Language.

    • nativeName: nom d’affichage de la langue dans les paramètres régionaux natifs de cette langue.

    • scripts: liste de scripts à partir desquels exécuter la conversion. Chaque élément de la liste scripts possède des propriétés :

      • code: code identifiant le script.

      • name: nom d’affichage du script dans les paramètres régionaux demandés via l’en-tête Accept-Language.

      • nativeName: nom d’affichage de la langue dans les paramètres régionaux natifs de cette langue.

      • dir: sens de l’écriture, rtl pour les langues qui se lisent de droite à gauche, ou ltr pour les langues qui se lisent de gauche à droite.

      • toScripts: liste de scripts disponibles en lesquels convertir le texte. Chaque élément de la liste toScripts possède des propriétés code, name, nativeName et dir, comme décrit précédemment.

    Voici un exemple :

    {
  "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"
            }
          ]
        }
      ]
    },
    ...
  }
}

  • Propriété dictionary

    La valeur de la propriété dictionary est un dictionnaire composé de paires (clé, valeur). Chaque clé est une balise de langue BCP 47. La clé identifie une langue pour laquelle d’autres traductions et des traductions inverses sont disponibles. La valeur est un objet JSON qui décrit la langue source et les langues cibles avec les traductions disponibles :

    • name: nom d’affichage de la langue source dans les paramètres régionaux demandés via l’en-tête Accept-Language.

    • nativeName: nom d’affichage de la langue dans les paramètres régionaux natifs de cette langue.

    • dir: sens de l’écriture, rtl pour les langues qui se lisent de droite à gauche, ou ltr pour les langues qui se lisent de gauche à droite.

    • translations: liste de langues avec des traductions alternatives et des exemples pour la requête exprimée en langue source. Chaque élément de la liste translations possède des propriétés :

      • name: nom d’affichage de la langue cible dans les paramètres régionaux demandés via l’en-tête Accept-Language.

      • nativeName: nom d’affichage de la langue cible dans les paramètres régionaux natifs de cette langue.

      • dir: sens de l’écriture, rtl pour les langues qui se lisent de droite à gauche, ou ltr pour les langues qui se lisent de gauche à droite.

      • code: code de langue identifiant la langue cible.

    Voici un exemple :

    "es": {
  "name": "Spanish",
  "nativeName": "Español",
  "dir": "ltr",
  "translations": [
    {
      "name": "English",
      "nativeName": "English",
      "dir": "ltr",
      "code": "en"
    }
  ]
},

La structure de l’objet de réponse n’évolue pas sans modification de la version de l’API. Pour la même version de l’API, la liste des langues disponibles peut évoluer au fil du temps, car Microsoft Translator étoffe en permanence la liste des langues prises en charge par ses services.

La liste des langues prises en charge ne change pas souvent. Pour économiser de la banque passante et améliorer les temps de réponse, mieux vaut envisager une application cliente qui met en cache les ressources de langue et la balise de l’entité correspondante (ETag). Par la suite, l’application cliente peut interroger le service de manière périodique (par exemple, une fois toutes les 24 heures) afin de récupérer le jeu de langues prises en charge le plus récent. Le transfert de la valeur actuelle ETag dans un champ d’en-tête If-None-Match permet au service d’optimiser la réponse. Si la ressource n’a pas été modifiée, le service renvoie un code d’état 304 et un corps de réponse vide.

En-têtes de réponse

headers Description
ETag Valeur actuelle de la balise d’entité pour les groupes de langues prises en charge demandés. Pour effectuer d’autres demandes plus efficaces, le client peut envoyer la valeur ETag dans un champ d’en-tête If-None-Match.
X-RequestId Valeur générée par le service pour identifier la demande. Elle sert à des fins de dépannage.

Codes d’état de réponse

Voici les codes d’état HTTP qu’une demande peut retourner.

Code d’état Description
200 Réussite.
304 La ressource n’a pas été modifiée depuis la version indiquée par les en-têtes de requête If-None-Match.
400 L’un des paramètres de requête est manquant ou non valide. Corrigez les paramètres de demande avant de réessayer.
429 Le serveur a rejeté la requête, car le client a dépassé les limites de requête.
500 Une erreur inattendue s’est produite. Si l’erreur persiste, signalez-la en fournissant les informations suivantes : date et heure de la défaillance, identificateur de la demande dans l’en-tête de réponse,X-RequestId et identificateur du client dans l’en-tête de demande X-ClientTraceId.
503 Serveur temporairement indisponible. Relancez la requête. Si l’erreur persiste, signalez-la en fournissant les informations suivantes : date et heure de la défaillance, identificateur de la demande dans l’en-tête de réponse,X-RequestId et identificateur du client dans l’en-tête de demande X-ClientTraceId.

Si une erreur se produit, la requête renvoie également une réponse d'erreur JSON. Le code d’erreur est un nombre à 6 chiffres qui combine le code d’état HTTP à 3 chiffres et un nombre à 3 chiffres qui sert à catégoriser plus précisément l’erreur. Vous trouverez les codes d’erreur les plus courants sur la page Référence de Translator v3.

Exemples

L’exemple suivant montre comment récupérer les langues prises en charge pour la traduction du texte.

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