Azure Document Translation client library for JavaScript - version 1.0.0

ドキュメント翻訳は、Azure AI 翻訳サービスにおけるクラウドベースの機械翻訳機能です。複数の複雑な文書を、すべての対応言語や方言で翻訳しつつ、元の文書構造やデータ形式を保持できます。 Document Translation API では、次の 2 つの翻訳プロセスがサポートされています。

非同期バッチ翻訳では、複数のドキュメントと大きなファイルの処理がサポートされます。バッチ翻訳プロセスでは、翻訳前と翻訳後のドキュメント用のストレージコンテナーを含む Azure Blob Storage アカウントが必要です。

同期単ファイル変換は単ファイル変換の処理をサポートします。このファイル翻訳プロセスでは、Azure Blob Storage アカウントは必要ありません。最後の応答には翻訳されたドキュメントが含まれており、呼び出し元のクライアントに直接返されます。

文書翻訳機能でサポートされている操作は以下の通りです:

同期文書翻訳:単一の文書を同期翻訳するために使用されます。この方法では、Azure Blob Storage アカウントは必要ありません。
バッチ変換開始:非同期バッチ変換要求を実行するために使用されます。この方法では、ソースドキュメントと翻訳済みドキュメントのストレージコンテナーを含む Azure BLOB ストレージアカウントが必要です。
すべての翻訳ジョブのステータスを取得する:ユーザーが(リソースに関連付けられている)から提出されたすべての翻訳ジョブのリストとステータスを要求するために使われます。
特定の翻訳ジョブのステータスを取得する:特定の翻訳ジョブのステータスをリクエストするために使われます。応答には、ジョブ全体の状態と、そのジョブの一部として翻訳されるドキュメントの状態が含まれます。
すべての文書のステータスを取得する:翻訳ジョブのすべての文書のステータスを要求するために使われました。
特定ドキュメントのステータスを取得する:リクエストで示されたidおよびdocumentIdクエリパラメータで、ジョブ内の特定のドキュメントの状態を返します。
翻訳キャンセル:現在処理中またはキューに入っている(保留中)の翻訳ジョブをキャンセルします。既に完了している場合、失敗した場合、または取り消し中の場合、操作は取り消されません。
サポートフォーマットを取得する:ドキュメント翻訳機能でサポートされているドキュメントまたは用語集フォーマットのリストを返します。

主要なリンク:

作業の開始

現在サポートされている環境

Node.js の LTS バージョン
Safari、Chrome、Edge、Firefox の最新バージョン。

詳細については、サポートポリシーのを参照してください。

前提条件

Azure サブスクリプション。
既存のTranslatorサービスやAzure AI サービスリソース。「翻訳者作成」リソースを参照してください。

`@azure/ai-translation-document` パッケージをインストールする

JavaScript用のAzure Document Translationクライアントライブラリをnpmインストールしてください:

npm install @azure/ai-translation-document

Set Azure Blob Storage account

バッチ翻訳にはAzure Blob Storageアカウントが必要です。 Azure Blob Storageアカウントの作成についての詳細はこちらをご覧ください。ソースファイルとターゲットファイルのコンテナを作成するには、こちらをご覧ください。翻訳リソースの保存アクセスを必ず許可してください。詳細はこちらをご覧ください。

ストレージアカウントで「Allow Storage Account Key Access」が無効になり、Managed Identityがトランスレーターリソースで有効になり、ストレージアカウントで「Storage Blob Data Contributor」として役割が割り当てられれば、コンテナURLを直接使用でき、SAS URIの生成は不要になります。

クライアントを認証する

このライブラリは2つのクライアントを露出させます:

DocumentTranslationClient バッチ翻訳および翻訳状態操作のために。
SingleDocumentTranslationClient 同期単一文書翻訳用。

両クライアントはMicrosoft Entraの認証情報またはAPIキーで認証できます。

Microsoft Entraの認証情報の使用

Microsoft Entra IDで認証は、@azure/identityライブラリの認証情報を使ってできます。以下に示す 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キーの使用

また、リソースのAPIキーで認証することも KeyCredential:

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 Storageアカウントが必要です。

SingleDocumentTranslationClient

SingleDocumentTranslationClient は同期単一文書変換のインターフェースです。 Azure Blob Storageアカウントは必要ありません。翻訳された文書はレスポンス内で直接返されます。

例示

以下のセクションでは、このクライアントライブラリの主な機能をカバーするいくつかのコードスニペットを提供します。

同期ドキュメント翻訳

単一の文書を同期翻訳するために使われていました。この方法では、Azure Blob Storage アカウントは必要ありません。

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/logger パッケージのドキュメントを参照してください。

投稿

このライブラリに投稿する場合は、コードをビルドしてテストする方法の詳細については、投稿ガイドを参照してください。

Microsoft Azure SDK for JavaScript の

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-08-13