使用 Translator API 進行文字翻譯

Translator API 是一個實驗性的網頁 API，允許你利用 Microsoft Edge 內建的專家模型，從你網站或瀏覽器擴充功能中的 JavaScript 程式碼，翻譯不同語言之間的文字。

關於翻譯器 API 的入門資訊，請參見：

• 翻譯器與語言偵測器 API
• 翻譯器與語言偵測器 API 的說明

詳細內容：

• 翻譯器 API 的可用性
• Translator API 的優點
• Translator API 的替代方案
• 免責聲明
• 模型可用性
• 啟用翻譯器 API
• 請參考工作範例
• 使用翻譯器 API
• 檢查 Translator API 是否啟用
• 請確認該型號是否能 (可用性 () )
• 建立一個新會話 (建立 () )
• 監控模型下載進度 (監控：)
• 執行翻譯器 API (翻譯 () )
  • 等文字翻譯後 (翻譯 () )
  • 顯示產生的代幣 (翻譯串流 () )
• 停止翻譯 (abortController.signal)
• 摧毀一場會話 (摧毀 () )
  • 透過呼叫「摧毀 () 來摧毀一場會議
  • 使用 AbortController 銷毀會話
• 傳送意見反應
• 另請參閱

翻譯器 API 的可用性

Translator API 從 143.0.3636.0 版本起，已在 Microsoft Edge Canary 或 Dev 頻道以開發者預覽版形式提供。 若要下載 Microsoft Edge (Beta、開發版或 Canary) 的預覽頻道，請前往 「成為 Microsoft Edge Insider」。

Translator API 的優點

Translator API 使用專家模型進行機器翻譯，該模型運行於同一裝置上，該裝置同時使用該模型的輸入與輸出， (即本地) 。 此方法相較於雲端解決方案有以下優點：

• 降低成本： 使用雲端翻譯服務是沒有費用的。

• 網路獨立性： 除了初始模型下載外，使用此 API 翻譯文字時沒有網路延遲，且裝置離線時也能使用。

• 提升隱私： 輸入到模型的資料不會離開裝置，也不會被收集來訓練 AI 模型。

指定語言對的翻譯模型會在 Microsoft Edge 首次使用 API 時下載，隨後在瀏覽器中所有網站共享。 這些模型透過簡單的網頁 API 存取，無需第三方框架知識，也不需要人工智慧 (AI) 或機器學習 (機器學習) 專業知識。

Translator API 的替代方案

你可以向具備更先進功能（包括神經翻譯）的雲端翻譯服務發送網路請求;請參閱 Azure AI 翻譯器文件。

作為裝置端替代方案，Prompt API 提供更多自訂的多語言提示場景，並內建於 Microsoft Edge 的小型語言模型;請參見 Prompt，一個內建 Prompt API 的語言模型。

免責聲明

與其他機器翻譯模型一樣，Microsft Edge 中的專家模型可能產生不公平、不可靠或冒犯性的翻譯。 欲了解更多關於這些機器翻譯模型的限制，請參閱Azure AI 翻譯器透明度說明。

模型可用性

網站首次呼叫內建 AI API 時，必須先下載模型。 你可以在建立新的翻譯器 API 會話時，使用監控選項來監控模型下載過程;請參見下方 「監控模型下載進度」 (monitor：) 。

啟用翻譯器 API

要在 Microsoft Edge 中使用 Translator API，請設定兩個旗標，如下：

1. 在 Microsoft Edge 中，請前往 edge://version，並確保你使用的是 Microsoft Edge 的 143.0.3636.0 或更新版本，例如 Microsoft Edge 的 Canary 或 Dev 預覽頻道。

   若要下載 Microsoft Edge (Beta、開發版或 Canary) 的預覽頻道，請前往 「成為 Microsoft Edge Insider」。

2. 在該版本的 Microsoft Edge 中，開啟一個新分頁或視窗，然後前往 edge://flags。

3. 在頂端 的搜尋旗標 文字框中，開始輸入 翻譯 API：

   

   以下旗幟列出：

   • 實驗性翻譯 API - 啟用裝置上的語言翻譯 API。 請參閱 說明說明，了解翻譯器與語言偵測器 API。

     此條目顯示 #edge-translation-api，該 表示 edge://flags/#edge-translation-api。

   • 翻譯 API 按句子串流 - 啟用後，翻譯 API 會逐句分割並串流每句翻譯完成的句子，提供更佳的長文字翻譯反應速度。

     此條目顯示 #edge-translation-api-streaming-by-sentence，該 表示 edge://flags/#edge-translation-api-streaming-by-sentence。

4. 在 實驗性翻譯 API 中，選擇 啟用。

5. 在 Translation API 按句子分割串流時，選擇 啟用。

   右下角 顯示一個重新啟動 按鈕。

6. 點擊 重新啟動 按鈕。

請參考工作範例

想查看翻譯器 API 的運作，並檢視使用這些 API 的現有程式碼：

1. 啟用上述的翻譯器 API。

2. 在 Microsoft Edge Canary 或 Dev 中，進入 Translator API 遊樂場 ，開啟新視窗或分頁。

3. 在最上方的資訊橫幅中，請查看狀態：最初顯示： 裝置上 API 與型號可下載。指定語言對的模型會在首次使用 API 時下載。

4. 在「 文字翻譯 」文字框中輸入文字以翻譯，並可選擇更改 來源語言 與 目標語言 值。

5. 點擊 翻譯 按鈕。

   如果指定語言對的模型之前未被下載，下載即開始。

   

   如果模型下載無法啟動，請重新啟動 Microsoft Edge 再試一次。

   模型下載完成後，會開始將文本從來源語言翻譯成目標語言。

   輸出會在頁面的回應區產生：

   

6. 要停止產生回應，隨時點擊 停止 按鈕。

另請參閱:

• /built-in-ai/ - 內建 AI 遊樂場示範的原始碼與說明文件。

使用翻譯器 API

接下來的章節將介紹如何使用 Translator API。

檢查 Translator API 是否啟用

在使用翻譯器 API 前，先測試該物件是否存在 Translator ，確認該 API 已啟用：

if (!Translator) {
  // The Translator API is not available.
} else {
  // The Translator API is available.
}

請確認該模型是否可用於 (availability())

翻譯器 API 有以下需求：

• 必須支援從指定原始語言轉換到指定目標語言。
• 語言對的翻譯模型與模型執行時必須已被 Microsoft Edge 下載。

要檢查該 API 是否可用，請呼叫 availability()：

const availability = await Translator.availability({
  sourceLanguage: "en",
  targetLanguage: "es"
});

if (availability == "unavailable") {
  // The model is not available.
}

if (availability == "downloadable" || availability == "downloading") {
  // The model can be used, but it needs to be downloaded first.
}

if (availability == "available") {
  // The model is available and can be used.
}

對於 sourceLanguagetargetLanguage和 ，請在 「識別語言標籤」中以字串形式使用語言代碼。

建立一個新的 (create())

建立會話會指示瀏覽器將語言模型載入記憶體，以便使用。 在翻譯文字之前，請先用此 create() 方法建立一個新會話，並指定來源語言與目標語言：

// Create a Translator session.
const session = await Translator.create({
  sourceLanguage: "en",
  targetLanguage: "es"
});

你可以透過 monitor 以下選項監控模型下載過程。

監控模型下載進度 (monitor:)

你可以透過這個 monitor 選項追蹤模型下載進度。 當模型尚未完全下載到將使用的裝置時，這很有用，可以提醒網站用戶應該等待。

// Create a Translator session with the monitor option to monitor the model
// download.
const session = await Translator.create({
  sourceLanguage: "en",
  targetLanguage: "es",
  monitor: m => {
    // Use the monitor object argument to add an listener for the 
    // downloadprogress event.
    m.addEventListener("downloadprogress", event => {
      // The event is an object with the loaded and total properties.
      if (event.loaded == event.total) {
        // The model is fully downloaded.
      } else {
        // The model is still downloading.
        const percentageComplete = (event.loaded / event.total) * 100;
      }
    });
  }
});

執行翻譯器 API (translate())

建立模型會話後，你可以翻譯文字。 翻譯 API 提供兩種文字翻譯方法：

• translatorSession.translate() 回傳一個承諾，該承諾在文本翻譯後才解決。
• translatorSession.translateStreaming() 會立即回傳一個串流物件，你可以用它逐個標記顯示翻譯後的文字，當它正在產生時。

詳情如下。

等文本翻譯 (translate())

翻譯文字。 回傳一個承諾，該承諾在文本翻譯後才解決。

若要等待文字完全翻譯後再繼續執行程式碼，請使用 translate() 非同步方法。 此方法回傳一個承諾，該承諾會在 API 產生文字完成後解決：

// Create a Translator session.
const translatorSession = await Translator.create({
  sourceLanguage: "en",
  targetLanguage: "es"
});

// Translate the text and wait for the translation to be done.
const translatedText = await translatorSession.translate(sourceText);

// Use the translation.
console.log(translatedText);

在產生的代幣 (translateStreaming() 顯示)

翻譯文字。 會立即回傳一個串流物件，你可以用它逐個標記顯示翻譯後的文字，當它正在產生時。

要在代幣生成時顯示，請使用此串流方式。 該方法會 translateStreaming() 立即回傳串流物件。 使用回傳的串流物件顯示正在產生的回應標記：

// Create a Translator session.
const translatorSession = await Translator.create({
  sourceLanguage: "en",
  targetLanguage: "es"
});

// Ask the model to translate text.
const stream = translatorSession.translateStreaming(sourceText);

// Use the stream object to display tokens that are generated by the model, as
// they are being generated.
for await (const chunk of stream) {
  console.log(chunk);
}

停止翻譯文字 (abortController.signal)

若要在上述方法回傳的承諾或串流尚未解決或結束前停止翻譯文字，請使用以下 AbortController 訊號：

// Create a Translator session.
const translatorSession = await Translator.create({
  sourceLanguage: "en",
  targetLanguage: "es"
});

// Create an AbortController object.
const abortController = new AbortController();

// Use the model session to translate some text and pass the AbortController
// object by using the signal option.
const stream = translatorSession.translateStreaming(sourceText, {
    signal: abortController.signal
});

// Later, perhaps when the user presses a "Stop" button, call the abort()
// method on the AbortController object to stop translating text.
abortController.abort();

摧毀一場 (destroy())

翻譯完文字後，銷毀該工作階段，讓瀏覽器知道你不再需要語言模型，這樣模型就能從記憶體中卸載。

你可以用兩種不同的方式摧毀一場遊戲：

• 透過使用這個 destroy() 方法。
• 透過使用 AbortController.

詳情如下。

透過呼叫銷毀會話 destroy()

要用 session 呼叫來摧毀一個 session destroy()Translator ：

const session = await Translator.create({
  sourceLanguage: "en",
  targetLanguage: "es"
});

// Later, destroy the session by using the destroy method.
session.destroy();

透過以下方式銷毀一個會話 AbortController

要透過建立 AbortController 物件來銷毀會話，請建立一個 Translator 會話，然後呼叫 abort()：

// Create an AbortController object.
const controller = new AbortController();

// Create a Translator session and pass the 
// AbortController object by using the signal option.
const session = await Translator.create({
  sourceLanguage: "en",
  targetLanguage: "es",
  signal: controller.signal
});

// Later, perhaps when the user interacts with the UI, destroy the session by
// calling the abort() function of the AbortController object.
controller.abort();

傳送意見反應

我們非常有興趣了解您打算使用翻譯器 API 的各種情境、API 或專家模型的問題，以及其他針對特定任務的內建 API 是否有用。

若想對您的情境及想達成的任務提供回饋，請在 翻譯器 API 回饋問題中留言。

如果你發現使用 API 時有任何問題，請向倉庫回報。

你也可以在 W3C Web Machine Learning 工作小組的資料庫中，參與 Translator API 設計的討論。

另請參閱

• 用 Prompt API 來提示內建語言模型
• 使用 Writing Assistance API 摘要、撰寫及重寫文字

取得 Microsoft Edge：

• 成為 Microsoft Edge Insider - 下載Microsoft Edge (Beta、開發版或 Canary) 預覽頻道。

GitHub：

• Web機器學習/翻譯API 倉庫。
  • 翻譯器與語言偵測器 API 的說明
• 翻譯器與語言偵測器 API
  • 識別語言 標籤 - 用於 sourceLanguagetargetLanguage和 。

Azure docs：

• Azure AI Translator documentation
• Azure AI 翻譯器的限制透明度說明。

Demos repo：

• 翻譯器 API 遊樂場
• /built-in-ai/ - 內建 AI 遊樂場示範的原始碼與說明文件。