Conteneur : Traduire du texte

Article
04/09/2024

Traduisez du texte.

URL de la demande

Envoyez une demande POST à :

POST {Endpoint}/translate?api-version=3.0&&from={from}&to={to}

Exemple de requête

POST https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=es

[
  {
    "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

Vous pouvez interroger le service pour obtenir translation des langues prises en charge par l’étendue.
Consultez égalementla prise en charge de la langue pour la translittération.

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

headers	Description	Condition
En-têtes d’authentification	Consultez lesoptions 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 10 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

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. Pour spécifier un port, utilisez l’option -p .

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 un point de terminaison azure AI Traducteur (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

Accédez à la page Swagger : http://localhost:5000/swagger/index.html
Sélectionnez POST /translate
Sélectionnez Faites un essai.
Entrez le paramètre De comme en
Entrez le paramètre À comme de
Entrez le paramètre api-version comme 3.0
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:{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?'}, {'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:{port}/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:{port}/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:{port}/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 à 10 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	10 000

Utiliser docker compose : Traducteur avec des conteneurs prenant 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 docker compose up commande pour démarrer votre application conteneur et la docker compose down commande pour arrêter et supprimer vos conteneurs.

Si vous avez installé Docker Desktop CLI, il 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 document. Le conteneur Traducteur envoie des informations de facturation à Azure via la ressource Azure AI Traducteur sur votre compte Azure.

Opération	Requête de requête	Type de document	Prise en charge des conteneurs
•Traduction de texte • Traduction de documents	`from` Spécifié.	Documents Office	Aucun
•Traduction de texte • Traduction de documents	`from` non spécifié. Nécessite la détection automatique de la langue pour déterminer la langue source.	Documents Office	✔️ Analyse de texte :conteneur de langue
•Traduction de texte • Traduction de documents	`from` Spécifié.	Documents PDF numérisés	Vision :read container ✔️
•Traduction de texte • Traduction de documents	`from` non spécifié nécessitant la détection automatique de langue pour déterminer la langue source.	Documents PDF numérisés	✔️ Analyse de texte :conteneur de langue Vision :read container ✔️

Images et balises conteneur

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

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 balises de version traduction de texte des services Azure AI sur MCR.
Traducteur : 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 services Azure AI Analyse de texte balises de version de langage sur MCR.
Vision : lecture	`mcr.microsoft.com/azure-cognitive-services/vision/read:latest`	Vous pouvez afficher la liste complète des services Azure AI Vision par ordinateur lire `OCR` les balises de version sur MCR.

Créer votre application

À l’aide de votre éditeur ou IDE préféré, créez un répertoire pour votre application nommée container-environment ou un nom de votre choix.
Créez un fichier YAML nommé compose.yaml. Les extensions .yml ou .yaml peuvent être utilisées pour le compose fichier.
Copiez et collez l’exemple de code YAML suivant dans votre compose.yaml fichier. Remplacez et {TRANSLATOR_ENDPOINT_URI} utilisez {TRANSLATOR_KEY} les valeurs de clé et de point de terminaison de votre instance de Portail Azure Traducteur. Veillez à utiliser le document translation endpoint.
Le nom de niveau supérieur (azure-ai-translator, azure-ai-language, azure-ai-read) est le paramètre que vous spécifiez.

Il container_name s’agit d’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}

Ouvrez un terminal accédez au container-environment dossier et démarrez les conteneurs avec la commande suivante docker-compose :
```
docker compose up
```
Pour arrêter les conteneurs, utilisez la commande suivante :
```
docker compose down
```
Conseil

docker compose Commandes:
- docker compose pause met en pause les conteneurs en cours d’exécution.
- docker compose unpause {your-container-name} supprime les conteneurs suspendus.
- docker compose restart redémarre tous les conteneurs arrêtés et en cours d’exécution avec toutes ses modifications précédentes intactes. Si vous apportez des modifications à votre compose.yaml configuration, ces modifications ne sont pas mises à jour avec la docker compose restart commande. Vous devez utiliser la docker compose up commande pour refléter les mises à jour et les modifications apportées au compose.yaml fichier.
- docker compose ps -a répertorie 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, consultezla référence docker CLI.

Étapes suivantes

En savoir plus sur la traduction de texte