你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 .NET 的 Azure 文本翻译客户端库 - 版本 1.0.0-beta.1

项目
04/20/2023

文本翻译是翻译器服务的基于云的 REST API 功能，它使用神经网络机器翻译技术跨所有支持的语言实现快速准确的源到目标实时文本翻译。

使用适用于 .NET 的文本翻译客户端库可以：

返回 Translate、Transliterate 和 Dictionary 操作支持的语言列表。
使用单个请求将单个源语言文本呈现为多个目标语言文本。
将源语言的文本转换为不同脚本的字母。
返回目标语言中源术语的等效字词。
返回源术语和目标术语对的语法结构和上下文示例。

源代码 | API 参考文档 | 产品文档

入门

安装包

使用 NuGet 安装适用于 .NET 的 Azure 文本翻译客户端库：

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

此表显示了 SDK 版本与服务支持的 API 版本之间的关系：

SDK 版本	服务支持的 API 版本
1.0.0-beta.1	3.0

先决条件

一个 Azure 订阅。
现有的翻译器服务或认知服务资源。可以在创建翻译器资源后创建翻译器资源。

验证客户端

使用客户端库与服务的交互首先创建 TextTranslationClient 类的实例。需要 一个 API 密钥 或 TokenCredential 来实例化客户端对象。有关使用认知服务进行身份验证的详细信息，请参阅对翻译器服务的请求进行身份验证。

获取 API 密钥

可以从 Azure 门户中的endpoint认知服务资源或翻译器服务资源信息获取、 API key 和 Region 。

或者，使用以下 Azure CLI 代码片段从翻译器服务资源获取 API 密钥。

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

`TextTranslationClient`使用 API 密钥和区域凭据创建

获得 API 密钥和区域的值后，请 AzureKeyCredential创建。这样，无需创建新客户端即可更新 API 密钥。

使用终结点 AzureKeyCredential 的值和， Region可以创建 TextTranslationClient：

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

关键概念

`TextTranslationClient`

是 TextTranslationClient 使用文本翻译客户端库的开发人员的主要接口。它提供同步和异步操作来访问文本翻译的特定用途，例如获取支持的语言检测或文本翻译。

输入

文本元素 (string) ，是翻译器服务中的翻译模型要处理的单个输入单元。对 TextTranslationClient 的操作可能采用单个文本元素或文本元素集合。有关文本元素长度限制、最大请求大小和支持的文本编码，请参阅此处。

返回值

返回值（如 Response<IReadOnlyList<TranslatedTextItem>>）是文本转换操作的结果，它包含输入数组中每个字符串的一个结果数组。操作的返回值还可以选择性地包含有关输入文本元素的信息， (例如检测到的语言) 。

线程安全

我们保证所有客户端实例方法都是线程安全的，并且彼此独立 (准则) 。这可确保重用客户端实例的建议始终是安全的，即使在线程之间也是如此。

其他概念

示例

以下部分提供了使用client上面创建的多个代码片段，并介绍了此客户端库中存在的main功能。尽管下面的大多数代码片段都使用异步服务调用，但请记住， Azure.AI.Translation.Text 包同时支持同步 API 和异步 API。

获取支持的语言

获取翻译器的其他操作当前支持的语言集。

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

有关使用终结点的示例， languages 请参阅此处的更多示例。

有关语言的概念性讨论，请参阅服务文档。

Translate

使用单个请求将单个源语言文本呈现为多个目标语言文本。

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

有关使用终结点的示例， translate 请参阅此处的更多示例。

有关翻译的概念性讨论，请参阅服务文档。

Transliterate

将源语言的字符或字母转换为目标语言的对应字符或字母。

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

有关使用终结点的示例， transliterate 请参阅此处的更多示例。

有关 transliterate 的概念性讨论，请参阅服务文档。

断句

标识文本段中的句子边界的位置。

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

有关使用终结点的示例， break sentece 请参阅此处的更多示例。

有关断句的概念性讨论，请参阅服务文档。

字典查找

返回源术语在目标语言中的等效字词。

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

有关使用终结点的示例， dictionary lookup 请参阅此处的更多示例。

有关字典查找的概念性讨论，请参阅服务文档。

字典示例

返回源术语和目标术语对的语法结构和上下文示例。

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

有关使用终结点的示例， dictionary examples 请参阅此处的更多示例。

有关字典示例的概念性讨论，请参阅服务文档。

故障排除

使用文本翻译客户端库与翻译服务交互时，翻译器服务返回的错误对应于为 REST API 请求返回的相同 HTTP 状态代码。

例如，如果提交没有目标翻译语言的翻译请求，则会返回一个 400 错误，指示“错误请求”。

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

你会注意到记录了其他信息，例如操作的客户端请求 ID。

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

设置控制台日志记录

查看日志的最简单方法是启用控制台日志记录。若要创建将消息输出到控制台的 Azure SDK 日志侦听器，请使用 AzureEventSourceListener.CreateConsoleLogger 方法。

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

若要了解有关其他日志记录机制的详细信息，请参阅此处。

后续步骤

此 GitHub 存储库中提供了演示如何使用此客户端库的示例。每个main功能区域提供示例，每个区域都以同步和异步模式提供示例。

供稿

有关构建、测试和参与此库的详细信息，请参阅 CONTRIBUTING.md 。

本项目欢迎贡献和建议。大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。有关详细信息，请访问 cla.microsoft.com。

提交拉取请求时，CLA 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。直接按机器人提供的说明操作。只需使用 CLA 对所有存储库执行一次这样的操作。

此项目采用了 Microsoft 开放源代码行为准则。有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与联系。

通过

适用于 .NET 的 Azure 文本翻译客户端库 - 版本 1.0.0-beta.1

入门

安装包

先决条件

验证客户端

获取 API 密钥

`TextTranslationClient`使用 API 密钥和区域凭据创建

关键概念

`TextTranslationClient`

输入

返回值

线程安全

其他概念

示例

获取支持的语言

Translate

Transliterate

断句

字典查找

字典示例

故障排除

设置控制台日志记录

后续步骤

供稿

其他资源

通过

适用于 .NET 的 Azure 文本翻译客户端库 - 版本 1.0.0-beta.1

入门

安装包

先决条件

验证客户端

获取 API 密钥

TextTranslationClient使用 API 密钥和区域凭据创建

关键概念

TextTranslationClient

输入

返回值

线程安全

其他概念

示例

获取支持的语言

Translate

Transliterate

断句

字典查找

字典示例

故障排除

设置控制台日志记录

后续步骤

供稿

其他资源

`TextTranslationClient`使用 API 密钥和区域凭据创建

`TextTranslationClient`