Azure.AI.Translation.Text 1.0.0

Azure 文本翻译 .NET 客户端库

文本翻译是翻译服务基于云的 REST API 功能，使用神经机器翻译技术实现实时、跨所有支持语言的高效且准确的原语到目标语的翻译。

使用 .NET 文本翻译客户端库可以

• 返回支持 Translate、Transliterate 和字典操作的受支持语言列表。

• 单次请求将单个源语言文本渲染为多种目标语言文本。

• 将源语言文本转换为不同脚本字母。

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

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

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

入门

安装包

使用 NuGet 安装 Azure Text Translation .NET 客户端库

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

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

先决条件

• 一个 Azure 订阅。
• 现有的翻译服务或认知服务资源。您可以根据创建翻译资源来创建翻译资源。

认证客户端

使用客户端库与服务的交互从创建 TextTranslationClient 类的实例开始。您需要一个 API 密钥 或 TokenCredential 来实例化客户端对象。有关与认知服务认证的更多信息，请参阅认证请求到翻译服务。

获取 API 密钥

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

或者，使用下面的 Azure CLI 段落从翻译服务资源获取 API 密钥。

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

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

一旦您有了 API 密钥和区域的信息，创建一个 AzureKeyCredential。这将允许您在不创建新客户端的情况下更新 API 密钥。

使用端点、AzureKeyCredential 和 Region 的值，您可以创建 TextTranslationClient

string endpoint = "<Text Translator Resource Endpoint>";
string apiKey = "<Text Translator Resource API Key>";
string region = "<Text Translator Azure Region>";
TextTranslationClient client = new TextTranslationClient(new AzureKeyCredential(apiKey), new Uri(endpoint), region);

使用 Microsoft Entra ID 创建 TextTranslationClient

在大多数示例中，使用客户端 API 密钥认证，但您也可以使用Azure Identity 库使用 Microsoft Entra ID 认证。要使用以下所示的 DefaultAzureCredential 提供程序，请安装 Azure.Identity 包

dotnet add package Azure.Identity

为您的资源创建一个自定义子域以使用此类型的认证。使用此值作为 Text Translator Custom Endpoint 的 endpoint 变量的值。

您还需要注册一个新的 Microsoft Entra 应用程序 并通过将 "Cognitive Services User" 角色分配给您的服务主体来授予访问权限。有关 Microsoft Entra 认证的更多信息，请此处。

将 Microsoft Entra 应用程序的 客户端 ID、租户 ID 和 客户端密钥 设置为环境变量：AZURE_CLIENT_ID、AZURE_TENANT_ID、AZURE_CLIENT_SECRET。"DefaultAzureCredential" 构造函数使用这些变量来创建您的凭据。

string endpoint = "<Text Translator Custom Endpoint>";
DefaultAzureCredential credential = new DefaultAzureCredential();
TextTranslationClient client = new TextTranslationClient(credential, new Uri(endpoint));

关键概念

TextTranslationClient

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

输入

文本元素（string），是翻译服务中翻译模型要处理的单个输入单元。在 TextTranslationClient 上的操作可以接受单个文本元素或文本元素的集合。有关文本元素长度限制、请求大小的最大值和支持的文本编码，请参阅此处。

返回值

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

线程安全

我们保证所有客户端实例方法都是线程安全的，彼此独立（有关指南，请参阅此处）。这确保了复用客户端实例的建议总是安全的，即使在多线程环境下也是如此。

其他概念

客户端选项 | 访问响应 | 长时间运行的操作 | 处理失败 | 诊断 | 模拟 | 客户端生命周期

示例

以下部分提供了几个使用上述创建的 client 的代码片段，涵盖了此客户端库中的主要功能。尽管以下片段使用同步服务调用，但请注意，Azure.AI.Translation.Text 包支持同步和异步 API。

获取支持的语言

获取翻译中当前支持的语言集合。

try
{
    Response<GetSupportedLanguagesResult> response = client.GetSupportedLanguages(cancellationToken: CancellationToken.None);
    GetSupportedLanguagesResult 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 = client.Translate(targetLanguage, inputText);
    IReadOnlyList<TranslatedTextItem> translations = response.Value;
    TranslatedTextItem translation = translations.FirstOrDefault();

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

Translate 方式提供了一个带有 TextTranslationTranslateOptions 参数的方便的重载。此示例演示了使用选项重载，通过单个请求将单个源语言渲染到多个目标语言。

try
{
    TextTranslationTranslateOptions options = new TextTranslationTranslateOptions(
        targetLanguages: new[] { "cs", "es", "de" },
        content: new[] { "This is a test." }
    );

    Response<IReadOnlyList<TranslatedTextItem>> response = client.Translate(options);
    IReadOnlyList<TranslatedTextItem> translations = response.Value;

    foreach (TranslatedTextItem translation in translations)
    {
        Console.WriteLine($"Detected languages of the input text: {translation?.DetectedLanguage?.Language} with score: {translation?.DetectedLanguage?.Confidence}.");

        Console.WriteLine($"Text was translated to: '{translation?.Translations?.FirstOrDefault().TargetLanguage}' and the result is: '{translation?.Translations?.FirstOrDefault()?.Text}'.");
    }
}
catch (RequestFailedException exception)
{
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
}

此示例演示了使用 TextTranslationTranslateOptions 参数在单个调用中进行翻译和转写。将必需参数传递到构造函数，使用对象初始化器设置可选参数。

try
{
    TextTranslationTranslateOptions options = new TextTranslationTranslateOptions(
        targetLanguage: "zh-Hans",
        content: "hudha akhtabar.")
    {
        FromScript = "Latn",
        SourceLanguage = "ar",
        ToScript = "Latn"
    };

    Response<IReadOnlyList<TranslatedTextItem>> response = client.Translate(options);
    IReadOnlyList<TranslatedTextItem> translations = response.Value;
    TranslatedTextItem translation = translations.FirstOrDefault();

    Console.WriteLine($"Source Text: {translation.SourceText.Text}");
    Console.WriteLine($"Translation: '{translation?.Translations?.FirstOrDefault()?.Text}'.");
    Console.WriteLine($"Transliterated text ({translation?.Translations?.FirstOrDefault()?.Transliteration?.Script}): {translation?.Translations?.FirstOrDefault()?.Transliteration?.Text}");
}
catch (RequestFailedException exception)
{
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
}

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

请参阅服务文档以了解 翻译 的概念讨论。

转写

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

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

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

    Response<IReadOnlyList<TransliteratedText>> response = client.Transliterate(language, fromScript, toScript, inputText);
    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}");
}

使用单个 TextTranslationTransliterateOptions 参数提供转写的便捷重载。以下是演示其使用方法的示例的修改版本。

try
{
    TextTranslationTransliterateOptions options = new TextTranslationTransliterateOptions(
        language: "zh-Hans",
        fromScript: "Hans",
        toScript: "Latn",
        content: "这是个测试。"
    );

    Response<IReadOnlyList<TransliteratedText>> response = client.Transliterate(options);
    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 端点的示例，请参阅更多示例 这里。

请参阅服务文档以了解 转写 的概念讨论。

句子分割

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

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

    Response<IReadOnlyList<BreakSentenceItem>> response = client.FindSentenceBoundaries(inputText);
    IReadOnlyList<BreakSentenceItem> brokenSentences = response.Value;
    BreakSentenceItem brokenSentence = brokenSentences.FirstOrDefault();

    Console.WriteLine($"Detected languages of the input text: {brokenSentence?.DetectedLanguage?.Language} with score: {brokenSentence?.DetectedLanguage?.Confidence}.");
    Console.WriteLine($"The detected sentence boundaries: '{string.Join(",", brokenSentence?.SentencesLengths)}'.");
}
catch (RequestFailedException exception)
{
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
}

有关使用 break sentence 端点的示例，请参阅更多示例 这里。

请参阅服务文档以了解 句子分割 的概念讨论。

字典查询

返回目标语言中与源术语等效的单词。

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

    Response<IReadOnlyList<DictionaryLookupItem>> response = client.LookupDictionaryEntries(sourceLanguage, targetLanguage, inputText);
    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 = client.LookupDictionaryExamples(sourceLanguage, targetLanguage, inputTextElements);
    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 端点的示例，请参阅更多示例 这里。

请参阅服务文档以了解 字典示例 的概念讨论。

故障排除

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

例如，如果您未提供目标翻译语言就提交翻译请求，将返回一个 400 错误，表示“请求错误”。

try
{
    var translation = client.Translate(Array.Empty<string>(), new[] { "This is a Test" });
}
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 存储库中提供了演示如何使用此客户端库的示例。为每个主要功能区域提供了示例，并且在每个区域中，都提供了同步和异步模式下的示例。

• 创建 TextTranslationClient
• 语言
• 翻译
• 转写
• 句子分割
• 字典查询
• 字典示例

贡献

有关构建、测试和为此库做出贡献的详细信息，请参阅 CONTRIBUTING.md。

此项目欢迎贡献和建议。大多数贡献都需要您同意贡献者许可协议 (CLA)，声明您有权，并且实际上已授予我们使用您的贡献的权利。有关详细信息，请访问 cla.microsoft.com。

当您提交拉取请求时，CLA-bot 会自动确定您是否需要提供 CLA，并根据需要适当标记 PR（例如，标记、注释）。只需遵循机器人提供的说明即可。您只需在整个 clu 使用我们的 CLA 的情况下做一次。

本项目采用了微软开源行为准则。更多相关信息请参阅行为准则常见问题解答或向[email protected]发送任何额外的问题或评论。