Démarrage rapide : API REST Azure AI Traducteur

Essayez la version d’Azure AI Traducteur la plus récente. Dans ce guide de démarrage rapide, commencez à utiliser le service Traducteur pour traduire du texte avec le langage de programmation de votre choix ou l’API REST. Pour ce projet, nous vous recommandons d’utiliser le niveau tarifaire gratuit (F0), pendant votre apprentissage de la technologie, puis d’effectuer une mise à niveau vers un niveau payant pour la production.

Prérequis

Vous avez besoin d’un abonnement Azure actif. Si vous n’avez pas d’abonnement Azure, vous pouvez en créer un gratuitement.

• Une fois que vous avez votre abonnement Azure, créez une ressource Traducteur dans le Portail Azure.

• Une fois votre ressource déployée, sélectionnez Accéder à la ressource et récupérez votre clé et votre point de terminaison.

  • Vous aurez besoin de la clé et du point de terminaison de la ressource pour connecter votre application au service Translator. Vous insérez votre clé et votre point de terminaison dans le code plus loin dans ce guide de démarrage rapide. Vous pouvez trouver ces valeurs sur la page Clés et Points de terminaison du portail Azure :

    

    Notes

    • Pour ce guide de démarrage rapide, il est recommandé d’utiliser une ressource globale monoservice Traduction de texte Translator Text.
    • En utilisant une ressource globale monoservice, vous incluez un en-tête d’autorisation (Ocp-Apim-Subscription-key) avec la requête d’API REST. La valeur d’Ocp-Apim-Subscription-Key est votre clé secrète Azure pour votre abonnement Traduction de texte Translator Text.
    • Si vous choisissez d’utiliser une ressource Azure AI Traducteur multiservice ou régionale, deux en-têtes d’authentification sont nécessaires : (Ocp-Api-Subscription-Key et Ocp-Apim-Subscription-Region). La valeur d’Ocp-Apim-Subscription-Region est la région associée à votre abonnement.
    • Pour plus d’informations sur l’utilisation de l’en-tête Ocp-Apim-Subscription-Region, consultez En-têtes de l’API REST de traduction de texte.

En-têtes

Pour appeler le service Traducteur via l’API REST, vous devez inclure les en-têtes suivants avec chaque requête. Ne vous inquiétez pas, nous incluons les en-têtes pour vous dans l’exemple de code de chaque langage de programmation.

Pour plus d’informations sur les options d’authentification Traducteur, consultez le guide de référence Traducteur v3.

En-tête	Valeur	Condition
Ocp-Apim-Subscription-Key	Votre clé de service Traducteur à partir du Portail Azure.	• Obligatoire
Ocp-Apim-Subscription-Region	Région dans laquelle votre ressource a été créée.	• Obligatoire pour l’utilisation d’une ressource Azure AI multiservice ou régionale (géographique) comme USA Ouest. • Facultatif pour l’utilisation d’une ressource Traducteur globale mono-service.
Content-Type	Type de contenu de la charge utile. Les valeurs acceptées sont application/json ou charset=UTF-8.	• Obligatoire
Content-Length	Longueur du corps de la demande.	• Facultatif

Important

N’oubliez pas de supprimer la clé de votre code une fois que vous avez terminé, et ne la postez jamais publiquement. Pour la production, utilisez un moyen sécurisé de stocker et d’accéder à vos informations d’identification comme Azure Key Vault. Pour plus d’informations, consultez l’article Sécurité des Azure AI services.

Traduire le texte

Traduire du texte est l’opération fondamentale du service Traducteur. Dans ce guide de démarrage rapide, vous générez une requête à l’aide d’un langage de programmation de votre choix qui prend une seule source (from) et fournit deux sorties (to). Ensuite, nous examinons quelques paramètres que vous pouvez utiliser pour ajuster à la fois la requête et la réponse.

Pour plus d’informations sur les limites d’une requête au service Azure AI Traducteur, consultez Limites d’une requête de traduction de texte.

C# : Visual Studio

Configurer votre projet Visual Studio

1. Vérifiez que la version actuelle de Visual Studio IDE est installée.

   Conseil

   Si vous débutez avec Visual Studio, essayez le module Learn Introduction à Visual Studio.

2. Ouvrez Visual Studio.

3. Dans la page de démarrage, choisissez Créer un projet.

   

4. Dans la page Créer un nouveau projet, entrez console dans la zone de recherche. Choisissez le modèle Application console, puis choisissez Suivant.

   

5. Dans la fenêtre de dialogue Configurer votre nouveau projet, entrez translator_quickstart dans la zone Nom de projet. Laissez la case à cocher « Placer la solution et le projet dans le même répertoire » désactivée, puis sélectionnez Suivant.

   

6. Dans la fenêtre de dialogue Informations supplémentaires, vérifiez que .NET 6.0 (Support à long terme) est sélectionné. Laissez la case à cocher « Ne pas utiliser d’instructions de niveau supérieur » décochée et sélectionnez Créer.

   

Installer le package Newtonsoft.json avec NuGet

1. Cliquez avec le bouton droit sur votre projet translator_quickstart et sélectionnez Gérer les packages NuGet.

   

2. Sélectionnez l’onglet Parcourir et tapez Newtonsoft.json.

   

3. Pour ajouter le package à votre projet, sélectionnez Installer dans la fenêtre du gestionnaire de package appropriée.

   

Générer votre application C#

Notes

• À compter de .NET 6, de nouveaux projets utilisant le modèle console génèrent un nouveau style de programme qui diffère des versions précédentes.
• La nouvelle sortie utilise des fonctionnalités C# récentes qui simplifient le code que vous devez écrire.
• Lorsque vous utilisez la version la plus récente, vous devez uniquement écrire le corps de la Main méthode. Vous n’avez pas besoin d’inclure des instructions de niveau supérieur, des directives globales à l’aide de directives ou des directives implicites.
• Pour plus d’informations, consultez Les nouveaux modèles C# génèrent des instructions de plus haut niveau.

1. Ouvrez le fichier Program.cs.

2. Supprimez le code existant, y compris la ligne Console.WriteLine("Hello World!"). Copiez et collez les exemples de code dans le fichier Program.cs de votre application. Veillez à mettre à jour la variable de clé avec la valeur de votre instance Traducteur du Portail Azure :

using System.Text;
using Newtonsoft.Json;

class Program
{
    private static readonly string key = "<your-translator-key>";
    private static readonly string endpoint = "https://api.cognitive.microsofttranslator.com";

    // location, also known as region.
    // required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    private static readonly string location = "<YOUR-RESOURCE-LOCATION>";

    static async Task Main(string[] args)
    {
        // Input and output languages are defined as parameters.
        string route = "/translate?api-version=3.0&from=en&to=fr&to=zu";
        string textToTranslate = "I would really like to drive your car around the block a few times!";
        object[] body = new object[] { new { Text = textToTranslate } };
        var requestBody = JsonConvert.SerializeObject(body);

        using (var client = new HttpClient())
        using (var request = new HttpRequestMessage())
        {
            // Build the request.
            request.Method = HttpMethod.Post;
            request.RequestUri = new Uri(endpoint + route);
            request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json");
            request.Headers.Add("Ocp-Apim-Subscription-Key", key);
            // location required if you're using a multi-service or regional (not global) resource.
            request.Headers.Add("Ocp-Apim-Subscription-Region", location);

            // Send the request and get response.
            HttpResponseMessage response = await client.SendAsync(request).ConfigureAwait(false);
            // Read response as a string.
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}

Exécuter votre application C#

Une fois que vous ajoutez un exemple de code à votre application, choisissez le bouton de démarrage vert à côté de formRecognizer_quickstart pour générer et exécuter votre programme, ou appuyez sur F5.

Sortie de la traduction :

Quand l’appel aboutit, vous devez voir la réponse suivante :

[
    {
        "detectedLanguage": {
            "language": "en",
            "score": 1.0
        },
        "translations": [
            {
                "text": "J'aimerais vraiment conduire votre voiture autour du pâté de maisons plusieurs fois!",
                "to": "fr"
            },
            {
                "text": "Ngingathanda ngempela ukushayela imoto yakho endaweni evimbelayo izikhathi ezimbalwa!",
                "to": "zu"
            }
        ]
    }
]

Go

Configurer votre environnement Go

Vous pouvez utiliser n’importe quel éditeur de texte pour écrire des applications Go. Nous vous recommandons d’utiliser la dernière version de Visual Studio Code et l’extension Go.

Conseil

Si vous débutez avec Go, essayez le module Learn Prise en main de Go.

1. Vérifiez que la dernière version de Go est installée :

   • Téléchargez la version de langage de programmation Go pour votre système d’exploitation.

   • Une fois le téléchargement terminé, exécutez le programme d’installation.

   • Ouvrez une invite de commandes et entrez ce qui suit pour confirmer que Go a été installé :

       go version
     

Générer votre application Go

1. Dans une fenêtre de console (par exemple, cmd, PowerShell ou Bash), créez le répertoire translator-app pour votre application et accédez-y.

2. Créez un fichier GO nommé translation.go à partir du répertoire translator-app.

3. Copiez et collez l’exemple de code fourni dans votre fichier translation.go. Veillez à mettre à jour la variable de clé avec la valeur de votre instance Traducteur du Portail Azure :

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "log"
    "net/http"
    "net/url"
)

func main() {
    key := "<YOUR-TRANSLATOR-KEY>"
    endpoint := "https://api.cognitive.microsofttranslator.com/"
    uri := endpoint + "/translate?api-version=3.0"

    // location, also known as region.
    // required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    location := "<YOUR-RESOURCE-LOCATION>"

    // Build the request URL. See: https://go.dev/pkg/net/url/#example_URL_Parse
    u, _ := url.Parse(uri)
    q := u.Query()
    q.Add("from", "en")
    q.Add("to", "fr")
    q.Add("to", "zu")
    u.RawQuery = q.Encode()

    // Create an anonymous struct for your request body and encode it to JSON
    body := []struct {
        Text string
    }{
        {Text: "I would really like to drive your car around the block a few times."},
    }
    b, _ := json.Marshal(body)

    // Build the HTTP POST request
    req, err := http.NewRequest("POST", u.String(), bytes.NewBuffer(b))
    if err != nil {
        log.Fatal(err)
    }
    // Add required headers to the request
    req.Header.Add("Ocp-Apim-Subscription-Key", key)
    // location required if you're using a multi-service or regional (not global) resource.
    req.Header.Add("Ocp-Apim-Subscription-Region", location)
    req.Header.Add("Content-Type", "application/json")

    // Call the Translator API
    res, err := http.DefaultClient.Do(req)
    if err != nil {
        log.Fatal(err)
    }

    // Decode the JSON response
    var result interface{}
    if err := json.NewDecoder(res.Body).Decode(&result); err != nil {
        log.Fatal(err)
    }
    // Format and print the response to terminal
    prettyJSON, _ := json.MarshalIndent(result, "", "  ")
    fmt.Printf("%s\n", prettyJSON)
}

Exécuter votre application Go

Une fois que vous avez ajouté un exemple de code à votre application, votre programme Go peut être exécuté dans une invite de commandes ou de terminal. Vérifiez que le chemin d’accès de votre invite est défini sur le dossier translator-app et utilisez la commande suivante :

 go run translation.go

Sortie de la traduction :

Quand l’appel aboutit, vous devez voir la réponse suivante :

[
    {
        "detectedLanguage": {
            "language": "en",
            "score": 1.0
        },
        "translations": [
            {
                "text": "J'aimerais vraiment conduire votre voiture autour du pâté de maisons plusieurs fois!",
                "to": "fr"
            },
            {
                "text": "Ngingathanda ngempela ukushayela imoto yakho endaweni evimbelayo izikhathi ezimbalwa!",
                "to": "zu"
            }
        ]
    }
]

Java: Gradle

Configurer votre environnement Java

• Vous devez utiliser la dernière version de Visual Studio Code ou de votre IDE préféré. Consultez Java dans Visual Studio Code.

  Conseil

  • Visual Studio Code offre un pack de programmation pour Java pour Windows et macOS. Le pack de programmation est un bundle de VS Code, le Kit de développement Java (JDK) et une collection d’extensions suggérées par Microsoft. Le Pack de programmation peut également être utilisé pour corriger un environnement de développement existant.
  • Si vous utilisez VS Code et le Pack de programmation pour Java, installez l’extension Gradle pour Java.

• Si vous n’utilisez pas Visual Studio Code, vérifiez que les éléments suivants sont installés dans votre environnement de développement :

  • Un Kit de développement Java (OpenJDK), version 8 ou ultérieure.

  • Gradle, version 6.8 ou ultérieure.

Créer un projet Gradle

1. Dans une fenêtre de console (par exemple, cmd, PowerShell ou Bash), créez le répertoire translator-text-app pour votre application et accédez-y.

   mkdir translator-text-app && translator-text-app
   

    mkdir translator-text-app; cd translator-text-app
   

2. Exécutez la commande gradle init à partir du répertoire translator-text-app. Cette commande crée des fichiers de build essentiels pour Gradle, notamment build.gradle.kts, qui est utilisé au moment de l’exécution pour créer et configurer votre application.

   gradle init --type basic
   

3. Quand vous êtes invité à choisir un DSL, sélectionnez Kotlin.

4. Acceptez le nom du projet par défaut (translator-text-app) en sélectionnant Retour ou Entrée.

5. Mettez à jour build.gradle.kts à l’aide du code suivant :

plugins {
  java
  application
}
application {
  mainClass.set("TranslatorText")
}
repositories {
  mavenCentral()
}
dependencies {
  implementation("com.squareup.okhttp3:okhttp:4.10.0")
  implementation("com.google.code.gson:gson:2.9.0")
}

Créer votre application Java

1. À partir du répertoire translator-text-app, exécutez la commande suivante :

   mkdir -p src/main/java
   

   Vous créez la structure de répertoires suivante :

   

2. Accédez au répertoire java et créez un fichier nommé TranslatorText.java.

   Conseil

   • Vous pouvez créer un nouveau fichier à l’aide de PowerShell.

   • Ouvrez une fenêtre PowerShell dans le répertoire de votre projet en maintenant la touche Maj enfoncée et en cliquant avec le bouton droit sur le dossier.

   • Tapez la commande New-Item TranslatorText.java.

   • Vous pouvez également créer un fichier dans votre IDE nommé TranslatorText.java et l’enregistrer dans le répertoire java.

3. Ouvrez le fichier TranslatorText.java dans votre IDE, puis copiez l’exemple de code suivant et collez-le dans votre application. Veillez à mettre à jour la clé avec l’une des valeurs de clé de votre instance de Portail Azure Traducteur :

import java.io.IOException;

import com.google.gson.*;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class TranslatorText {
    private static String key = "<your-translator-key";

    // location, also known as region.
   // required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    private static String location = "<YOUR-RESOURCE-LOCATION>";


    // Instantiates the OkHttpClient.
    OkHttpClient client = new OkHttpClient();

    // This function performs a POST request.
    public String Post() throws IOException {
        MediaType mediaType = MediaType.parse("application/json");
        RequestBody body = RequestBody.create(mediaType,
                "[{\"Text\": \"I would really like to drive your car around the block a few times!\"}]");
        Request request = new Request.Builder()
                .url("https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=fr&to=zu")
                .post(body)
                .addHeader("Ocp-Apim-Subscription-Key", key)
                // location required if you're using a multi-service or regional (not global) resource.
                .addHeader("Ocp-Apim-Subscription-Region", location)
                .addHeader("Content-type", "application/json")
                .build();
        Response response = client.newCall(request).execute();
        return response.body().string();
    }

    // This function prettifies the json response.
    public static String prettify(String json_text) {
        JsonParser parser = new JsonParser();
        JsonElement json = parser.parse(json_text);
        Gson gson = new GsonBuilder().setPrettyPrinting().create();
        return gson.toJson(json);
    }

    public static void main(String[] args) {
        try {
            TranslatorText translateRequest = new TranslatorText();
            String response = translateRequest.Post();
            System.out.println(prettify(response));
        } catch (Exception e) {
            System.out.println(e);
        }
    }
}

Générer et exécuter votre application Java

Une fois que vous avez ajouté un exemple de code à votre application, revenez à votre répertoire de projet principal (translator-text-app), ouvrez une fenêtre de console et entrez les commandes suivantes :

1. Générez votre application avec la commande build :

   gradle build
   

2. Exécutez votre application avec la commande run :

   gradle run
   

Sortie de la traduction :

Quand l’appel aboutit, vous devez voir la réponse suivante :

[
  {
    "translations": [
      {
        "text": "J'aimerais vraiment conduire votre voiture autour du pâté de maisons plusieurs fois!",
        "to": "fr"
      },
      {
        "text": "Ngingathanda ngempela ukushayela imoto yakho endaweni evimbelayo izikhathi ezimbalwa!",
        "to": "zu"
      }
    ]
  }
]

JavaScript : Node.js

Configurer votre projet Node.js Express

1. Vérifiez que la dernière version de Node.js est installée. Node Package Manager (npm) est inclus dans l’installation Node.js.

   Conseil

   Si vous débutez avec Node.js, essayez le module Learn Introduction à Node.js.

2. Dans une fenêtre de console (par exemple, cmd, PowerShell ou Bash), créez un répertoire translator-app pour votre application et accédez-y.

       mkdir translator-app && cd translator-app
   

     mkdir translator-app; cd translator-app
   

3. Exécutez la commande npm init pour initialiser l’application et échafauder votre projet.

      npm init
   

4. Spécifiez les attributs de votre projet à l’aide des invites qui s’affichent dans le terminal.

   • Les attributs les plus importants sont le nom, le numéro de version et le point d’entrée.
   • Nous vous recommandons de conserver index.js comme nom du point d’entrée. La description, la commande de test, le référentiel GitHub, les mots clés, l’auteur et les informations de licence sont des attributs facultatifs. Vous pouvez les ignorer pour ce projet.
   • Acceptez les suggestions entre parenthèses en sélectionnant Retour ou Entrée.
   • Une fois que vous avez répondu aux invites, un fichier package.json est créé dans votre répertoire translator-app.

5. Ouvrez une fenêtre de console et utilisez npm pour installer la bibliothèque HTTP axios et le package uuid :

      npm install axios uuid
   

6. Créez le fichier index.js dans le répertoire de l’application.

   Conseil

   • Vous pouvez créer un nouveau fichier à l’aide de PowerShell.

   • Ouvrez une fenêtre PowerShell dans le répertoire de votre projet en maintenant la touche Maj enfoncée et en cliquant avec le bouton droit sur le dossier.

   • Tapez la commande New-Item index.js.

   • Vous pouvez également créer un fichier nommé index.js dans votre IDE et l’enregistrer dans le répertoire translator-app.

Générer votre application JavaScript

Ajoutez l’exemple code suivant à votre fichier index.js. Veillez à mettre à jour la variable de clé avec la valeur de votre instance Traducteur du Portail Azure :

    const axios = require('axios').default;
    const { v4: uuidv4 } = require('uuid');

    let key = "<your-translator-key>";
    let endpoint = "https://api.cognitive.microsofttranslator.com";

    // location, also known as region.
    // required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    let location = "<YOUR-RESOURCE-LOCATION>";

    axios({
        baseURL: endpoint,
        url: '/translate',
        method: 'post',
        headers: {
            'Ocp-Apim-Subscription-Key': key,
             // location required if you're using a multi-service or regional (not global) resource.
            'Ocp-Apim-Subscription-Region': location,
            'Content-type': 'application/json',
            'X-ClientTraceId': uuidv4().toString()
        },
        params: {
            'api-version': '3.0',
            'from': 'en',
            'to': 'fr,zu'
        },
        data: [{
            'text': 'I would really like to drive your car around the block a few times!'
        }],
        responseType: 'json'
    }).then(function(response){
        console.log(JSON.stringify(response.data, null, 4));
    })

Exécuter votre application JavaScript

Une fois que vous avez ajouté l’exemple de code à votre application, exécutez votre programme :

1. Accédez à votre répertoire d’application (translator-app).

2. Tapez la commande suivante dans votre terminal :

   node index.js
   

Sortie de la traduction :

Quand l’appel aboutit, vous devez voir la réponse suivante :

[
    {
        "translations": [
            {
                "text": "J'aimerais vraiment conduire votre voiture autour du pâté de maisons plusieurs fois!",
                "to": "fr"
            },
            {
                "text": "Ngingathanda ngempela ukushayela imoto yakho endaweni evimbelayo izikhathi ezimbalwa!",
                "to": "zu"
            }
        ]
    }
]

Python

Configurer votre projet Python

1. Vérifiez que la dernière version de Python 3.x est installée. Le package d’installation Python (pip) est inclus dans l’installation de Python.

   Conseil

   Si vous débutez avec Python, essayez le module Learn Introduction à Python.

2. Ouvrez une fenêtre de terminal et utilisez pip pour installer la bibliothèque Requests et le package uuid0 :

      pip install requests uuid
   

   Notes

   Nous allons également utiliser un package intégré Python appelé json. Il est utilisé pour utiliser des données JSON.

Générer votre application Python

1. Créez une application Python nommée translator-app.py dans votre éditeur ou IDE favori.

2. Ajoutez l’exemple code suivant à votre fichier translator-app.py. Veillez à mettre à jour la clé avec l’une des valeurs de votre instance Translator du Portail Azure.

import requests, uuid, json

# Add your key and endpoint
key = "<your-translator-key>"
endpoint = "https://api.cognitive.microsofttranslator.com"

# location, also known as region.
# required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
location = "<YOUR-RESOURCE-LOCATION>"

path = '/translate'
constructed_url = endpoint + path

params = {
    'api-version': '3.0',
    'from': 'en',
    'to': ['fr', 'zu']
}

headers = {
    'Ocp-Apim-Subscription-Key': key,
    # location required if you're using a multi-service or regional (not global) resource.
    'Ocp-Apim-Subscription-Region': location,
    'Content-type': 'application/json',
    'X-ClientTraceId': str(uuid.uuid4())
}

# You can pass more than one object in body.
body = [{
    'text': 'I would really like to drive your car around the block a few times!'
}]

request = requests.post(constructed_url, params=params, headers=headers, json=body)
response = request.json()

print(json.dumps(response, sort_keys=True, ensure_ascii=False, indent=4, separators=(',', ': ')))

Exécuter votre application Python

Une fois que vous avez ajouté un exemple de code à votre application, générez et exécutez votre programme :

1. Accédez à votre fichier translator-app.py.

2. Tapez la commande suivante dans votre console :

   python translator-app.py
   

Sortie de la traduction :

Quand l’appel aboutit, vous devez voir la réponse suivante :

[
  {
    "translations": [
      {
        "text": "J'aimerais vraiment conduire votre voiture autour du pâté de maisons plusieurs fois!",
        "to": "fr"
      },
      {
        "text": "Ngingathanda ngempela ukushayela imoto yakho endaweni evimbelayo izikhathi ezimbalwa!",
        "to": "zu"
      }
    ]
  }
]

Étapes suivantes

Voilà, félicitations ! Vous venez d’apprendre à utiliser le service Traducteur pour traduire du texte.

Explorez notre documentation pratique et découvrez plus en détail les fonctionnalités du service Traduction :

• Traduire du texte

• Translittérer du texte

• Détecter et identifier le langage

• Obtenir la longueur de phrase

• Recherche dans le dictionnaire et autres traductions