Partager via

Conteneur : Traduire du texte

  • Article

Traduisez du texte.

URL de la demande

Envoyez une demande POST à :

POST http://localhost:{port}/translate?api-version=3.0&&from={from}&to={to}

Exemple de requête

curl -x POST "https:localhost:5000/translate?api-version=3.0&from=en&to=es" -H "Content-Type: application/json" -d "[{
'Text': 'I would really like to drive your car.'}]"

Exemple de réponse

[
  {
    "translations": [
      {
        "text": "Realmente me gustaría conducir su coche.",
        "to": "es"
      }
    ]
  }
]

Paramètres de la demande

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

Paramètres obligatoires

Paramètre de requête. Description Condition
api-version Version de l’API demandée par le client. La valeur doit être 3.0. Paramètre obligatoire
from Spécifie la langue du texte d’entrée. Paramètre obligatoire
à Spécifie la langue du texte de sortie. Par exemple, utilisez to=de pour traduire en allemand.
Il est possible de traduire en plusieurs langues simultanément en répétant le paramètre dans la chaîne de requête. Par exemple, utilisez to=de&to=it pour traduire en allemand et italien.		 Paramètre obligatoire

Paramètres facultatifs

Paramètre de requête. Description
textType Paramètre facultatif.
Définit si le texte en cours de traduction est au format texte brut ou HTML. Tout code HTML doit être un élément bien formé et complet. Les valeurs possibles sont : plain (par défaut) ou html.
includeSentenceLength Paramètre facultatif.
Spécifie s’il faut inclure des limites de longueur de phrase aux texte d’entrée et au texte traduit. Les valeurs possibles sont true ou false (par défaut).

En-têtes de requête

En-têtes Description Condition
En-têtes d’authentification Consultez les options disponibles pour l’authentification. En-tête de requête obligatoire
Type de contenu Spécifie le type de contenu de la charge utile.
La valeur acceptée est application/json; charset=UTF-8.		 En-tête de requête obligatoire
Content-Length Longueur du corps de la demande. Facultatif
X-ClientTraceId GUID généré par le client pour identifier de façon unique la demande. Vous pouvez omettre cet en-tête si vous incluez l’ID de trace dans la chaîne de requête à l’aide d’un paramètre de requête appelé ClientTraceId. Facultatif

Corps de la demande

Le corps de la demande est un tableau JSON. Chaque élément du tableau est un objet JSON avec une propriété de chaîne nommée Text, qui représente la chaîne à traduire.

[
    {"Text":"I would really like to drive your car around the block a few times."}
]

Les limites suivantes s'appliquent :

  • Le tableau ne peut pas compter plus de 100 éléments.
  • L’intégralité du texte inclus dans la demande ne peut pas dépasser 50 000 caractères, espaces comprises.

Response body

Une réponse correcte est un tableau JSON avec un résultat pour chaque chaîne dans le tableau d’entrée. Un objet de résultat inclut les propriétés suivantes :

  • translations: tableau des résultats de la traduction. La taille du tableau correspond au nombre de langues cibles spécifié par le paramètre de requête to. Chaque élément dans le tableau inclut ce qui suit :

  • to: chaîne représentant le code de langue de la langue cible.

  • text: chaîne fournissant le texte traduit.

  • sentLen: objet retournant les limites de longueur de phrase dans les textes d’entrée et de sortie.

  • srcSentLen: tableau d’entiers représentant les longueurs des phrases dans le texte d’entrée. La longueur du tableau correspond au nombre de phrases, et les valeurs sont les longueurs des phrases.

  • transSentLen : tableau d’entiers représentant les longueurs des phrases dans le texte traduit. La longueur du tableau correspond au nombre de phrases, et les valeurs sont les longueurs des phrases.

    Les limites de longueur de phrase ne sont incluses que si le paramètre de requête includeSentenceLength est true.

    • sourceText: objet avec une propriété de chaîne unique nommée text, qui fournit le texte d’entrée dans le script par défaut de la langue source. La propriété sourceText est présente uniquement quand l’entrée est exprimée dans un script qui n’est pas le script habituel pour la langue. Par exemple, si l’entrée est de l’arabe écrit dans un script latin, sourceText.text est le même texte en arabe converti en script arabe.

En-têtes de réponse

headers Description
X-RequestId Valeur générée par le service pour identifier la demande et utilisée à des fins de résolution des problèmes.
X-MT-System Spécifie le type de système qui a été utilisé pour la traduction pour chaque langue de destination « to » demandée pour la traduction. La valeur est une liste de chaînes séparées par des virgules. Chaque chaîne indique un type :

▪ Custom - La demande inclut un système personnalisé et au moins un système personnalisé a été utilisé pendant la traduction.
▪ Team - Toutes les autres demandes

Codes d’état de réponse

Si une erreur se produit, la requête renvoie 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 de code : traduire du texte

Remarque

  • Chaque exemple s’exécute sur le localhost fichier que vous avez spécifié avec la docker run commande.
  • Pendant que votre conteneur est en cours d’exécution, localhost pointe vers le conteneur lui-même.
  • Vous n’avez pas besoin d’utiliser localhost:5000. Vous pouvez utiliser n’importe quel port qui n’est pas déjà utilisé dans votre environnement hôte.

Traduire une entrée unique

Cet exemple montre comment traduire une phrase unique de l’anglais en chinois simplifié.

curl -X POST "http://localhost:{port}/translate?api-version=3.0&from=en&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

Le corps de la réponse est le suivant :

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"}
        ]
    }
]

Le translations tableau inclut un élément qui fournit la traduction de l’élément de texte dans l’entrée.

Interroger le point de terminaison Azure AI Translator (texte)

Voici un exemple de requête HTTP cURL à l’aide de localhost :5000 que vous avez spécifié avec la docker run commande :

  curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-HANS"
    -H "Content-Type: application/json" -d "[{'Text':'Hello, what is your name?'}]"

Remarque

Si vous tentez la requête cURL POST avant que le conteneur soit prêt, vous obtenez en réponse un message Le service est temporairement indisponible. Attendez que le conteneur soit prêt, puis réessayez.

Traduire du texte à l’aide de l’API Swagger

Anglais ↔ Allemand

  1. Accédez à la page Swagger : http://localhost:5000/swagger/index.html
  2. Sélectionnez POST /translate
  3. Sélectionnez Faites un essai.
  4. Entrez le paramètre De comme en
  5. Entrez le paramètre À comme de
  6. Entrez le paramètre api-version comme 3.0
  7. Sous texts, remplacez string par le code JSON suivant
  [
        {
            "text": "hello, how are you"
        }
  ]

Sélectionnez Exécuter, les traductions obtenues sont générées dans le corps de la réponse. Vous devez normalement voir la réponse suivante :

"translations": [
      {
          "text": "hallo, wie geht es dir",
          "to": "de"
      }
    ]

Traduire du texte avec Python

Français anglais ↔

import requests, json

url = 'http://localhost:5000/translate?api-version=3.0&from=en&to=fr'
headers = { 'Content-Type': 'application/json' }
body = [{ 'text': 'Hello, how are you' }]

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

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

Traduire du texte avec une application console C#/.NET

Espagnol anglais ↔

Ouvrez Visual Studio et créez une nouvelle application de console. Modifiez le fichier *.csproj pour ajouter le nœud <LangVersion>7.1</LangVersion>, qui spécifie la version 7.1 de C#. Ajoutez le package NuGet Newtoonsoft.Json version 11.0.2.

Dans Program.cs, remplacez tout le code existant par le script suivant :

using Newtonsoft.Json;
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

namespace TranslateContainer
{
    class Program
    {
        const string ApiHostEndpoint = "http://localhost:5000";
        const string TranslateApi = "/translate?api-version=3.0&from=en&to=es";

        static async Task Main(string[] args)
        {
            var textToTranslate = "Sunny day in Seattle";
            var result = await TranslateTextAsync(textToTranslate);

            Console.WriteLine(result);
            Console.ReadLine();
        }

        static async Task<string> TranslateTextAsync(string textToTranslate)
        {
            var body = new object[] { new { Text = textToTranslate } };
            var requestBody = JsonConvert.SerializeObject(body);

            var client = new HttpClient();
            using (var request =
                new HttpRequestMessage
                {
                    Method = HttpMethod.Post,
                    RequestUri = new Uri($"{ApiHostEndpoint}{TranslateApi}"),
                    Content = new StringContent(requestBody, Encoding.UTF8, "application/json")
                })
            {
                // Send the request and await a response.
                var response = await client.SendAsync(request);

                return await response.Content.ReadAsStringAsync();
            }
        }
    }
}

Traduire plusieurs chaînes

La traduction de plusieurs chaînes en une fois nécessite simplement de spécifier un tableau de chaînes dans le corps de la demande.

curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}, {'Text':'I am fine, thank you.'}]"

La réponse contient la traduction de tous les éléments de texte dans le même ordre que dans la requête. Le corps de la réponse est le suivant :

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"}
        ]
    },
    {
        "translations":[
            {"text":"我很好，谢谢你。","to":"zh-Hans"}
        ]
    }
]

Traduire en plusieurs langues

Cet exemple montre comment traduire une même entrée en plusieurs langues en utilisant une seule requête.

curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-Hans&to=de" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

Le corps de la réponse est le suivant :

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"},
            {"text":"Hallo, was ist dein Name?","to":"de"}
        ]
    }
]

Traduire du contenu avec le balisage et spécifier le contenu traduit

Il est courant de traduire du contenu incluant un balisage, tel que le contenu d’une page HTML ou d’un document XML. Lors de la traduction de contenu incluant des balises, incluez le paramètre de requête textType=html. De plus, il est parfois utile d’exclure du contenu spécifique de la traduction. Vous pouvez utiliser l’attribut class=notranslate pour spécifier le contenu qui doit rester dans la langue d’origine. Dans l’exemple suivant, le contenu du premier élément div ne sera pas traduit, tandis que le contenu du deuxième élément div le sera.

<div class="notranslate">This will not be translated.</div>
<div>This will be translated. </div>

Voici un exemple de demande.

curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-Hans&textType=html" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'<div class=\"notranslate\">This will not be translated.</div><div>This will be translated.</div>'}]"

La réponse est la suivante :

[
    {
        "translations":[
            {"text":"<div class=\"notranslate\">This will not be translated.</div><div>这将被翻译。</div>","to":"zh-Hans"}
        ]
    }
]

Traduire avec un dictionnaire dynamique

Si vous connaissez déjà la traduction que vous souhaitez appliquer à un mot ou à une phrase, vous pouvez la fournir en tant que balisage dans la demande. Le dictionnaire dynamique n’est sûr que pour des noms propres comme les noms de personnes et les noms de produits.

Le balisage à fournir utilise la syntaxe suivante.

<mstrans:dictionary translation="translation of phrase">phrase</mstrans:dictionary>

Par exemple, considérez la phrase anglaise « le mot WordOMatic est une entrée de dictionnaire ». Pour conserver le mot WordOMatic dans la traduction, envoyez la demande :

curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=de" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'The word <mstrans:dictionary translation=\"wordomatic\">word or phrase</mstrans:dictionary> is a dictionary entry.'}]"

Le résultat est le suivant :

[
    {
        "translations":[
            {"text":"Das Wort \"wordomatic\" ist ein Wörterbucheintrag.","to":"de"}
        ]
    }
]

Cette fonctionnalité opère de la même façon avec textType=text ou textType=html. Elle doit être utilisée avec parcimonie. La façon appropriée et de loin préférable de personnaliser une traduction consiste à utiliser Custom Translator. Custom Translator utilise totalement le contexte et les probabilités statistiques. Si vous avez créé des données d’apprentissage qui affichent votre travail ou expression dans le contexte, vous obtenez de meilleurs résultats. En savoir plus sur Custom Translator.

Limites de requête

Chaque demande de traduction est limitée à 50 000 caractères, dans toutes les langues cibles de traduction. Par exemple, l’envoi d’une demande de traduction de 3 000 caractères à traduire en trois langues différentes génère une demande d’une taille de 3 000 x 3 = 9 000 caractères, qui satisfait la limite de demande. Vous êtes facturé au caractère, et non pas au nombre de requêtes. Nous vous recommandons d’envoyer des demandes plus courtes.

Le tableau suivant liste les limites d’éléments de tableau et de caractères pour chaque opération de translation dans Translator.

Opération Taille maximale d’un élément de tableau Nombre maximal d’éléments de tableau Taille de requête maximale (caractères)
translate 10 000 100 50 000

Utiliser docker compose : Translator avec des conteneurs de prise en charge

Docker compose est un outil qui vous permet de configurer des applications multiconteneurs à l’aide d’un seul fichier YAML généralement nommé compose.yaml. Utilisez la commande docker compose up pour démarrer votre application conteneur, et la commande docker compose down pour arrêter et supprimer vos conteneurs.

Si vous avez installé l’interface CLI Docker Desktop, elle inclut Docker compose et ses prérequis. Si vous n’avez pas Docker Desktop, consultez la vue d’ensemble de l’installation de Docker Compose.

Le tableau suivant répertorie les conteneurs de prise en charge requis pour vos opérations de traduction de texte et de documentation. Le conteneur Traducteur envoie des informations de facturation à Azure via la ressource Azure AI Traducteur sur votre compte Azure.

Opération Requête demandée Type de document Conteneurs de prise en charge
• Traduction de texte
• Traduction de documentation		 from spécifié. Documents Office Aucun
• Traduction de texte
• Traduction de documentation		 from non spécifié. Nécessite la détection automatique de la langue pour déterminer la langue source. Documents Office ✔️ Conteneur Text analytics:language
• Traduction de texte
• Traduction de documentation		 from spécifié. Documents PDF numérisés ✔️ Conteneur Vision:read
• Traduction de texte
• Traduction de documentation		 from non spécifié nécessitant la détection automatique de la langue pour déterminer la langue source. Documents PDF numérisés ✔️ Conteneur Text analytics:language

✔️ Conteneur Vision:read
Images conteneur et étiquettes

Vous trouverez les images conteneur Azure AI services dans le catalogue du Registre des artefacts Microsoft. Le tableau suivant indique l’emplacement complet de l’image pour la traduction de texte et de documentation :

Conteneur Emplacement de l’image Notes
Traducteur : traduction de texte mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest Vous pouvez afficher la liste complète des étiquettes de version d’Azure AI services Text Translation sur MCR.
Translator : Traduction de documents TODO TODO
Analyse de texte : langue mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest Vous pouvez afficher la liste complète des étiquettes de version d’Azure AI services Text Analytics Language sur MCR.
Vision : Lire mcr.microsoft.com/azure-cognitive-services/vision/read:latest Vous pouvez afficher la liste complète des étiquettes de version de Azure AI services Computer Vision Read OCR sur MCR.

Créer votre application

  1. À l’aide de votre éditeur ou IDE préféré, créez un répertoire nommé container-environment (ou tout autre nom de votre choix) pour votre application.

  2. Créez un fichier YAML nommé compose.yaml. Vous pouvez utiliser les extensions .yml ou .yaml pour le fichier compose.

  3. Copiez et collez l’exemple de code YAML suivant dans votre fichier compose.yaml. Remplacez {TRANSLATOR_KEY} et {TRANSLATOR_ENDPOINT_URI} par les valeurs de clé et de point de terminaison issues de votre instance Traducteur du portail Azure. Veillez à utiliser le document translation endpoint.

  4. Le nom de niveau supérieur (azure-ai-translator, azure-ai-language, azure-ai-read) est le paramètre que vous spécifiez.

  5. container_name est un paramètre facultatif qui définit un nom pour le conteneur lorsqu’il s’exécute, plutôt que de laisser docker compose générer un nom.

    services:
  azure-ai-translator:
    container_name: azure-ai-translator
    image: mcr.microsoft.com/product/azure-cognitive-services/translator/text-translation:latest
    environment:
        - EULA=accept
        - billing={TRANSLATOR_ENDPOINT_URI}
        - apiKey={TRANSLATOR_KEY}
        - AzureAiLanguageHost=http://azure-ai-language:5000
        - AzureAiReadHost=http://azure-ai-read:5000
    ports:
          - "5000:5000"
    azure-ai-language:
      container_name: azure-ai-language
      image:  mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest
      environment:
          - EULA=accept
          - billing={TRANSLATOR_ENDPOINT_URI}
          - apiKey={TRANSLATOR_KEY}
    azure-ai-read:
      container_name: azure-ai-read
      image:  mcr.microsoft.com/azure-cognitive-services/vision/read:latest
      environment:
          - EULA=accept
          - billing={TRANSLATOR_ENDPOINT_URI}
          - apiKey={TRANSLATOR_KEY}

  6. Ouvrez un terminal, accédez au dossier container-environment et démarrez les conteneurs avec la commande docker-compose suivante :

    docker compose up

  7. Pour arrêter les conteneurs, utilisez la commande suivante :

    docker compose down

    Conseil

    docker compose Commandes:

    • docker compose pause suspend les conteneurs en cours d’exécution.
    • docker compose unpause {your-container-name} annule la suspension des conteneurs suspendus.
    • docker compose restart redémarre tous les conteneurs arrêtés et en cours d’exécution avec toutes leurs modifications précédentes intactes. Si vous apportez des modifications à votre configuration compose.yaml, ces modifications ne sont pas mises à jour avec la commande docker compose restart. Vous devez utiliser la commande docker compose up pour refléter les mises à jour et les modifications apportées au fichier compose.yaml.
    • docker compose ps -a dresse la liste de tous les conteneurs, y compris ceux qui sont arrêtés.
    • docker compose exec vous permet d’exécuter des commandes pour détacher ou définir des variables d’environnement dans un conteneur en cours d’exécution.

    Pour plus d’informations, consultez les informations de référence sur l’interface CLI docker.

Étapes suivantes

En savoir plus sur la traduction de texte