你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Azure Document Translation client library for JavaScript - version 1.0.0

文档翻译是Azure AI 翻译服务中的一项基于云的机器翻译功能。 你可以在保留原始文档结构和数据格式的同时，翻译多个复杂的文档，跨越所有支持的语言和方言。 文档翻译 API 支持两个翻译过程：

异步批量翻译支持处理多个文档和大型文件。 批量翻译过程需要一个 Azure Blob 存储帐户，其中包含源文档和翻译文档的存储容器。

同步单文件转换支持单文件转换的处理。 文件转换过程不需要Azure Blob 存储帐户。 最终响应包含翻译后的文档，会直接返回给调用客户端。

文档翻译功能支持以下操作：

  • 同步文档翻译：用于同步翻译单一文档。 该方法不需要有 Azure Blob 存储帐户。
  • 启动批处理转换：用于执行异步批处理翻译请求。 该方法需要一个 Azure Blob 存储帐户，其中包含用于源文档和已翻译文档的存储容器。
  • 获取所有翻译作业的状态：用于请求用户提交的所有翻译作业列表和状态（与资源关联）。
  • 获取特定翻译项目的状态：用于请求特定翻译项目的状态。 响应包括整体作业状态和作为该作业一部分正在翻译的文档的状态。
  • 获取所有文档状态：用于请求翻译任务中所有文档的状态。
  • 获取特定文档的状态：返回任务中特定文档的状态，按照请求中 id 和 documentId 查询参数显示。
  • 取消翻译：取消当前正在处理或排队（待处理）的翻译作业。 如果操作已完成、已失败或仍在取消中，则不会取消操作。
  • 获取支持格式：返回文档翻译功能支持的文档或词汇表格式列表。

关键链接：

入门

目前支持的环境

有关更多详细信息，请参阅我们的支持政策。

Prerequisites

安装 @azure/ai-translation-document 包

安装 Azure 文档翻译客户端库，支持npmJavaScript：

npm install @azure/ai-translation-document

Set Up Azure Blob 存储 account

批量翻译需要一个 Azure Blob 存储 账户。 关于创建 Azure Blob 存储 账户的更多信息，请参见这里。 关于为源文件和目标文件创建容器，请参见 这里。 请务必授权你的翻译资源存储访问权限，更多信息 请见此处。

当存储账户禁用“允许存储账户密钥访问”，在翻译器资源上启用管理身份，并且在存储账户上被赋予“存储Blob数据贡献者”角色时，你可以直接使用容器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 和类节点环境，你可以用该 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());

对于浏览器环境，使用 InteractiveBrowserCredential “from the @azure/identity package”来进行认证：

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 是异步批处理翻译以及查询翻译和文档状态的接口。 批量翻译需要一个 Azure Blob 存储 账户，里面有容器来存放源文档和翻译文档。

单文档翻译客户端

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);
}

故障排除

伐木业

启用日志记录可能有助于发现有关故障的有用信息。 若要查看 HTTP 请求和响应的日志，请将 AZURE_LOG_LEVEL 环境变量设置为 info。 或者，可以通过在 setLogLevel中调用 @azure/logger 在运行时启用日志记录：

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

setLogLevel("info");

有关如何启用日志的更详细说明，可以查看 @azure/记录器包文档。

贡献

若要参与此库，请阅读 贡献指南 了解有关如何生成和测试代码的详细信息。

  • Last updated on