Commencer la traduction

Article
02/23/2024

Service
de référence : Traduction de documentation Azure AI
Version de l’API : v1.1

Utilisez cette API pour commencer une demande de traduction avec le service Traduction de documents. Chaque demande peut contenir plusieurs documents, et doit contenir un conteneur source et un conteneur de destination pour chaque document.

Les filtres de préfixe et de suffixe (s’ils sont fournis) sont utilisés pour filtrer les dossiers. Le préfixe est appliqué au sous-chemin après le nom du conteneur.

Des glossaires et une mémoire de traduction peuvent être inclus dans la demande, et appliqués par le service lorsque le document est traduit.

Si le glossaire n’est pas valide ou est inaccessible lors de la traduction, une erreur est signalée dans l’état du document. Si un fichier portant le même nom existe déjà dans la destination, le travail se solde par un échec. La valeur targetUrl de chaque langue cible doit être unique.

URL de la demande

Envoyez une demande POST à :

POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches

Découvrez comment déterminer votre nom de domaine personnalisé.

Important

Toutes les requêtes d’API adressées au service Traduction de documentation nécessitent un point de terminaison de domaine personnalisé.
Vous ne pouvez pas utiliser le point de terminaison qui se trouve dans la page Clés et point de terminaison de votre ressource du portail Azure, ni le point de terminaison du traducteur global (api.cognitive.microsofttranslator.com) pour soumettre des requêtes HTTP au service Traduction de documentation.

En-têtes de requête

Les en-têtes de requête sont les suivants :

headers	Description
Ocp-Apim-Subscription-Key	En-tête de requête obligatoire

BatchRequest (corps)

Définition de la demande de traduction par lot d’entrée. Chaque requête peut contenir plusieurs documents et doit contenir un conteneur source et un conteneur cible pour chaque document. Types de médias sources : application/json, text/json, application/*+json.


{
  "inputs": [
    {
      "source": {
        "sourceUrl": "https://myblob.blob.core.windows.net/Container/",
        "filter": {
          "prefix": "FolderA",
          "suffix": ".txt"
        },
        "language": "en",
        "storageSource": "AzureBlob"
      },
      "targets": [
        {
          "targetUrl": "https://myblob.blob.core.windows.net/TargetUrl/",
          "category": "general",
          "language": "fr",
          "glossaries": [
            {
              "glossaryUrl": "https://myblob.blob.core.windows.net/Container/myglossary.tsv",
              "format": "XLIFF",
              "version": "2.0",
              "storageSource": "AzureBlob"
            }
          ],
          "storageSource": "AzureBlob"
        }
      ],
      "storageType": "Folder"
    }
  ],
  "options": {
    "experimental": true
  }
}

Entrées

Définition de la demande de traduction par lot d’entrée.

Paramètre clé	Type	Requis	Paramètres de la demande	Description
Entrées	`array`	True	• source (objet) • targets (groupe) • storageType (chaîne)	Données sources d’entrée.

inputs.source

Définition des données sources.

Paramètre clé	Type	Requis	Paramètres de la demande	Description
inputs.source	`object`	True	• sourceUrl (chaîne) • filter (objet) • language (chaîne) • storageSource (chaîne)	Données sources pour les documents d’entrée.
inputs.source.sourceUrl	`string`	True	•String	Emplacement du conteneur pour le fichier ou dossier source.
inputs.source.filter	`object`	False	• prefix (chaîne) • suffix (chaîne)	Chaînes respectant la casse pour filtrer des documents dans le chemin d’accès source.
inputs.source.filter.prefix	`string`	False	•String	Chaîne de préfixe respectant la casse pour filtrer les documents dans le chemin d’accès source pour la traduction. Souvent utilisé pour désigner des sous-dossiers pour la traduction. Exemple : « FolderA ».
inputs.source.filter.suffix	`string`	False	•String	Chaîne de suffixe respectant la casse pour filtrer les documents dans le chemin source pour la traduction. Le plus souvent utilisée pour les extensions de fichier. Exemple : « .txt »
inputs.source.language	`string`	False	•String	Le code de langue pour les documents sources. S’il n’est pas spécifié, la détection automatique est implémentée.
inputs.source.storageSource	`string`	False	•String	Source de stockage pour les entrées. La valeur par défaut est `AzureBlob`.

inputs.targets

Définition des données des cibles et des glossaires.

Paramètre clé	Type	Requis	Paramètres de la demande	Description
inputs.targets	`array`	True	• targetUrl (chaîne) • category (chaîne) • language (chaîne) • glossaries (groupe) • storageSource (chaîne)	Données de cibles et de glossaires pour les documents traduits.
inputs.targets.targetUrl	`string`	True	•String	Localisation de l’emplacement du conteneur pour les documents traduits.
inputs.targets.category	`string`	False	•String	Classification ou catégorie pour la requête de traduction. Exemple : général.
inputs.targets.language	`string`	True	•String	Code de langue cible. Example : « fr ».
inputs.targets.glossaries	`array`	False	• glossaryUrl (chaîne) • format (chaîne) • version (chaîne) • storageSource (chaîne)	AfficherCréer et utiliser des glossaires
inputs.targets.glossaries.glossaryUrl	`string`	True (si vous utilisez des glossaires)	•String	Emplacement du glossaire. L’extension de fichier est utilisée pour extraire la mise en forme si le paramètre de format n’est pas fourni. Si la paire de langues de traduction n’est pas présente dans le glossaire, elle n’est pas appliquée.
inputs.targets.glossaries.format	`string`	False	•String	Format de fichier spécifié pour le glossaire. Pour vérifier si votre format de fichier est pris en charge, consultezObtenir les formats de glossaire pris en charge.
inputs.targets.glossaries.version	`string`	False	•String	Indicateur de version. Exemple : « 2.0 ».
inputs.targets.glossaries.storageSource	`string`	False	•String	Source de stockage pour les glossaires. La valeur par défaut est `_AzureBlob_`.
inputs.targets.storageSource	`string`	False	•String	Stockage source pour les cibles. La valeur par défaut est `_AzureBlob_`.

inputs.storageType

Définition de l’entité de stockage pour les documents d’entrée.

Paramètre clé	Type	Requis	Paramètres de la demande	Description
inputs.storageType	`string`	False	•`Folder` • `File`	Type de stockage de la chaîne source des documents d’entrée. Seules « Dossier » ou « Fichier » sont des valeurs valides.

Options

Définition de la demande de traduction par lot d’entrée.

Paramètre clé	Type	Requis	Paramètres de la demande	Description
options	`object`	False	Informations sources pour les documents d’entrée.
options.experimental	`boolean`	False	•`true` • `false`	Indique si la demande inclut une fonctionnalité expérimentale (le cas échéant). Seules les valeurs booléennes `true` ou `false` sont des valeurs valides.

Exemple de requête

Voici des exemples de demandes de lots :

Notes

Dans les exemples suivants, un accès limité a été accordé au contenu d’un conteneur de stockage Azure à l’aide d’un jeton de signature d’accès partagé (SAS).

Traduction de tous les documents dans un conteneur

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=SDRPMjE4nfrH3csmKLILkT%2Fv3e0Q6SWpssuuQl1NmfM%3D"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?sv=2019-12-12&st=2021-03-05T17%3A49%3A02Z&se=2021-03-13T17%3A49%3A00Z&sr=c&sp=wdl&sig=Sq%2BYdNbhgbq4hLT0o1UUOsTnQJFU590sWYo4BOhhQhs%3D",
                    "language": "fr"
                }
            ]
        }
    ]
}

Traduction de tous les documents d’un conteneur avec application de glossaires

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=SDRPMjE4nfrH3csmKLILkT%2Fv3e0Q6SWpssuuQl1NmfM%3D"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?sv=2019-12-12&st=2021-03-05T17%3A49%3A02Z&se=2021-03-13T17%3A49%3A00Z&sr=c&sp=wdl&sig=Sq%2BYdNbhgbq4hLT0o1UUOsTnQJFU590sWYo4BOhhQhs%3D",
                    "language": "fr",
                    "glossaries": [
                        {
                            "glossaryUrl": "https://my.blob.core.windows.net/glossaries/en-fr.xlf?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=BsciG3NWoOoRjOYesTaUmxlXzyjsX4AgVkt2AsxJ9to%3D",
                            "format": "xliff",
                            "version": "1.2"
                        }
                    ]

                }
            ]
        }
    ]
}

Traduction d’un dossier spécifique dans un conteneur

Veillez à spécifier le nom du dossier (respectant la casse) comme préfixe dans le filtre.

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=SDRPMjE4nfrH3csmKLILkT%2Fv3e0Q6SWpssuuQl1NmfM%3D",
                "filter": {
                    "prefix": "MyFolder/"
                }
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?sv=2019-12-12&st=2021-03-05T17%3A49%3A02Z&se=2021-03-13T17%3A49%3A00Z&sr=c&sp=wdl&sig=Sq%2BYdNbhgbq4hLT0o1UUOsTnQJFU590sWYo4BOhhQhs%3D",
                    "language": "fr"
                }
            ]
        }
    ]
}

Traduction d’un document spécifique dans un conteneur

Spécifiez « storageType » : File.
Créez l’URL source et le jeton SAS pour l’objet blob/document spécifique.
Spécifiez le nom de fichier cible dans le cadre de l’URL cible, bien que le jeton SAS soit toujours pour le conteneur.

Cet exemple de requête montre un document unique traduit en deux langues cibles.

{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en/source-english.docx?sv=2019-12-12&st=2021-01-26T18%3A30%3A20Z&se=2021-02-05T18%3A30%3A00Z&sr=c&sp=rl&sig=d7PZKyQsIeE6xb%2B1M4Yb56I%2FEEKoNIF65D%2Fs0IFsYcE%3D"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-Spanish.docx?sv=2019-12-12&st=2021-01-26T18%3A31%3A11Z&se=2021-02-05T18%3A31%3A00Z&sr=c&sp=wl&sig=AgddSzXLXwHKpGHr7wALt2DGQJHCzNFF%2F3L94JHAWZM%3D",
                    "language": "es"
                },
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-German.docx?sv=2019-12-12&st=2021-01-26T18%3A31%3A11Z&se=2021-02-05T18%3A31%3A00Z&sr=c&sp=wl&sig=AgddSzXLXwHKpGHr7wALt2DGQJHCzNFF%2F3L94JHAWZM%3D",
                    "language": "de"
                }
            ]
        }
    ]
}

Codes d’état de réponse

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

Code d’état	Description
202	Accepté. La demande ayant réussi et la demande de lot ont été créées. L’en-tête Operation-Location indique une URL d’état avec la chaîne ID.HeadersOperation-Location: de l’opération
400	Demande incorrecte. Demande non valide. Vérifiez les paramètres d’entrée.
401	Non autorisé. Vérifiez vos informations d’identification.
429	Le taux de demandes est trop élevé.
500	Erreur interne du serveur.
503	Le service est actuellement indisponible. Réessayez plus tard.
Autres codes d’état	• Trop de demandes • Serveur temporaire indisponible

Réponse d’erreur

Paramètre clé	Type	Description
code	`string`	Enums contenant des codes d’erreur généraux. Valeurs possibles : InternalServerError InvalidArgument InvalidRequest RequestRateTooHigh ResourceNotFound ServiceUnavailable Non autorisé
message	`string`	Obtient un message d’erreur général.
innerError	InnerTranslationError	Nouveau format d’erreur interne conforme aux instructions de l’API Azure AI services. Ce message d’erreur contient les propriétés requises : ErrorCode, message et cible de propriétés facultatives, détails(paire valeur clé) et erreur interne (il peut être imbriqué).
inner.Errorcode	`string`	Obtient la chaîne d’erreur de code.
innerError.message	`string`	Obtient un message d’erreur général.
innerError.target	`string`	Obtient la source de l’erreur. Par exemple, ce serait `documents` ou `document id` si le document était invalide.

Exemples

Exemple de réponse positive

Les informations suivantes sont retournées dans une réponse positive.

Vous trouverez l’ID de travail dans la valeur de l’URL de l’en-tête de réponse Operation-Location de la méthode POST. Le dernier paramètre de l’URL est l’ID de travail de l’opération (la chaîne qui suit "/operation/").

Operation-Location: https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/operation/0FA2822F-4C2A-4317-9C20-658C801E0E55

Exemple de réponse d’erreur

{
  "error": {
    "code": "ServiceUnavailable",
    "message": "Service is temporary unavailable",
    "innerError": {
      "code": "ServiceTemporaryUnavailable",
      "message": "Service is currently unavailable.  Please try again later"
    }
  }
}

Étapes suivantes

Suivez notre guide de démarrage rapide pour en savoir plus sur l’utilisation du service Traduction de document et de la bibliothèque de client.

Bien démarrer avec la traduction de documentation