Bibliothèque cliente De traduction de texte Azure pour .NET - version 1.0.0-beta.1

  • Article

La traduction de texte est une fonctionnalité d’API REST basée sur le cloud du service Traducteur qui utilise la technologie de traduction automatique neuronale pour permettre une traduction de texte source en temps réel rapide et précise dans toutes les langues prises en charge.

Utilisez la bibliothèque cliente de traduction de texte pour .NET pour :

  • Retourne une liste des langues prises en charge par les opérations Translate, Transliterate et Dictionary.

  • Restituez du texte en langue source unique dans plusieurs textes de langue cible avec une seule requête.

  • Convertissez le texte d’une langue source en lettres d’un autre script.

  • Retourne des mots équivalents pour le terme source dans la langue cible.

  • Retourne des exemples de structure grammaticale et de contexte pour la paire terme source et terme cible.

| Code sourceDocumentation de référence sur les | API Documentation produit

Prise en main

Installer le package

Installez la bibliothèque cliente De traduction de texte Azure pour .NET avec NuGet :

dotnet add package Azure.AI.Translation.Text --prerelease

Ce tableau montre la relation entre les versions du kit de développement logiciel (SDK) et les versions d’API prises en charge du service :

Version du SDK Version d’API prise en charge du service
1.0.0-beta.1 3.0

Prérequis

Authentifier le client

L’interaction avec le service à l’aide de la bibliothèque cliente commence par la création d’un instance de la classe TextTranslationClient. Vous aurez besoin d’une clé API ou TokenCredential pour instancier un objet client. Pour plus d’informations sur l’authentification auprès de Cognitive Services, consultez Authentifier les demandes auprès du service Translator.

Obtenir une clé API

Vous pouvez obtenir les endpointinformations et RegionAPI key à partir de la ressource Cognitive Services ou du service Translator dans le portail Azure.

Vous pouvez également utiliser l’extrait de code Azure CLI ci-dessous pour obtenir la clé API à partir de la ressource du service Translator.

az cognitiveservices account keys list --resource-group <your-resource-group-name> --name <your-resource-name>

Créer un à l’aide d’une TextTranslationClient clé API et d’informations d’identification de région

Une fois que vous avez la valeur de la clé API et de la région, créez un AzureKeyCredential. Cela vous permettra de mettre à jour la clé API sans créer de client.

Avec la valeur du point de terminaison et un Region, AzureKeyCredential vous pouvez créer le TextTranslationClient :

AzureKeyCredential credential = new("<apiKey>");
TextTranslationClient client = new(credential, "<region>");

Concepts clés

TextTranslationClient

A TextTranslationClient est l’interface principale pour les développeurs qui utilisent la bibliothèque cliente de traduction de texte. Il fournit des opérations synchrones et asynchrones pour accéder à une utilisation spécifique du traducteur de texte, comme obtenir la détection des langues prises en charge ou la traduction de texte.

Entrée

Un élément de texte (string) est une unité d’entrée unique à traiter par les modèles de traduction dans le service Translator. Les opérations sur TextTranslationClient peuvent prendre un seul élément de texte ou une collection d’éléments de texte. Pour connaître les limites de longueur des éléments de texte, la taille maximale des requêtes et l’encodage de texte pris en charge, consultez ici.

Valeur retournée

Les valeurs de retour, telles que Response<IReadOnlyList<TranslatedTextItem>>, sont le résultat d’une opération de traduction de texte. Il contient un tableau avec un résultat pour chaque chaîne dans le tableau d’entrée. La valeur de retour d’une opération peut également inclure éventuellement des informations sur l’élément de texte d’entrée (par exemple, la langue détectée).

Sécurité des threads

Nous garantissons que toutes les méthodes de instance client sont sécurisées pour les threads et indépendantes les unes des autres (recommandations). Cela garantit que la recommandation de réutilisation des instances clientes est toujours sécurisée, même entre les threads.

Concepts supplémentaires

Options clientes | Accès à la réponse | Opérations de longue durée | Gestion des défaillances | Diagnostics | Moqueur | Durée de vie du client

Exemples

La section suivante fournit plusieurs extraits de code à l’aide de ce client qui a été créé ci-dessus et décrit les fonctionnalités main présentes dans cette bibliothèque cliente. Bien que la plupart des extraits de code ci-dessous utilisent des appels de service asynchrones, gardez à l’esprit que le Azure.AI.Translation.Text package prend en charge les API synchrones et asynchrones.

Obtenir les langues prises en charge

Permet d’obtenir l’ensemble des langues actuellement prises en charge par d’autres opérations de Translator.

try
{
    Response<GetLanguagesResult> response = await client.GetLanguagesAsync(cancellationToken: CancellationToken.None).ConfigureAwait(false);
    GetLanguagesResult languages = response.Value;

    Console.WriteLine($"Number of supported languages for translate operations: {languages.Translation.Count}.");
}
catch (RequestFailedException exception)
{
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
}

Pour obtenir des exemples sur l’utilisation du point de languages terminaison, reportez-vous à d’autres exemples ici.

Reportez-vous à la documentation du service pour une présentation conceptuelle des langues.

Translate

Restitue un texte en langage source unique dans plusieurs textes de langue cible avec une seule requête.

try
{
    string targetLanguage = "cs";
    string inputText = "This is a test.";

    Response<IReadOnlyList<TranslatedTextItem>> response = await client.TranslateAsync(targetLanguage, inputText).ConfigureAwait(false);
    IReadOnlyList<TranslatedTextItem> translations = response.Value;
    TranslatedTextItem translation = translations.FirstOrDefault();

    Console.WriteLine($"Detected languages of the input text: {translation?.DetectedLanguage?.Language} with score: {translation?.DetectedLanguage?.Score}.");
    Console.WriteLine($"Text was translated to: '{translation?.Translations?.FirstOrDefault().To}' and the result is: '{translation?.Translations?.FirstOrDefault()?.Text}'.");
}
catch (RequestFailedException exception)
{
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
}

Pour obtenir des exemples sur l’utilisation du point de translate terminaison, reportez-vous à d’autres exemples ici.

Reportez-vous à la documentation du service pour une discussion conceptuelle sur translate.

Transliterate

Convertit des caractères ou des lettres d’une langue source en caractères ou lettres correspondants d’une langue cible.

try
{
    string language = "zh-Hans";
    string fromScript = "Hans";
    string toScript = "Latn";

    string inputText = "这是个测试。";

    Response<IReadOnlyList<TransliteratedText>> response = await client.TransliterateAsync(language, fromScript, toScript, inputText).ConfigureAwait(false);
    IReadOnlyList<TransliteratedText> transliterations = response.Value;
    TransliteratedText transliteration = transliterations.FirstOrDefault();

    Console.WriteLine($"Input text was transliterated to '{transliteration?.Script}' script. Transliterated text: '{transliteration?.Text}'.");
}
catch (RequestFailedException exception)
{
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
}

Pour obtenir des exemples sur l’utilisation du point de transliterate terminaison, reportez-vous à d’autres exemples ici.

Reportez-vous à la documentation du service pour une discussion conceptuelle sur le translittération.

Arrêter la phrase

Identifie le positionnement des limites de phrases dans du texte.

try
{
    string inputText = "How are you? I am fine. What did you do today?";

    Response<IReadOnlyList<BreakSentenceItem>> response = await client.FindSentenceBoundariesAsync(inputText).ConfigureAwait(false);
    IReadOnlyList<BreakSentenceItem> brokenSentences = response.Value;
    BreakSentenceItem brokenSentence = brokenSentences.FirstOrDefault();

    Console.WriteLine($"Detected languages of the input text: {brokenSentence?.DetectedLanguage?.Language} with score: {brokenSentence?.DetectedLanguage?.Score}.");
    Console.WriteLine($"The detected sentece boundaries: '{string.Join(",", brokenSentence?.SentLen)}'.");

}
catch (RequestFailedException exception)
{
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
}

Pour obtenir des exemples sur l’utilisation du point de break sentece terminaison, reportez-vous à d’autres exemples ici.

Reportez-vous à la documentation du service pour une discussion conceptuelle sur la phrase d’arrêt.

Recherche dans le dictionnaire

Retourne des mots équivalents pour le terme source dans la langue cible.

try
{
    string sourceLanguage = "en";
    string targetLanguage = "es";
    string inputText = "fly";

    Response<IReadOnlyList<DictionaryLookupItem>> response = await client.LookupDictionaryEntriesAsync(sourceLanguage, targetLanguage, inputText).ConfigureAwait(false);
    IReadOnlyList<DictionaryLookupItem> dictionaryEntries = response.Value;
    DictionaryLookupItem dictionaryEntry = dictionaryEntries.FirstOrDefault();

    Console.WriteLine($"For the given input {dictionaryEntry?.Translations?.Count} entries were found in the dictionary.");
    Console.WriteLine($"First entry: '{dictionaryEntry?.Translations?.FirstOrDefault()?.DisplayTarget}', confidence: {dictionaryEntry?.Translations?.FirstOrDefault()?.Confidence}.");

}
catch (RequestFailedException exception)
{
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
}

Pour obtenir des exemples sur l’utilisation du point de dictionary lookup terminaison, reportez-vous à d’autres exemples ici.

Reportez-vous à la documentation du service pour une discussion conceptuelle sur la recherche de dictionnaire.

Exemples de dictionnaire

Renvoie des exemples de structure grammaticale et de contexte pour la paire de termes sources et de termes cibles.

try
{
    string sourceLanguage = "en";
    string targetLanguage = "es";
    IEnumerable<InputTextWithTranslation> inputTextElements = new[]
    {
        new InputTextWithTranslation("fly", "volar")
    };

    Response<IReadOnlyList<DictionaryExampleItem>> response = await client.LookupDictionaryExamplesAsync(sourceLanguage, targetLanguage, inputTextElements).ConfigureAwait(false);
    IReadOnlyList<DictionaryExampleItem> dictionaryEntries = response.Value;
    DictionaryExampleItem dictionaryEntry = dictionaryEntries.FirstOrDefault();

    Console.WriteLine($"For the given input {dictionaryEntry?.Examples?.Count} examples were found in the dictionary.");
    DictionaryExample firstExample = dictionaryEntry?.Examples?.FirstOrDefault();
    Console.WriteLine($"Example: '{string.Concat(firstExample.TargetPrefix, firstExample.TargetTerm, firstExample.TargetSuffix)}'.");

}
catch (RequestFailedException exception)
{
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
}

Pour obtenir des exemples sur l’utilisation du point de dictionary examples terminaison, reportez-vous à d’autres exemples ici.

Reportez-vous à la documentation du service pour obtenir une présentation conceptuelle des exemples de dictionnaire.

Dépannage

Lorsque vous interagissez avec le service Translator à l’aide de la bibliothèque cliente Traduction de texte, les erreurs retournées par le service Translator correspondent aux mêmes codes de status HTTP retournés pour les demandes d’API REST.

Par exemple, si vous envoyez une demande de traduction sans langue de traduction cible, une 400 erreur est renvoyée, indiquant « Demande incorrecte ».

try
{
    var translation = client.TranslateAsync(Array.Empty<string>(), new[] { new InputText { Text = "This is a Test" } }).ConfigureAwait(false);
}
catch (RequestFailedException e)
{
    Console.WriteLine(e.ToString());
}

Vous remarquerez que des informations supplémentaires sont enregistrées, telles que l’ID de demande client de l’opération.

Message:
    Azure.RequestFailedException: Service request failed.
    Status: 400 (Bad Request)

Content:
    {"error":{"code":400036,"message":"The target language is not valid."}}

Headers:
    X-RequestId: REDACTED
    Access-Control-Expose-Headers: REDACTED
    X-Content-Type-Options: REDACTED
    Strict-Transport-Security: REDACTED
    Date: Mon, 27 Feb 2023 23:31:37 GMT
    Content-Type: text/plain; charset=utf-8
    Content-Length: 71

Configuration de la journalisation de la console

Le moyen le plus simple de voir les journaux consiste à activer la journalisation de la console. Pour créer un écouteur de journal du Kit de développement logiciel (SDK) Azure qui génère des messages dans la console, utilisez la méthode AzureEventSourceListener.CreateConsoleLogger.

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

Pour en savoir plus sur les autres mécanismes de journalisation , consultez ici.

Étapes suivantes

Des exemples montrant comment utiliser cette bibliothèque cliente sont disponibles dans ce dépôt GitHub. Des exemples sont fournis pour chaque zone fonctionnelle main, et pour chaque zone, les exemples sont fournis en mode synchronisé et asynchrone.

Contribution

Consultez la CONTRIBUTING.md pour plus d’informations sur la création, le test et la contribution à cette bibliothèque.

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, consultez cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.