使用 翻譯工具 API 的文字翻譯

Microsoft 翻譯工具 API 可用來透過 REST API 翻譯語音和文字。 本文說明如何使用 Microsoft 翻譯工具 文字 API，在應用程式中將文字從一種語言翻譯成另一Xamarin.Forms種語言。

概觀

翻譯工具 API 有兩個元件：

• 文字翻譯 REST API，用來將文字從某個語言翻譯成其他語言的文字。 API 會自動偵測在翻譯之前傳送的文字語言。
• 語音翻譯 REST API，用來將語音從某個語言轉譯成其他語言的文字。 API 也會整合文字到語音轉換功能，以將翻譯的文字說回。

本文著重於使用 翻譯工具 文字 API，將文字從一種語言翻譯成另一種語言。

注意

如果您沒有 Azure 訂用帳戶，請在開始前建立免費帳戶。

必須取得 API 金鑰，才能使用 翻譯工具 文字 API。 這可以在如何註冊 Microsoft 翻譯工具 文字 API 取得。

如需 Microsoft 翻譯工具 文字 API 的詳細資訊，請參閱 翻譯工具 文字 API 檔。

驗證

對 翻譯工具 文字 API 提出的每個要求都需要 JSON Web 令牌 （JWT） 存取令牌，此令牌可從 的https://api.cognitive.microsoft.com/sts/v1.0/issueToken認知服務令牌服務取得。 對令牌服務發出 POST 要求，即可取得令牌，並 Ocp-Apim-Subscription-Key 指定包含 API 金鑰作為其值的標頭。

下列程式代碼範例示範如何向令牌服務要求存取令牌：

public AuthenticationService(string apiKey)
{
    subscriptionKey = apiKey;
    httpClient = new HttpClient();
    httpClient.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", apiKey);
}
...
async Task<string> FetchTokenAsync(string fetchUri)
{
    UriBuilder uriBuilder = new UriBuilder(fetchUri);
    uriBuilder.Path += "/issueToken";
    var result = await httpClient.PostAsync(uriBuilder.Uri.AbsoluteUri, null);
    return await result.Content.ReadAsStringAsync();
}

傳回的存取令牌是Base64文字，其到期時間為10分鐘。 因此，範例應用程式會每隔 9 分鐘更新存取令牌一次。

存取令牌必須在每個 翻譯工具 文字 API 呼叫中指定為Authorization前面加上字串Bearer的標頭，如下列程式代碼範例所示：

httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", bearerToken);

如需認知服務令牌服務的詳細資訊，請參閱 驗證。

執行文字翻譯

在 對 API https://api.microsofttranslator.com/v2/http.svc/translate提出 GET 要求translate，即可達成文字翻譯。 在範例應用程式中， TranslateTextAsync 方法會叫用文字翻譯程式：

public async Task<string> TranslateTextAsync(string text)
{
  ...
  string requestUri = GenerateRequestUri(Constants.TextTranslatorEndpoint, text, "en", "de");
  string accessToken = authenticationService.GetAccessToken();
  var response = await SendRequestAsync(requestUri, accessToken);
  var xml = XDocument.Parse(response);
  return xml.Root.Value;
}

方法 TranslateTextAsync 會產生要求 URI，並從令牌服務擷取存取令牌。 文字翻譯要求接著會傳送至 translate API，以傳回包含結果的 XML 回應。 XML 回應會剖析，並將轉譯結果傳回給呼叫方法以供顯示。

如需文字翻譯 REST API 的詳細資訊，請參閱 翻譯工具 文字 API。

設定文字翻譯

您可以藉由指定 HTTP 查詢參數來設定文字轉譯程式：

string GenerateRequestUri(string endpoint, string text, string to)
{
  string requestUri = endpoint;
  requestUri += string.Format("?text={0}", Uri.EscapeUriString(text));
  requestUri += string.Format("&to={0}", to);
  return requestUri;
}

這個方法會設定要翻譯的文字，以及要翻譯文字的語言。 如需 Microsoft 翻譯工具 所支援語言的清單，請參閱 Microsoft 翻譯工具 文字 API 中支援的語言。

注意

如果應用程式必須知道文字所使用的語言， Detect 可以呼叫 API 來偵測文字字串的語言。

傳送要求

方法 SendRequestAsync 會向文字翻譯 REST API 提出 GET 要求，並傳回回應：

async Task<string> SendRequestAsync(string url, string bearerToken)
{
    if (httpClient == null)
    {
        httpClient = new HttpClient();
    }
    httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", bearerToken);

    var response = await httpClient.GetAsync(url);
    return await response.Content.ReadAsStringAsync();
}

這個方法會藉由將存取令牌新增至 Authorization 標頭來建置 GET 要求，前面加上字串 Bearer。 GET 要求接著會傳送至 translate API，並要求 URL 指定要翻譯的文字，以及要翻譯文字的語言。 接著會讀取回應並傳回至呼叫方法。

translate API 會在回應中傳送 HTTP 狀態代碼 200 （確定），前提是要求有效，這表示要求成功，且要求的信息在回應中。 如需可能的錯誤回應清單，請參閱 GET Translate 的回應消息。

處理回應

API 回應會以 XML 格式傳回。 下列 XML 數據顯示典型的成功回應訊息：

<string xmlns="http://schemas.microsoft.com/2003/10/Serialization/">Morgen kaufen gehen ein</string>

在範例應用程式中，XML 回應會剖析成 XDocument 實例，並將 XML 根值傳回給呼叫方法，以顯示，如下列螢幕快照所示：

摘要

本文說明如何使用 Microsoft 翻譯工具 文字 API，將某個語言的Xamarin.Forms文字翻譯成應用程式中另一種語言的文字。 除了翻譯文字之外，Microsoft 翻譯工具 API 也可以將語音從某個語言轉譯成另一種語言的文字。

相關連結

• 翻譯工具 文字 API 檔
• 取用 RESTful Web 服務
• 翻譯工具 文字 API