Translator 3.0 : Translate

  • Article

Traduit du texte.

URL de la demande

Envoyez une demande POST à :

https://api.cognitive.microsofttranslator.com/translate?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 obligatoires

Paramètre de requête. Description
api-version Paramètre obligatoire.
Version de l’API demandée par le client. La valeur doit être 3.0.
to Paramètre obligatoire.
Spécifie la langue du texte de sortie. La langue cible doit être l’une des langues prises en charge incluses dans l’étendue translation. 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ètres facultatifs

Paramètre de requête. Description
de Paramètre facultatif.
Spécifie la langue du texte d’entrée. Trouvez les langues disponibles pour la traduction en recherchant langues prises en charge à l’aide de l’étendue translation. Si le paramètre from n’est pas spécifié, une détection automatique de la langue est appliquée pour déterminer la langue source.

Vous devez utiliser le paramètre from au lieu de la détection automatique lors de l’utilisation de la fonctionnalité de dictionnaire dynamique. Remarque : la fonctionnalité de dictionnaire dynamique respecte la casse.
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.
catégorie Paramètre facultatif.
Chaîne spécifiant la catégorie (domaine) de la traduction. Ce paramètre est utilisé pour obtenir des traductions d’un système personnalisé créé avec Custom Translator. Pour utiliser votre système personnalisé déployé, ajoutez l’ID de catégorie de votre projet de Traducteur personnalisé au paramètre de catégorie. La valeur par défaut est general.
ProfanityAction Paramètre facultatif.
Spécifie comment les vulgarités doivent être traitées dans les traductions. Les valeurs possibles sont les suivantes : NoAction (par défaut), Markedou Deleted. Pour comprendre comment traiter les vulgarités, voir Gestion de la vulgarité.
ProfanityMarker Paramètre facultatif.
Spécifie comment vulgarités doit être marquées dans les traductions. Les valeurs possibles sont : Asterisk (par défaut) ou Tag. Pour comprendre comment traiter les vulgarités, voir Gestion de la vulgarité.
includeAlignment Paramètre facultatif.
Spécifie s’il faut inclure une projection d’alignement du texte source vers le texte traduit. Les valeurs possibles sont true ou false (par défaut).
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).
suggestedFrom Paramètre facultatif.
Spécifie une langue de base si la langue du texte d’entrée ne peut pas être identifiée. La détection automatique de la langue est appliquée en cas d’omission du paramètre from. Si la détection échoue, la langue suggestedFrom est adoptée.
fromScript Paramètre facultatif.
Spécifie le script du texte d’entrée.
toScript Paramètre facultatif.
Spécifie le script du texte traduit.
allowFallback Paramètre facultatif.
Spécifie que le service est autorisé à revenir à un système général quand il n’existe pas de système personnalisé. Les valeurs possibles sont : true (par défaut) ou false.

allowFallback=false spécifie que la traduction doit utiliser uniquement les systèmes entraînés pour le category spécifié par la requête. Si une traduction de la langue X vers la langue Y exige un chaînage via une langue relais E, tous les systèmes présents dans la chaîne (X → E and E → Y) doivent être personnalisés et avoir la même catégorie. Si aucun système n’est trouvé avec une catégorie spécifique, la requête retourne le code d’état 400. allowFallback=true spécifie que le service est autorisé à revenir à un système général quand il n’existe pas de système personnalisé.

Les en-têtes de demande sont les suivants :

headers Description
En-têtes d’authentification En-tête de demande obligatoire.
Voir les options disponibles pour l’authentification.
Content-Type En-tête de demande obligatoire.
Spécifie le type de contenu de la charge utile.
La valeur acceptée est application/json; charset=UTF-8.
Content-Length En-tête de demande obligatoire.
Longueur du corps de la demande.
X-ClientTraceId Facultatif.
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.

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

Pour plus d’informations sur les limites des caractères et des tableaux, consultezLimites de requête.

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 :

  • detectedLanguage: objet décrivant la langue détectée au moyen des propriétés suivantes :

    • language: chaîne représentant le code de la langue détectée.

    • score: valeur flottante indiquant le niveau de confiance dans le résultat. Le score est compris entre zéro et un, un score faible indiquant un niveau de confiance bas.

    La propriété detectedLanguage n’est présente dans l’objet de résultat que quand la détection automatique de la langue est demandée.

  • 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.

    • transliteration: objet fournissant le texte traduit dans le script spécifié par le paramètre toScript.

      • script: chaîne spécifiant le script cible.

      • text: chaîne fournissant le texte traduit dans le script cible.

      L’objet transliteration n’est pas inclus si une translittération n’a pas lieu.

      • alignment: objet avec une propriété de chaîne unique nommée proj, qui mappe le texte d’entrée au texte traduit. Les informations d’alignement ne sont fournies que quand le paramètre de requête includeAlignment est true. L’alignement est renvoyé en tant que valeur de chaîne au format suivant : [[SourceTextStartIndex]:[SourceTextEndIndex]–[TgtTextStartIndex]:[TgtTextEndIndex]]. Le signe deux-points sépare les index de début et de fin, le signe tiret sépare les langues, et une espace sépare les mots. Un mot peut s’aligner sur zéro, un ou plusieurs mots dans l’autre langue, et les mots alignés peuvent être noncontigus. Lorsqu’aucune information d’alignement n’est disponible, l’élément Alignment est vide. Pour obtenir un exemple et les restrictions, voir Obtenir les informations d’alignement.

    • 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 était arabe écrite en écriture latine, il sourceText.text s’agirait du même texte arabe converti en script arabe..

Des exemples de réponses JSON sont fournis dans la section exemples.

En-têtes de réponse

headers Description
X-requestid Valeur générée par le service pour identifier la demande 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 :

Personnalisé : la demande inclut un système personnalisé et au moins un système personnalisé a été utilisé pendant la traduction.
Équipe : toutes les autres demandes
X-metered-usage Spécifie la consommation (nombre de caractères facturés à l’utilisateur) de la demande de travail de traduction. Par exemple, si le mot « Hello » est traduit de l’anglais (en) en français (fr), ce champ renvoie la valeur 5.

Codes d’état de réponse

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

Code d’état Description
200 Réussite.
400 L’un des paramètres de requête est manquant ou non valide. Corrigez les paramètres de demande avant de réessayer.
401 Il n’a pas été possible d’authentifier la demande. Vérifiez que les informations d’identification sont spécifiées et valides.
403 La requête n’est pas autorisée. Vérifiez le message d’erreur détaillé. Ce code d’état indique souvent que vous avez utilisé toutes les traductions gratuites fournies avec un abonnement d’essai.
408 La requête n’a pas pu être satisfaite car il manque une ressource. Vérifiez le message d’erreur détaillé. Lorsque la requête inclut une catégorie personnalisée, ce code d’état indique souvent que le système de traduction personnalisé n’est pas encore disponible pour traiter les demandes. La requête doit être retentée après un délai d’attente (par exemple, 1 minute).
429 Le serveur a rejeté la demande, 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 l’échec, 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 l’échec, 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 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

Traduire une entrée unique

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

curl -X POST "https://api.cognitive.microsofttranslator.com/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.

Traduire une entrée unique avec détection automatique de la langue

Cet exemple montre comment traduire une phrase unique de l’anglais en chinois simplifié. La demande ne spécifie pas la langue d’entrée. La détection automatique de la langue source est utilisée à la place.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&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 :

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

La réponse est similaire à la réponse de l’exemple précédent. Étant donné que la détection automatique de la langue a été demandée, la réponse inclut également des informations sur la langue détectée pour le texte d’entrée. La détection automatique de la langue fonctionne mieux avec un texte d’entrée plus long.

Traduire avec translittération

Étendons l’exemple précédent en ajoutant la translittération. La requête suivante demande une traduction chinoise écrite en script Latin.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=zh-Hans&toScript=Latn" -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 :

[
    {
        "detectedLanguage":{"language":"en","score":1.0},
        "translations":[
            {
                "text":"你好, 你叫什么名字？",
                "transliteration":{"script":"Latn", "text":"nǐ hǎo , nǐ jiào shén me míng zì ？"},
                "to":"zh-Hans"
            }
        ]
    }
]

Le résultat de la traduction inclut à présent une transliteration propriété qui fournit le texte traduit en caractères latins.

Traduire plusieurs éléments de texte

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 "https://api.cognitive.microsofttranslator.com/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 "https://api.cognitive.microsofttranslator.com/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"}
        ]
    }
]

Traiter la vulgarité

En règle générale, le service Translator conserve dans la traduction les termes vulgaires présents dans la source. Le degré de profanité et le contexte qui rend les mots profanes diffèrent entre les cultures et, par conséquent, le degré de profanité dans la langue cible peut être amplifié ou réduit.

Si vous souhaitez éviter toute vulgarité dans la traduction, indépendamment de la présence de vulgarité dans le texte source, vous disposez d’une option de filtrage de la vulgarité. L’option vous permet de choisir si vous souhaitez voir les vulgarités supprimées, marqués avec les balises appropriées (ce qui vous donne la possibilité d’ajouter votre propre post-traitement) ou sans aucune action effectuée. Les valeurs ProfanityAction acceptées sont Deleted, Markedet NoAction (par défaut).

ProfanityAction Action
NoAction NoAction est le comportement par défaut. Les termes vulgaires de la source sont reflétés dans la cible.

Exemple de source (japonais) : 彼はジャッカンです。
Exemple de traduction (anglais) : C’est un c--.
Deleted Les mots vulgaires sont supprimés de la cible et ne sont pas remplacés.

Exemple de source (japonais) : 彼はジャッカンです。
Exemple de traduction (anglais) : Il est un**
Marked Un marqueur remplace le mot marqué dans la sortie. Le marqueur varie selon le paramètre ProfanityMarker.

Pour ProfanityMarker=Asteriskles mots profanes sont remplacés par ***:
Exemple de source (japonais) : 彼はジャッカンです。
Exemple de traduction (anglais) : Il est un \\\*.

Pour ProfanityMarker=Tag, les mots profanes sont entourés de balises XML <profanité> et </profanité> :
Exemple de source (japonais) : 彼はジャッカンです。
Exemple de traduction (anglais) : C’est un <vulgarité>c--</vulgarité>.

Par exemple :

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de&profanityAction=Marked" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'This is an <expletive> good idea.'}]"

Cette requête retourne :

[
    {
        "translations":[
            {"text":"Das ist eine *** gute Idee.","to":"de"}
        ]
    }
]

Comparez à :

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de&profanityAction=Marked&profanityMarker=Tag" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'This is an <expletive> good idea.'}]"

Cette dernière demande renvoie :

[
    {
        "translations":[
            {"text":"Das ist eine <profanity>verdammt</profanity> gute Idee.","to":"de"}
        ]
    }
]

Traduire du contenu incluant le balisage

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 "https://api.cognitive.microsofttranslator.com/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"}
        ]
    }
]

Obtenir les informations d’alignement

L’alignement est retourné en tant que valeur de chaîne au format suivant pour chaque mot de la source. Les informations pour chaque mot sont séparées par un espace, y compris pour les langues non séparées par des espaces (scripts) comme le chinois :

[[SourceTextStartIndex]\:[SourceTextEndIndex]–[TgtTextStartIndex]\:[TgtTextEndIndex]] *

Exemple de chaîne d’alignement : « 0:0-7:10 1:2-11:20 3:4-0:3 3:4-4:6 5:5-21:21 ».

En d’autres termes, le signe deux-points sépare les index de début et de fin, le signe tiret sépare les langues et un espace sépare les mots. Un mot peut s’aligner sur zéro, un ou plusieurs mots dans l’autre langue, et les mots alignés peuvent être noncontigus. Lorsqu’aucune information d’alignement n’est disponible, l’élément Alignment est vide. La méthode ne retourne aucune erreur dans ce cas.

Pour recevoir les informations d’alignement, spécifiez includeAlignment=true sur la chaîne de requête.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=fr&includeAlignment=true" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'The answer lies in machine translation.'}]"

La réponse est la suivante :

[
    {
        "translations":[
            {
                "text":"La réponse se trouve dans la traduction automatique.",
                "to":"fr",
                "alignment":{"proj":"0:2-0:1 4:9-3:9 11:14-11:19 16:17-21:24 19:25-40:50 27:37-29:38 38:38-51:51"}
            }
        ]
    }
]

Les informations d’alignement commencent par 0:2-0:1, ce qui signifie que les trois premiers caractères dans le texte source (The) mappent aux deux premiers caractères dans le texte traduit (La).

Limites

L’obtention d’informations d’alignement est une fonctionnalité expérimentale que nous avons activée pour la recherche de prototypage et les expériences avec des mappages d’expressions potentiels. Voici quelques restrictions notables pour lesquelles les alignements ne sont pas pris en charge :

  • L’alignement n’est pas disponible pour du texte au format HTML, soit textType=html
  • L’alignement est retourné uniquement pour un sous-ensemble des paires de langues :
    • Anglais vers/depuis n’importe quelle autre langue, à l’exception du chinois traditionnel, cantonais (traditionnel) ou serbe (cyrillique)
    • du japonais au coréen ou du coréen au japonais
    • du japonais au chinois simplifié et chinois simplifié en japonais
    • du chinois simplifié au chinois traditionnel et chinois traditionnel au chinois simplifié
  • Vous n’aurez pas d’alignement si la phrase est une traduction définie. Exemple de traduction en boîte est This is a test, I love youet d’autres phrases à fréquence élevée
  • L'alignement n'est pas possible lorsque vous appliquez l'une des approches visant à empêcher la traduction comme décrit ici

Obtenir les limites de longueur de phrase

Pour recevoir des informations sur la longueur des phrases dans le texte source et le texte traduit, spécifiez includeSentenceLength=true dans la chaîne de requête.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=fr&includeSentenceLength=true" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'The answer lies in machine translation. The best machine translation technology cannot always provide translations tailored to a site or users like a human. Simply copy and paste a code snippet anywhere.'}]"

La réponse est la suivante :

[
    {
        "translations":[
            {
                "text":"La réponse se trouve dans la traduction automatique. La meilleure technologie de traduction automatique ne peut pas toujours fournir des traductions adaptées à un site ou des utilisateurs comme un être humain. Il suffit de copier et coller un extrait de code n'importe où.",
                "to":"fr",
                "sentLen":{"srcSentLen":[40,117,46],"transSentLen":[53,157,62]}
            }
        ]
    }
]

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. Remarque : la fonctionnalité de dictionnaire dynamique respecte la casse.

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 "https://api.cognitive.microsofttranslator.com/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\">wordomatic</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é de dictionnaire dynamique 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 pouvez créer des données d’entraînement qui montrent votre mot ou phrase en contexte, vous obtiendrez de meilleurs résultats. En savoir plus sur Custom Translator.

Étapes suivantes

Essayer le guide de démarrage rapide Translator