Clientbibliothek für die Azure-Textübersetzung für .NET– Version 1.0.0-beta.1

Artikel
2023-04-20

Bei der Textübersetzung handelt es sich um ein cloudbasiertes REST-API-Feature des Übersetzungsdiensts, das die Technologie der neuronalen maschinellen Übersetzung verwendet, um eine schnelle und genaue Übersetzung von Ausgangstext zu Zieltext in Echtzeit in allen unterstützten Sprachen zu ermöglichen.

Verwenden Sie die Clientbibliothek für die Textübersetzung für .NET für Folgendes:

Gibt eine Liste der Sprachen zurück, die von Übersetzungs-, Transliteraten- und Wörterbuchvorgängen unterstützt werden.
Rendern von Text in einer einzelnen Quellsprache in mehreren Zielsprachentexten mit einer einzelnen Anforderung.
Konvertieren von Text einer Quellsprache in Buchstaben eines anderen Skripts.
Gibt äquivalente Wörter für den Quellbegriff in der Zielsprache zurück.
Gibt grammatikalische Struktur- und Kontextbeispiele für das Quellbegriffs- und Zielbegriffspaar zurück.

Quellcode | API-Referenzdokumentation | Produktdokumentation

Erste Schritte

Installieren des Pakets

Installieren Sie die Clientbibliothek für die Azure-Textübersetzung für .NET mit NuGet:

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

Diese Tabelle gibt Aufschluss über die Beziehung zwischen SDK-Versionen und unterstützten API-Versionen des Diensts:

SDK-Version	Unterstützte API-Version des Diensts
1.0.0-beta.1	3.0

Voraussetzungen

Ein Azure-Abonnement.
Eine vorhandene Translator-Dienst- oder Cognitive Services-Ressource. Sie können eine Translator-Ressource erstellen, indem Sie eine Translator-Ressource erstellen.

Authentifizieren des Clients

Die Interaktion mit dem Dienst mithilfe der Clientbibliothek beginnt mit dem Erstellen einer instance der TextTranslationClient-Klasse. Sie benötigen einen API-Schlüssel oder TokenCredential zum Instanziieren eines Clientobjekts. Weitere Informationen zur Authentifizierung mit Cognitive Services finden Sie unter Authentifizieren von Anforderungen an den Translator-Dienst.

Abrufen eines API-Schlüssels

Sie können die Informationen API key , endpointund Region über die Cognitive Services-Ressource oder die Translator-Dienstressource im Azure-Portal abrufen.

Alternativ können Sie den folgenden Azure CLI-Codeausschnitt verwenden, um den API-Schlüssel aus der Translator-Dienstressource abzurufen.

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

Erstellen eines mithilfe `TextTranslationClient` eines API-Schlüssels und Regionsanmeldeinformationen

Nachdem Sie über den Wert für den API-Schlüssel und die Region verfügen, erstellen Sie eine AzureKeyCredential. Dadurch können Sie den API-Schlüssel aktualisieren, ohne einen neuen Client zu erstellen.

Mit dem Wert des Endpunkts AzureKeyCredential und einem Regionkönnen Sie textTranslationClient erstellen:

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

Wichtige Begriffe

`TextTranslationClient`

Eine TextTranslationClient ist die primäre Schnittstelle für Entwickler, die die Clientbibliothek für die Textübersetzung verwenden. Es bietet sowohl synchrone als auch asynchrone Vorgänge für den Zugriff auf eine bestimmte Verwendung des Textübersetzungs, z. B. das Abrufen unterstützter Sprachenerkennung oder Textübersetzung.

Eingabe

Ein Textelement (string) ist eine einzelne Eingabeeinheit, die von den Übersetzungsmodellen im Translator-Dienst verarbeitet werden soll. Vorgänge auf TextTranslationClient können ein einzelnes Textelement oder eine Auflistung von Textelementen annehmen. Informationen zur Länge von Textelementen, zur maximalen Anforderungsgröße und zur unterstützten Textcodierung finden Sie hier.

Rückgabewert

Rückgabewerte, z Response<IReadOnlyList<TranslatedTextItem>>. B. , sind das Ergebnis eines Textübersetzungsvorgangs. Es enthält ein Array mit einem Ergebnis für jede Zeichenfolge im Eingabearray. Der Rückgabewert eines Vorgangs kann optional auch Informationen zum Eingabetextelement enthalten (z. B. erkannte Sprache).

Threadsicherheit

Wir garantieren, dass alle Client-instance Methoden threadsicher und voneinander unabhängig sind (Richtlinie). Dadurch wird sichergestellt, dass die Empfehlung, Clientinstanzen wiederzuverwenden, immer sicher ist, auch über Threads hinweg.

Zusätzliche Konzepte

Beispiele

Der folgende Abschnitt enthält mehrere Codeausschnitte, die das clientoben erstellte verwenden, und behandelt die Standard Features, die in dieser Clientbibliothek vorhanden sind. Obwohl die meisten der folgenden Codeausschnitte asynchrone Dienstaufrufe verwenden, beachten Sie, dass das Azure.AI.Translation.Text Paket sowohl synchrone als auch asynchrone APIs unterstützt.

Abrufen unterstützter Sprachen

Ruft die Sprachen ab, die derzeit von anderen Translator-Vorgängen unterstützt werden.

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}");
}

Beispiele zur Verwendung des Endpunkts languages finden Sie hier.

Eine konzeptionelle Erläuterung der Sprachen finden Sie in der Servicedokumentation.

Translate

Rendert Text in einer einzelnen Quellsprache mit einer einzelnen Anforderung in Texte in mehreren Zielsprachen.

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}");
}

Beispiele zur Verwendung des Endpunkts translate finden Sie hier.

Eine konzeptionelle Erläuterung von translate finden Sie in der Servicedokumentation.

Transliterate

Konvertiert Zeichen oder Buchstaben einer Quellsprache in die entsprechenden Zeichen oder Buchstaben einer Zielsprache.

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}");
}

Beispiele zur Verwendung des Endpunkts transliterate finden Sie hier.

Eine konzeptionelle Erläuterung der Transliterate finden Sie in der Servicedokumentation.

Satz unterbrechen

Erkennt die Positionierung von Satzgrenzen in einem Textabschnitt.

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}");
}

Beispiele zur Verwendung des Endpunkts break sentece finden Sie hier.

Eine konzeptionelle Erläuterung der Unterbrechungssätze finden Sie in der Dienstdokumentation.

Wörterbuchsuche

Gibt äquivalente Wörter für den Quellbegriff in der Zielsprache zurück.

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}");
}

Beispiele zur Verwendung des Endpunkts dictionary lookup finden Sie hier.

Eine konzeptionelle Erläuterung der Wörterbuchsuche finden Sie in der Dienstdokumentation.

Wörterbuchbeispiele

Gibt grammatikalische Struktur- und Kontextbeispiele für das Quellbegriffs- und Zielbegriffspaar zurück.

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}");
}

Beispiele zur Verwendung des Endpunkts dictionary examples finden Sie hier.

Eine konzeptionelle Erläuterung der Wörterbuchbeispiele finden Sie in der Dienstdokumentation.

Problembehandlung

Wenn Sie mit dem Übersetzerdienst mithilfe der Clientbibliothek für die Textübersetzung interagieren, entsprechen die vom Translator-Dienst zurückgegebenen Fehler denselben HTTP-status Codes, die für REST-API-Anforderungen zurückgegeben werden.

Wenn Sie beispielsweise eine Übersetzungsanforderung ohne Zielübersetzungssprache übermitteln, wird ein 400 Fehler zurückgegeben, der auf "Ungültige Anforderung" hinweist.

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());
}

Sie werden feststellen, dass zusätzliche Informationen protokolliert werden, z. B. die Clientanforderungs-ID des Vorgangs.

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

Einrichten der Konsolenprotokollierung

Die einfachste Möglichkeit, die Protokolle anzuzeigen, besteht darin, die Konsolenprotokollierung zu aktivieren. Verwenden Sie die AzureEventSourceListener.CreateConsoleLogger-Methode, um einen Azure SDK-Protokolllistener zu erstellen, der Nachrichten an die Konsole ausgibt.

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

Weitere Informationen zu anderen Protokollierungsmechanismen finden Sie hier.

Nächste Schritte

Beispiele zur Verwendung dieser Clientbibliothek sind in diesem GitHub-Repository verfügbar. Für jeden Standard Funktionsbereich werden Beispiele bereitgestellt, und für jeden Bereich werden Beispiele sowohl im Synchronisierungs- als auch im asynchronen Modus bereitgestellt.

Mitwirken

Ausführliche Informationen zum Erstellen, Testen und Mitwirken zu dieser Bibliothek finden Sie im CONTRIBUTING.md .

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Weitere Informationen finden Sie unter cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Freigeben über