Partager via

Azure Translator dans Foundry Tools 3.0 : Traduire

Traduit du texte.

URL de requête

Envoyez une POST demande à :

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

ConsultezLa prise en charge du réseau virtuel pour Translator sélectionné réseau et la configuration et la prise en charge des points de terminaison privés.

Paramètres de la demande

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

Paramètres obligatoires

Paramètre de requête. Descriptif
version de l'API Paramètre obligatoire.
Version de l’API demandée par le client. La valeur doit être 3.0.
à 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 simultanément en plusieurs langues en répétant le paramètre dans la chaîne de requête. Par exemple, utilisez to=de&to=it pour traduire l’allemand et l’italien.

Paramètres facultatifs

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

Vous devez utiliser le from paramètre plutôt que la suppression 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 traduit est du texte brut ou du texte HTML. Tout code HTML doit être un élément complet bien formé. 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 à partir d’un système personnalisé créé avec Custom Translator. Pour utiliser votre système personnalisé déployé, ajoutez l’ID de catégorie de vos détails de projet Custom Translator au paramètre de catégorie. La valeur par défaut est : general.
profanityAction Paramètre facultatif.
Spécifie la façon dont les profanité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 profanités, consultez la gestion des profanités.
profanityMarker Paramètre facultatif.
Spécifie la façon dont les profanités doivent être marquées dans les traductions. Les valeurs possibles sont : Asterisk (par défaut) ou Tag. Pour comprendre comment traiter les profanités, consultez la gestion des profanités.
includeAlignment Paramètre facultatif.
Spécifie s’il faut inclure la projection d’alignement du texte source au 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 phrase pour le texte d’entrée et le texte traduit. Les valeurs possibles sont : true ou false (par défaut).
suggestedFrom Paramètre facultatif.
Spécifie une langue de secours si la langue du texte d’entrée ne peut pas être identifiée. L’autodétection de langue est appliquée lorsque le from paramètre est omis. Si la détection échoue, la suggestedFrom langue est supposé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 lorsqu’un système personnalisé n’existe pas. Les valeurs possibles sont : true (par défaut) ou false.

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

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

headers Descriptif
En-têtes d’authentification En-tête de demande obligatoire.
Consultez les options disponibles pour l’authentification.
Type de contenu 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.
Longueur-contenu Facultatif.
Longueur du corps de la requête.
X-ClientTraceId Facultatif.
GUID généré par le client pour identifier de manière unique la requête. 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 nommé ClientTraceId.

Corps de la requête

Le corps de la requête est un tableau JSON. Chaque élément de 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 de caractères et de tableaux, consultezLimites de requête.

Corps de réponse

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

  • detectedLanguage: objet décrivant la langue détectée via les propriétés suivantes :

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

    • score: valeur float indiquant la confiance dans le résultat. Le score est compris entre zéro et un et un score faible indique une faible confiance.

    La detectedLanguage propriété est présente uniquement dans l’objet de résultat lorsque l’autodétection du langage est demandée.

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

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

    • text: chaîne donnant le texte traduit.

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

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

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

      L’objet transliteration n’est pas inclus si la 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 sont fournies uniquement lorsque le paramètre includeAlignment de requête est true. L’alignement est retourné sous forme de valeur de chaîne du format suivant : [[SourceTextStartIndex]:[SourceTextEndIndex]–[TgtTextStartIndex]:[TgtTextEndIndex]]. Le signe deux-points sépare l’index de début et de fin, le tiret sépare les langues et l’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. Quand aucune information d’alignement n’est disponible, l’élément d’alignement est vide. Consultez Obtenir des informations d’alignement pour obtenir un exemple et des restrictions.

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

      • srcSentLen: tableau entier représentant les longueurs des phrases dans le texte d’entrée. La longueur du tableau est le nombre de phrases, et les valeurs sont la longueur de chaque phrase.

      • transSentLen: tableau entier représentant les longueurs des phrases dans le texte traduit. La longueur du tableau est le nombre de phrases, et les valeurs sont la longueur de chaque phrase.

      Les limites de phrase sont incluses uniquement lorsque le paramètre includeSentenceLength de requête est true.

  • sourceText: objet avec une propriété de chaîne unique nommée text, qui donne le texte d’entrée dans le script par défaut de la langue source. sourceText la propriété est présente uniquement lorsque 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 Descriptif
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 système utilisé pour la traduction pour chaque langue « vers » demandée pour la traduction. La valeur est une liste séparée par des virgules de chaînes. Chaque chaîne indique un type :

Custom - Request inclut un système personnalisé et au moins un système personnalisé a été utilisé pendant la traduction.
Équipe - Toutes les autres demandes
Utilisation limitée par X Spécifie la consommation (nombre de caractères pour lesquels l’utilisateur est facturé) pour la demande de travail de traduction. Par exemple, si le mot « Hello » est traduit de l’anglais (en) en français (fr), ce champ retourne la valeur 5.

Codes d’état de réponse

Voici les codes d’état HTTP possibles qu’une requête retourne.

Code de statut Descriptif
200 Succès.
400 L’un des paramètres de requête est manquant ou non valide. Corrigez les paramètres de requête avant de réessayer.
401 La demande n’a pas pu être authentifiée. Vérifiez que les informations d’identification sont spécifiées et valides.
4:03 La demande 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 demande n’a pas pu être remplie, car une ressource est manquante. Vérifiez le message d’erreur détaillé. Lorsque la demande 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 demande doit être retentée après une période 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 avec : date et heure de l’échec, identificateur de demande de l’en-tête de réponse X-RequestId et identificateur client de l’en-tête de requête X-ClientTraceId.
503 Serveur temporairement indisponible. Réessayez la requête. Si l’erreur persiste, signalez-la avec : date et heure de l’échec, identificateur de demande de l’en-tête de réponse X-RequestId et identificateur client de l’en-tête de requête X-ClientTraceId.

Si une erreur se produit, la requête retourne une réponse d’erreur JSON. Le code d’erreur est un nombre à 6 chiffres combinant le code d’état HTTP à 3 chiffres suivi d’un nombre à 3 chiffres pour catégoriser davantage l’erreur. Vous trouverez les codes d’erreur courants sur la page de référence de La version 3 de Translator.

Examples

Traduire une seule entrée

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 :

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

Le translations tableau comprend un élément, qui fournit la traduction du texte unique dans l’entrée.

Traduire une entrée unique avec l’autodétection de langue

Cet exemple montre comment traduire une phrase unique de l’anglais en chinois simplifié. La requête ne spécifie pas la langue d’entrée. La suppression 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 :

[
    {
        "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 l’autodétection de 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 du texte d’entrée plus long.

Traduire avec translittération

Étendons l’exemple précédent en ajoutant la translittération. La demande 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 :

[
    {
        "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 désormais une transliteration propriété, qui donne le texte traduit à l’aide de caractères latins.

Traduire plusieurs éléments de texte

La traduction de plusieurs chaînes à la fois est simplement une question de spécification d’un tableau de chaînes dans le corps de la requête.

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 toutes les parties de texte dans le même ordre que dans la demande. Le corps de la réponse est :

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

Traduire en plusieurs langues

Cet exemple montre comment traduire la même entrée en plusieurs langues dans une 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 :

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

Gérer la profanité

Normalement, le Traducteur conserve la profanité présente dans la source dans la traduction. 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 d’obtenir des profanations dans la traduction, quelle que soit la présence de profanité dans le texte source, vous pouvez utiliser l’option de filtrage de la profanité. L’option vous permet de choisir si vous souhaitez voir les profanités supprimées, marquées 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).

Valeur ProfanityAction acceptée Valeur ProfanityMarker Action Exemple : Source - Espagnol Exemple : Cible - Anglais
AucuneAction Default. Identique à ne pas définir l’option. La profanité passe de la source à la cible. Que coche de <insert-profane-word> Qu’est-ce qu’une <voiture insert-profane-word>
Marqué Astérisque Les astérisques remplacent les mots profanes (par défaut). Que coche de <insert-profane-word> Quelle voiture ***
Marqué Tag Les mots profanes sont entourés de profanités< de balises >XML...</profanité>. Que coche de <insert-profane-word> <Quelle voiture de profanité><insert-profane-word></profanity>
Deleted Les mots profanes sont supprimés de la sortie sans remplacement. Que coche de <insert-profane-word> Quelle voiture

Dans les exemples ci-dessus,< insert-profane-word> est un espace réservé pour les mots profanes.

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 avec :

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 requête retourne :

[
    {
        "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 qui inclut des marques telles que du contenu d’une page HTML ou du contenu à partir d’un document XML. Incluez le paramètre textType=html de requête lors de la traduction de contenu avec des balises. En outre, 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 sa langue d’origine. Dans l’exemple suivant, le contenu à l’intérieur du premier div élément n’est pas traduit, tandis que le contenu du deuxième div élément est traduit.

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

Voici un exemple de requête à illustrer.

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 des informations d’alignement

L’alignement est retourné sous forme de valeur de chaîne du format suivant pour chaque mot de la source. Les informations de chaque mot sont séparées par un espace, y compris pour les langues non séparées par l’espace (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:21:21 ».

En d’autres termes, le signe deux-points sépare l’index de début et de fin, le tiret sépare les langues et l’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. Quand 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 des 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 du texte source (The) sont mappés aux deux premiers caractères du 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-unes des restrictions notables où les alignements ne sont pas pris en charge :

  • L’alignement n’est pas disponible pour le texte au format HTML, 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’alignez pas si la phrase est une traduction en boîte. 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 disponible lorsque vous appliquez l’une des approches pour empêcher la traduction, comme décrit ici

Obtenir des limites de phrase

Pour recevoir des informations sur la longueur des phrases dans le texte source et le texte traduit, spécifiez includeSentenceLength=true 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 expression, vous pouvez le fournir en tant que balisage dans la demande. Le dictionnaire dynamique n’est sûr que pour les noms appropriés, tels que les noms personnels 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 wordomatique 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 :

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

Cette fonctionnalité de dictionnaire dynamique fonctionne de la même façon avec textType=text ou avec textType=html. La fonctionnalité doit être utilisée avec parcimonie. La meilleure façon de personnaliser la traduction est d’utiliser Custom Translator. Custom Translator utilise pleinement le contexte et les probabilités statistiques. Si vous pouvez créer 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.

Étapes suivantes

Essayer le guide de démarrage rapide Translator

  • Last updated on