快速入门：Translator 入门

  • 项目

本快速入门介绍如何通过 REST 使用 Translator 服务。 你将从基本示例开始，逐步完成在开发过程中常用的一些核心配置选项，其中包括：

先决条件

  • Azure 订阅 - 创建试用订阅

  • 有了 Azure 订阅后，请在 Azure 门户中创建 Translator 资源，以获取密钥和终结点。 部署后，选择”转到资源”。

    • 你需要从资源获取密钥和终结点，以便将应用程序连接到 Translator 服务。 你稍后会在快速入门中将密钥和终结点粘贴到下方的代码中。 可以在 Azure 门户的“密钥和终结点”页面上找到这些值：

      Screenshot: Azure portal keys and endpoint page.

  • 可以使用免费定价层 (F0) 试用该服务，然后再升级到付费层进行生产。

平台设置

  • 创建一个新项目：dotnet new console -o your_project_name
  • 将 Program.cs 替换为下面所示的 C# 代码。
  • 在 Program.cs 中设置密钥和终结点值。
  • 使用 .NET CLI 添加 Newtonsoft.Json。
  • 从项目目录中运行程序：dotnet run

标头

通过 REST 调用 Translator 服务时，需要确保每个请求中都包含以下标头。 别担心，我们会在以下部分的示例代码中包括标头。

标头 说明
身份验证标头 必需的请求标头。
Ocp-Apim-Subscription-Key

使用认知服务资源时所需的请求头。 如果使用翻译器资源，则此为可选。
Ocp-Apim-Subscription-Region

请参阅用于身份验证的可用选项。
Content-Type 必需的请求标头。
指定有效负载的内容类型。
接受的值为：application/json; charset=UTF-8。
Content-Length 必需的请求标头。
请求正文的长度。
X-ClientTraceId 可选。
客户端生成的 GUID，用于唯一标识请求。 如果在查询字符串中使用名为 ClientTraceId 的查询参数包括了跟踪 ID，则可以省略此标头。

密钥和终结点

为简单起见，此页面上的示例使用了硬编码的密钥和终结点。 请记住完成后将密钥从代码中删除，永远不要公开发布该密钥。 对于生产环境，请考虑使用安全的方法来存储和访问凭据。 有关详细信息，请参阅认知服务安全性文章。

翻译文本

Translator 服务的核心操作是翻译文本。 在本部分，你将生成一个请求，该请求采用单个源 (from) 并提供两个输出 (to)。 然后，我们将查看一些参数，这些参数可用于调整请求和响应。

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json; // Install Newtonsoft.Json with NuGet

class Program
{
    private static readonly string key = "YOUR-KEY";
    private static readonly string endpoint = "https://api.translator.azure.cn/";

    // Add your location, also known as region. The default is global.
    // This is required if using a Cognitive Services resource.
    private static readonly string location = "YOUR_RESOURCE_LOCATION";
    
    static async Task Main(string[] args)
    {
        // Input and output languages are defined as parameters.
        string route = "/translate?api-version=3.0&from=en&to=de&to=it";
        string textToTranslate = "Hello, world!";
        object[] body = new object[] { new { Text = textToTranslate } };
        var requestBody = JsonConvert.SerializeObject(body);
    
        using (var client = new HttpClient())
        using (var request = new HttpRequestMessage())
        {
            // Build the request.
            request.Method = HttpMethod.Post;
            request.RequestUri = new Uri(endpoint + route);
            request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json");
            request.Headers.Add("Ocp-Apim-Subscription-Key", key);
            request.Headers.Add("Ocp-Apim-Subscription-Region", location);
    
            // Send the request and get response.
            HttpResponseMessage response = await client.SendAsync(request).ConfigureAwait(false);
            // Read response as a string.
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}

成功调用后，应会看到以下响应：

[
    {
        "translations": [
            {
                "text": "Hallo Welt!",
                "to": "de"
            },
            {
                "text": "Salve, mondo!",
                "to": "it"
            }
        ]
    }
]

检测语言

如果你知道你需要翻译，但不知道将发送到 Translator 服务的文本的语言，则可以使用语言检测操作。 可以通过多种方式来识别源文本语言。 本部分介绍如何通过 translate 终结点和 detect 终结点来使用语言检测。

在翻译过程中检测源语言

如果未在翻译请求中包含 from 参数，则 Translator 服务会尝试检测源文本的语言。 在响应中，你将获得检测到的语言 (language) 和置信度分数 (score)。 score 越接近 1.0，意味着检测结果正确的置信度越高。

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json; // Install Newtonsoft.Json with NuGet

class Program
{
    private static readonly string key = "YOUR-KEY";
    private static readonly string endpoint = "https://api.translator.azure.cn/";

    // Add your location, also known as region. The default is global.
    // This is required if using a Cognitive Services resource.
    private static readonly string location = "YOUR_RESOURCE_LOCATION";
    
    static async Task Main(string[] args)
    {
        // Output languages are defined as parameters, input language detected.
        string route = "/translate?api-version=3.0&to=de&to=it";
        string textToTranslate = "Hello, world!";
        object[] body = new object[] { new { Text = textToTranslate } };
        var requestBody = JsonConvert.SerializeObject(body);
    
        using (var client = new HttpClient())
        using (var request = new HttpRequestMessage())
        {
            // Build the request.
            request.Method = HttpMethod.Post;
            request.RequestUri = new Uri(endpoint + route);
            request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json");
            request.Headers.Add("Ocp-Apim-Subscription-Key", key);
            request.Headers.Add("Ocp-Apim-Subscription-Region", location);
    
            // Send the request and get response.
            HttpResponseMessage response = await client.SendAsync(request).ConfigureAwait(false);
            // Read response as a string.
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}

成功调用后，应会看到以下响应：

[
    {
        "detectedLanguage": {
            "language": "en",
            "score": 1.0
        },
        "translations": [
            {
                "text": "Hallo Welt!",
                "to": "de"
            },
            {
                "text": "Salve, mondo!",
                "to": "it"
            }
        ]
    }
]

在不进行翻译的情况下检测源语言

可以使用 Translator 服务来检测源文本的语言，而不进行翻译。 为此，需要使用 /detect 终结点。

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json; // Install Newtonsoft.Json with NuGet

class Program
{
    private static readonly string key = "YOUR-KEY";
    private static readonly string endpoint = "https://api.translator.azure.cn/";

    // Add your location, also known as region. The default is global.
    // This is required if using a Cognitive Services resource.
    private static readonly string location = "YOUR_RESOURCE_LOCATION";    
    
    static async Task Main(string[] args)
    {
        // Just detect language
        string route = "/detect?api-version=3.0";
        string textToLangDetect = "Ich würde wirklich gern Ihr Auto um den Block fahren ein paar Mal.";
        object[] body = new object[] { new { Text = textToLangDetect } };
        var requestBody = JsonConvert.SerializeObject(body);
    
        using (var client = new HttpClient())
        using (var request = new HttpRequestMessage())
        {
            // Build the request.
            request.Method = HttpMethod.Post;
            request.RequestUri = new Uri(endpoint + route);
            request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json");
            request.Headers.Add("Ocp-Apim-Subscription-Key", key);
            request.Headers.Add("Ocp-Apim-Subscription-Region", location);
    
            // Send the request and get response.
            HttpResponseMessage response = await client.SendAsync(request).ConfigureAwait(false);
            // Read response as a string.
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}

使用 /detect 终结点时，响应会包括替代检测，并会通知你是否所有检测到的语言都支持翻译和音译。 成功调用后，应会看到以下响应：

[

    {

        "language": "de",

        "score": 1.0,

        "isTranslationSupported": true,

        "isTransliterationSupported": false

    }

]

直译文本

音译是指基于拼音相似性将脚本（表音符号系统）中的单词或短语从一种语言转换为另一种语言的过程。 例如，可以使用音译将“สวัสดี”(thai) 转换为“sawatdi”(latn)。 可以通过多种方式来执行音译。 本部分介绍如何通过 translate 终结点和 transliterate 终结点来使用语言检测。

在翻译过程中进行音译

如果要翻译成一种使用不同于源的字母表（或音素）的语言，则可能需要使用音译。 在此示例中，我们将“Hello”从英语翻译为泰语。 除了获得泰语翻译外，还可以使用拉丁字母获得翻译的短语的音译。

若要从 translate 终结点获取音译，请使用 toScript 参数。

注意

有关可用语言和音译选项的完整列表，请参阅语言支持。

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json; // Install Newtonsoft.Json with NuGet

class Program
{
    private static readonly string key = "YOUR-KEY";
    private static readonly string endpoint = "https://api.translator.azure.cn/";

    // Add your location, also known as region. The default is global.
    // This is required if using a Cognitive Services resource.
    private static readonly string location = "YOUR_RESOURCE_LOCATION";    
    
    static async Task Main(string[] args)
    {
        // Output language defined as parameter, with toScript set to latn
        string route = "/translate?api-version=3.0&to=th&toScript=latn";
        string textToTransliterate = "Hello";
        object[] body = new object[] { new { Text = textToTransliterate } };
        var requestBody = JsonConvert.SerializeObject(body);
    
        using (var client = new HttpClient())
        using (var request = new HttpRequestMessage())
        {
            // Build the request.
            request.Method = HttpMethod.Post;
            request.RequestUri = new Uri(endpoint + route);
            request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json");
            request.Headers.Add("Ocp-Apim-Subscription-Key", key);
            request.Headers.Add("Ocp-Apim-Subscription-Region", location);
    
            // Send the request and get response.
            HttpResponseMessage response = await client.SendAsync(request).ConfigureAwait(false);
            // Read response as a string.
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}

成功调用后，应会看到以下响应。 请记住，translate 终结点的响应包含检测到的源语言和一个置信度分数、使用输出语言的字母表的翻译，以及使用拉丁字母的音译。

[
    {
        "detectedLanguage": {
            "language": "en",
            "score": 1.0
        },
        "translations": [
            {
                "text": "สวัสดี",
                "to": "th",
                "transliteration": {
                    "script": "Latn",
                    "text": "sawatdi"
                }
            }
        ]
    }
]

在无翻译的情况下进行音译

你还可以使用 transliterate 终结点来获取音译。 使用音译终结点时，必须提供源语言 (language)、源脚本/字母表 (fromScript) 以及输出脚本/字母表 (toScript) 作为参数。 在此示例中，我们将获取 สวัสดี 的音译。

注意

有关可用语言和音译选项的完整列表，请参阅语言支持。

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json; // Install Newtonsoft.Json with NuGet

class Program
{
    private static readonly string key = "YOUR-KEY";
    private static readonly string endpoint = "https://api.translator.azure.cn/";

    // Add your location, also known as region. The default is global.
    // This is required if using a Cognitive Services resource.
    private static readonly string location = "YOUR_RESOURCE_LOCATION";   
    
    static async Task Main(string[] args)
    {
        // For a complete list of options, see API reference.
        // Input and output languages are defined as parameters.
        string route = "/translate?api-version=3.0&to=th&toScript=latn";
        string textToTransliterate = "Hello";
        object[] body = new object[] { new { Text = textToTransliterate } };
        var requestBody = JsonConvert.SerializeObject(body);
    
        using (var client = new HttpClient())
        using (var request = new HttpRequestMessage())
        {
            // Build the request.
            request.Method = HttpMethod.Post;
            request.RequestUri = new Uri(endpoint + route);
            request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json");
            request.Headers.Add("Ocp-Apim-Subscription-Key", key);
            request.Headers.Add("Ocp-Apim-Subscription-Region", location);
    
            // Send the request and get response.
            HttpResponseMessage response = await client.SendAsync(request).ConfigureAwait(false);
            // Read response as a string.
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}

成功调用后，应会看到以下响应。 与对 translate 终结点的调用不同，transliterate 只返回 script 和输出 text。

[
    {
        "script": "latn",
        "text": "sawatdi"
    }
]

获取句子长度

使用 Translator 服务，你可以获取一个句子或一系列句子的字符计数。 响应以数组的形式返回，包含检测到的每个句子的字符计数。 可以通过 translate 和 breaksentence 终结点获取句子长度。

在翻译过程中获取句子长度

可以使用 translate 终结点获取源文本和翻译输出的字符计数。 若要返回句子长度（srcSenLen 和 transSenLen），必须将 includeSentenceLength 参数设置为 True。

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json; // Install Newtonsoft.Json with NuGet

class Program
{
    private static readonly string key = "YOUR-KEY";
    private static readonly string endpoint = "https://api.translator.azure.cn/";

    // Add your location, also known as region. The default is global.
    // This is required if using a Cognitive Services resource.
    private static readonly string location = "YOUR_RESOURCE_LOCATION";   
    
    static async Task Main(string[] args)
    {
        // Include sentence length details.
        string route = "/translate?api-version=3.0&to=es&includeSentenceLength=true";
        string sentencesToCount = 
                "Can you tell me how to get to Penn Station? Oh, you aren't sure? That's fine.";
        object[] body = new object[] { new { Text = sentencesToCount } };
        var requestBody = JsonConvert.SerializeObject(body);
    
        using (var client = new HttpClient())
        using (var request = new HttpRequestMessage())
        {
            // Build the request.
            request.Method = HttpMethod.Post;
            request.RequestUri = new Uri(endpoint + route);
            request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json");
            request.Headers.Add("Ocp-Apim-Subscription-Key", key);
            request.Headers.Add("Ocp-Apim-Subscription-Region", location);
    
            // Send the request and get response.
            HttpResponseMessage response = await client.SendAsync(request).ConfigureAwait(false);
            // Read response as a string.
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}

成功调用后，应会看到以下响应。 除了检测到的源语言和翻译以外，还将为源 (srcSentLen) 和翻译 (transSentLen) 的每个检测到的句子获取字符计数。

[
    {
        "detectedLanguage": {
            "language": "en",
            "score": 1.0
        },
        "translations": [
            {
                "sentLen": {
                    "srcSentLen": [
                        44,
                        21,
                        12
                    ],
                    "transSentLen": [
                        48,
                        18,
                        10
                    ]
                },
                "text": "¿Puedes decirme cómo llegar a la estación Penn? ¿No estás seguro? Está bien.",
                "to": "es"
            }
        ]
    }
]

在不翻译的情况下获取句子长度

Translator 服务还允许使用 breaksentence 终结点请求句子长度，无需翻译。

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json; // Install Newtonsoft.Json with NuGet

class Program
{
    private static readonly string key = "YOUR-KEY";
    private static readonly string endpoint = "https://api.translator.azure.cn/";

    // Add your location, also known as region. The default is global.
    // This is required if using a Cognitive Services resource.
    private static readonly string location = "YOUR_RESOURCE_LOCATION";   
    
    static async Task Main(string[] args)
    {
        // Only include sentence length details.
        string route = "/breaksentence?api-version=3.0";
        string sentencesToCount = 
                "Can you tell me how to get to Penn Station? Oh, you aren't sure? That's fine.";
        object[] body = new object[] { new { Text = sentencesToCount } };
        var requestBody = JsonConvert.SerializeObject(body);
    
        using (var client = new HttpClient())
        using (var request = new HttpRequestMessage())
        {
            // Build the request.
            request.Method = HttpMethod.Post;
            request.RequestUri = new Uri(endpoint + route);
            request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json");
            request.Headers.Add("Ocp-Apim-Subscription-Key", key);
            request.Headers.Add("Ocp-Apim-Subscription-Region", location);
    
            // Send the request and get response.
            HttpResponseMessage response = await client.SendAsync(request).ConfigureAwait(false);
            // Read response as a string.
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}

成功调用后，应会看到以下响应。 与对 translate 终结点的调用不同，breaksentence 只返回名为 sentLen 的数组中源文本的字符计数。

[
    {
        "detectedLanguage": {
            "language": "en",
            "score": 1.0
        },
        "sentLen": [
            44,
            21,
            12
        ]
    }
]

字典查找（替代翻译）

使用终结点，可以获取字词或短语的替代翻译。 例如，将单词“shark”从 en 翻译为 es 时，此终结点同时返回“tiburón”和“escualo”。

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json; // Install Newtonsoft.Json with NuGet

class Program
{
    private static readonly string key = "YOUR-KEY";
    private static readonly string endpoint = "https://api.translator.azure.cn/";

    // Add your location, also known as region. The default is global.
    // This is required if using a Cognitive Services resource.
    private static readonly string location = "YOUR_RESOURCE_LOCATION"; 
    
    static async Task Main(string[] args)
    {
        // See many translation options
        string route = "/dictionary/lookup?api-version=3.0&from=en&to=es";
        string wordToTranslate = "shark";
        object[] body = new object[] { new { Text = wordToTranslate } };
        var requestBody = JsonConvert.SerializeObject(body);
    
        using (var client = new HttpClient())
        using (var request = new HttpRequestMessage())
        {
            // Build the request.
            request.Method = HttpMethod.Post;
            request.RequestUri = new Uri(endpoint + route);
            request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json");
            request.Headers.Add("Ocp-Apim-Subscription-Key", key);
            request.Headers.Add("Ocp-Apim-Subscription-Region", location);
    
            // Send the request and get response.
            HttpResponseMessage response = await client.SendAsync(request).ConfigureAwait(false);
            // Read response as a string.
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}

成功调用后，应会看到以下响应。 让我们将此分解一下，因为此 JSON 比本文中的一些其他示例更复杂。 translations 数组包含翻译列表。 此数组中的每个对象都包含置信度分数 (confidence)、为显示给最终用户而优化的文本 (displayTarget)、标准化文本 (normalizedText)、语音的部分 (posTag) 以及有关以前翻译的信息 (backTranslations)。 有关响应的详细信息，请参阅字典查找。

[
    {
        "displaySource": "shark",
        "normalizedSource": "shark",
        "translations": [
            {
                "backTranslations": [
                    {
                        "displayText": "shark",
                        "frequencyCount": 45,
                        "normalizedText": "shark",
                        "numExamples": 0
                    }
                ],
                "confidence": 0.8182,
                "displayTarget": "tiburón",
                "normalizedTarget": "tiburón",
                "posTag": "OTHER",
                "prefixWord": ""
            },
            {
                "backTranslations": [
                    {
                        "displayText": "shark",
                        "frequencyCount": 10,
                        "normalizedText": "shark",
                        "numExamples": 1
                    }
                ],
                "confidence": 0.1818,
                "displayTarget": "escualo",
                "normalizedTarget": "escualo",
                "posTag": "NOUN",
                "prefixWord": ""
            }
        ]
    }
]

字典示例（上下文中的翻译）

执行字典查找后，可以将源文本和翻译传递到 dictionary/examples 终结点，以获取在句子或短语的上下文中显示这两个字词的示例的列表。 在上一示例的基础上进行构建时，你需要将字典查找响应中的 normalizedText 和 normalizedTarget 分别用作 text 和 translation。 源语言 (from) 和输出目标 (to) 参数是必需的。

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json; // Install Newtonsoft.Json with NuGet

class Program
{
    private static readonly string key = "YOUR-KEY";
    private static readonly string endpoint = "https://api.translator.azure.cn/";

    // Add your location, also known as region. The default is global.
    // This is required if using a Cognitive Services resource.
    private static readonly string location = "YOUR_RESOURCE_LOCATION"; 
    
    static async Task Main(string[] args)
    {
        // See examples of terms in context
        string route = "/dictionary/examples?api-version=3.0&from=en&to=es";
        object[] body = new object[] { new { Text = "Shark",  Translation = "tiburón" } } ;
        var requestBody = JsonConvert.SerializeObject(body);
    
        using (var client = new HttpClient())
        using (var request = new HttpRequestMessage())
        {
            // Build the request.
            request.Method = HttpMethod.Post;
            request.RequestUri = new Uri(endpoint + route);
            request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json");
            request.Headers.Add("Ocp-Apim-Subscription-Key", key);
            request.Headers.Add("Ocp-Apim-Subscription-Region", location);
    
            // Send the request and get response.
            HttpResponseMessage response = await client.SendAsync(request).ConfigureAwait(false);
            // Read response as a string.
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}

成功调用后，应会看到以下响应。 有关响应的详细信息，请参阅字典查找

[
    {
        "examples": [
            {
                "sourcePrefix": "More than a match for any ",
                "sourceSuffix": ".",
                "sourceTerm": "shark",
                "targetPrefix": "Más que un fósforo para cualquier ",
                "targetSuffix": ".",
                "targetTerm": "tiburón"
            },
            {
                "sourcePrefix": "Same with the mega ",
                "sourceSuffix": ", of course.",
                "sourceTerm": "shark",
                "targetPrefix": "Y con el mega ",
                "targetSuffix": ", por supuesto.",
                "targetTerm": "tiburón"
            },
            {
                "sourcePrefix": "A ",
                "sourceSuffix": " ate it.",
                "sourceTerm": "shark",
                "targetPrefix": "Te la ha comido un ",
                "targetSuffix": ".",
                "targetTerm": "tiburón"
            }
        ],
        "normalizedSource": "shark",
        "normalizedTarget": "tiburón"
    }
]

疑难解答

常见的 HTTP 状态代码

HTTP 状态代码 说明 可能的原因
200 OK 请求已成功。
400 错误的请求 必需参数缺失、为空或为 null。 或者，传递给必需参数或可选参数的值无效。 常见问题是标头太长。
401 未授权 请求未经授权。 检查确保你的密钥或令牌有效并且在正确的区域中。 另请参阅身份验证。
429 请求过多 已经超过了订阅允许的配额或请求速率。
502 错误的网关 网络或服务器端问题。 也可能表示标头无效。

Java 用户

如果遇到连接问题，可能是因为你的 SSL 证书已过期。 若要解决此问题，请将 DigiCertGlobalRootG2.crt 安装到专用存储中。