Azure Document Translation client library for JavaScript - version 1.0.0

文件翻譯是 Azure AI 翻譯工具 服務中的一項雲端機器翻譯功能。 你可以在保留原始文件結構與資料格式的同時，將多份複雜文件翻譯到所有支援的語言和方言之間。 文件翻譯 API 支援兩種翻譯流程：

非同步批次翻譯支援處理多個文件與大型檔案。 批次翻譯流程需要具有來源和翻譯文件儲存體容器的 Azure Blob 儲存體帳戶。

同步單一檔案轉換支援單一檔案轉換的處理。 檔案轉譯程式不需要 Azure Blob 記憶體帳戶。 最終回應包含已翻譯的文件，並會直接傳回給呼叫用戶端。

文件轉換功能支援以下操作：

  • 同步文件翻譯：用於同步翻譯單一文件。 此方法不需要 Azure Blob 儲存體帳戶。
  • 啟動批次轉換：用於執行非同步批次轉換請求。 此方法需要具有來源和翻譯檔的記憶體容器的 Azure Blob 記憶體帳戶。
  • 取得所有翻譯任務的狀態：用於請求使用者（與該資源相關）提交的所有翻譯作業清單及狀態。
  • 取得特定翻譯工作的狀態：用於請求特定翻譯工作的狀態。 回應包含整體作業狀態，以及正在轉譯為該作業一部分的文件狀態。
  • 取得所有文件狀態：用於請求翻譯工作中所有文件的狀態。
  • 取得特定文件的狀態：回傳工作中特定文件的狀態，該文件依請求中 id 與 documentId 查詢參數所示。
  • 取消翻譯：取消目前正在處理或排隊（待處理）的翻譯工作。 如果作業已完成、失敗或仍取消，則不會取消。
  • 取得支援格式：回傳文件翻譯功能支援的文件或詞彙表格式清單。

主要連結：

入門指南

目前支援的環境

如需詳細資訊，請參閱我們的支援原則。

先決條件

安裝 @azure/ai-translation-document 套件

安裝 Azure 文件轉換客戶端函式庫 JavaScript 版本：npm

npm install @azure/ai-translation-document

Set Up Azure Blob 儲存體 account

批次轉換需要一個 Azure Blob 儲存體 帳號。 關於建立 Azure Blob 儲存體 帳號的更多資訊，請參見這裡。 關於建立來源檔案和目標檔案容器，請參考 這裡。 請務必授權你的翻譯資源儲存存取權，更多資訊 請見此處。

當儲存帳號關閉「允許儲存帳號金鑰存取」，轉換器資源啟用管理身份，並在儲存帳號上被分配為「Storage Blob Data Contributor」角色時，你可以直接使用容器 URL，且不需要產生 SAS URI。

驗證客戶端

此函式庫暴露兩個客戶端：

  • DocumentTranslationClient 用於批次翻譯及翻譯狀態操作。
  • SingleDocumentTranslationClient 用於同步單文件翻譯。

兩個用戶端都可以使用 Microsoft Entra 憑證或 API 金鑰進行驗證。

使用 Microsoft Entra 憑證

你可以用 @azure/identity 函式庫的憑證來驗證 Microsoft Entra ID。 若要使用如下所示的 DefaultAzureCredential 提供者，或 Azure SDK 所提供的其他認證提供者，請安裝 @azure/identity 套件：

npm install @azure/identity

你還需要註冊一個新的 Microsoft Entra 應用程式，並透過指派適當的角色給你的服務主體來授權翻譯器資源。

利用類 Node.js 和 Node 的環境，你可以用這個 DefaultAzureCredential 類別來驗證客戶端：

import { DocumentTranslationClient } from "@azure/ai-translation-document";
import { DefaultAzureCredential } from "@azure/identity";

const endpoint = "https://<translator-instance>.cognitiveservices.azure.com";
const client = new DocumentTranslationClient(endpoint, new DefaultAzureCredential());

對於瀏覽器環境，請使用套件中的 @azure/identity 來InteractiveBrowserCredential驗證：

import { InteractiveBrowserCredential } from "@azure/identity";
import { DocumentTranslationClient } from "@azure/ai-translation-document";

const credential = new InteractiveBrowserCredential({
  tenantId: "<YOUR_TENANT_ID>",
  clientId: "<YOUR_CLIENT_ID>",
});
const client = new DocumentTranslationClient("<endpoint>", credential);

使用 API 金鑰

你也可以用 KeyCredential資源的 API 金鑰進行驗證：

import { KeyCredential } from "@azure/core-auth";
import { DocumentTranslationClient } from "@azure/ai-translation-document";

const endpoint = "https://<translator-instance>.cognitiveservices.azure.com";
const credential: KeyCredential = { key: "YOUR_SUBSCRIPTION_KEY" };
const client = new DocumentTranslationClient(endpoint, credential);

JavaScript 套件組合

若要在瀏覽器中使用此用戶端連結庫，您必須先使用配套程式。 如需如何執行這項作的詳細資訊，請參閱我們的 組合檔。

關鍵概念

DocumentTranslationClient

DocumentTranslationClient 是非同步批次翻譯以及查詢翻譯與文件狀態的介面。 批次翻譯需要一個 Azure Blob 儲存體 帳號，裡面有容器存放原始文件和翻譯文件。

SingleDocumentTranslationClient

SingleDocumentTranslationClient 是同步單一文件轉換的介面。 它不需要 Azure Blob 儲存體 帳號;翻譯後的文件會直接回傳在回應中。

範例

以下章節提供多個涵蓋此用戶端函式庫主要功能的程式碼片段。

同步文件翻譯

用來同步翻譯單一文件。 此方法不需要 Azure Blob 儲存體帳戶。

import { SingleDocumentTranslationClient } from "@azure/ai-translation-document";
import { DefaultAzureCredential } from "@azure/identity";
import { writeFile } from "node:fs/promises";

const endpoint = "https://<translator-instance>.cognitiveservices.azure.com";
const client = new SingleDocumentTranslationClient(endpoint, new DefaultAzureCredential());
const response = await client.translate("hi", {
  document: {
    contents: "This is a test.",
    contentType: "text/html",
    filename: "test-input.txt",
  },
});
if (response.readableStreamBody) {
  await writeFile("test-output.txt", response.readableStreamBody);
}

批次文件翻譯

用於執行非同步批次轉換請求。 此方法需要具有來源和翻譯檔的記憶體容器的 Azure Blob 記憶體帳戶。 提供來源與目標容器 URL（如有需要，需使用 SAS 令牌），並輪詢直到操作完成。

import { DocumentTranslationClient } from "@azure/ai-translation-document";
import { DefaultAzureCredential } from "@azure/identity";

const endpoint = "https://<translator-instance>.cognitiveservices.azure.com";
const client = new DocumentTranslationClient(endpoint, new DefaultAzureCredential());
const poller = client.startTranslation({
  inputs: [
    {
      source: { sourceUrl: "<source container SAS URL>" },
      targets: [{ targetUrl: "<target container SAS URL>", language: "fr" }],
    },
  ],
});
const result = await poller.pollUntilDone();
console.log(`Translation status: ${result.status}`);

取得支援格式

回傳文件轉換功能所支援的文件格式清單。

import { DocumentTranslationClient } from "@azure/ai-translation-document";
import { DefaultAzureCredential } from "@azure/identity";

const endpoint = "https://<translator-instance>.cognitiveservices.azure.com";
const client = new DocumentTranslationClient(endpoint, new DefaultAzureCredential());
const formats = await client.getSupportedFormats("Document");
for (const format of formats.value) {
  console.log(format.format);
}

Troubleshooting

森林伐木業

啟用記錄可能有助於找出有關失敗的實用資訊。 若要查看 HTTP 要求和回應的記錄，請將 AZURE_LOG_LEVEL 環境變數設定為 info。 或者，您可以在運行時間啟用記錄，方法是在 setLogLevel中呼叫 @azure/logger：

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

如需如何啟用記錄的詳細指示，請參閱@azure/記錄器套件檔。

Contributing

如果您想要參與此連結庫，請閱讀 參與指南，以深入瞭解如何建置和測試程序代碼。

  • Last updated on