概要: Document Translation REST API

2025-01-27

ドキュメント翻訳は、サポートされている言語とさまざまなファイル形式でドキュメント全体を非同期的に翻訳する Azure AI Translator サービスのクラウドベースの機能です。このクイックスタートでは、ドキュメント翻訳と任意のプログラミング言語を使用して、構造とテキストの書式設定を維持しながら、ソースドキュメントをターゲット言語に翻訳する方法について説明します。

Document Translation API では、2 つの翻訳プロセスがサポートされています。

非同期バッチ翻訳では、複数のドキュメントと大きなファイルの処理がサポートされます。バッチ翻訳プロセスでは、ソースと翻訳後のドキュメント用のストレージコンテナーを含む Azure Blob Storage アカウントが必要です。
同期単一ファイルでは、単一ファイルの翻訳の処理がサポートされます。このファイル翻訳プロセスでは、Azure Blob Storage アカウントは必要ありません。最後の応答に翻訳されたドキュメントが含まれており、それが呼び出し元のクライアントに直接返されます。

それでは始めましょう。

前提条件

アクティブな Azure サブスクリプションが必要です。 Azure サブスクリプションがない場合は、無料で作成することができます。

Azure サブスクリプションを入手したら、Azure portal で Azure AI Translator リソースを作成します。
Note
- このクイックスタートでは、ビジネスまたはアプリケーションで特定のリージョンが必要な場合を除き、Azure AI Translator テキストの単一サービスグローバルリソースを使用することをお勧めします。認証にシステム割り当てマネージド ID を使用する場合は、米国西部などの地理的リージョンを選択します。
- 単一サービスグローバルリソースでは、REST API 要求に 1 つの承認ヘッダー (Ocp-Apim-Subscription-key) を含めます。 Ocp-Apim-Subscription-key の値は、Azure AI Translator Text サブスクリプションの Azure 秘密鍵です。
リソースがデプロイされたら、[リソースに移動] を選択してキーとエンドポイントを取得します。
- 自分のアプリケーションを Azure AI Translator サービスに接続するには、リソースのキーとエンドポイントが必要です。このクイックスタートで後に示すコードに、自分のキーとエンドポイントを貼り付けます。これらの値は Azure portal の [キーとエンドポイント] ページで確認できます。
このプロジェクトでは、cURL コマンドラインツールを使って REST API 呼び出しを行います。

Note

cURL パッケージは、ほとんどの Windows 10 と Windows 11、およびほとんどの macOS および Linux ディストリビューションにプレインストールされています。パッケージのバージョンは、次のコマンドを使用してチェックすることができます。Windows: curl.exe -V macOS: curl -V Linux: curl --version
cURL がインストールされていない場合は、お使いのプラットフォームに応じた次のインストールリンクをお使いください。
- Windows
- Mac または Linux

ドキュメントを非同期的に翻訳する (POST)

任意のエディターまたは IDE を使用して、document-translation という名前のアプリ用の新しいディレクトリを作成します。
document-translation ディレクトリに document-translation.json という名前の新しい json ファイルを作成します。
ドキュメント翻訳の要求サンプルをコピーして、document-translation.json ファイルに貼り付けます。 {your-source-container-SAS-URL} と {your-target-container-SAS-URL} を、Azure portal のストレージアカウントコンテナーインスタンスの値で置き換えます。

"要求のサンプル:"
```
{
  "inputs":[
    {
      "source":{
        "sourceUrl":"{your-source-container-SAS-URL}"
      },
      "targets":[
        {
          "targetUrl":"{your-target-container-SAS-URL}",
          "language":"fr"
        }
      ]
    }
  ]
}
```

POST 要求をビルドして実行する

POST 要求を実行する前に、{your-document-translator-endpoint} と {your-key} を、Azure portal の Azure AI Translator インスタンスからの値に置き換えます。

重要

終わったらコードからキーを削除し、公開しないよう注意してください。運用環境では、Azure Key Vault などの資格情報を格納してアクセスする安全な方法を使用します。詳しくは、「Azure AI サービスのセキュリティ」をご覧ください。

PowerShell

cmd /c curl "{document-translation-endpoint}/translator/document/batches?api-version={date}" -i -X POST --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@document-translation.json"

コマンドプロンプトまたはターミナル

curl "{document-translation-endpoint}/translator/document/batches?api-version={date}" -i -X POST --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@document-translation.json"

正常に完了したら、次のようになります。

翻訳されたドキュメントはターゲットコンテナーにあります。
成功した POST メソッドから 202 Accepted 応答コードが返され、バッチ要求によってサービスが作成されたことが示されます。
POST 要求では、後続の GET 要求で使用される値を提供する Operation-Location を含む応答ヘッダーも返します。

1 つのドキュメントを同期的に翻訳する (POST)

REST API を介して同期翻訳機能を呼び出すには、各要求に次のヘッダーを含める必要があります。このサンプルコードにはヘッダーが含まれていますので、ご安心ください。

Note

すべての cURL フラグとコマンドラインオプションでは、大文字と小文字が区別されます。

Query parameter (クエリパラメーター)	説明	条件
`-X` または `--requestPOST`	-X フラグは、API にアクセスするための要求メソッドを指定します。	必須
`{endpoint}`	ドキュメント翻訳リソースエンドポイントの URL	必須
`targetLanguage`	出力ドキュメントの言語を指定します。ターゲット言語は、翻訳スコープに含まれているサポートされている言語のいずれかとする必要があります。	必須
`sourceLanguage`	入力ドキュメントの言語を指定します。 `sourceLanguage` パラメーターが指定されていない場合は、自動言語検出が適用されてソース言語が特定されます。	オプション
`-H` または `--header"Ocp-Apim-Subscription-Key:{KEY}`	API へのアクセスを承認するドキュメント翻訳リソースキーを指定する要求ヘッダー。	必須
`-F` または `--form`	要求に含めるドキュメントのファイルパス。許可されるソースドキュメントは 1 つだけです。	必須
• `document=` • `type={contentType}/fileExtension`	• ソースドキュメントのファイルの場所のパス。 • コンテンツの種類とファイル拡張子。例: "document=@C:\Test\test-file.md;type=text/markdown	必須
`-o` または `--output`	応答結果のファイルパス。	必須
`-F` または `--form`	要求に含めるオプションの用語集のファイルパス。用語集には別個の `--form` フラグが必要です。	オプション
• `glossary=` • `type={contentType}/fileExtension`	• オプションの用語集ファイルを示すファイルの場所のパス。 • コンテンツの種類とファイル拡張子。例: "glossary=@C:\Test\glossary-file.txt;type=text/plain	オプション

✔️ contentType の詳細については、サポートされるドキュメントの形式を "参照してください"。

同期 POST 要求をビルドして実行する

このプロジェクトには、サンプルドキュメントが必要です。このクイックスタート用に、Microsoft Word サンプルドキュメントをダウンロードできます。ソース言語は英語です。
POST 要求を実行する前に、{your-document-translation-endpoint} と {your-key} を、Azure portal の Azure AI Translator サービスインスタンスからの値に置き換えます。

重要

終わったらコードからキーを削除し、公開しないよう注意してください。運用環境では、Azure Key Vault などの資格情報を格納してアクセスする安全な方法を使用します。詳しくは、「Azure AI サービスのセキュリティ」をご覧ください。

コマンドプロンプトまたはターミナル
```
curl -i -X POST "{document-translation-endpoint}/translator/document:translate?targetLanguage={target_language}&api-version={date}" -H "Ocp-Apim-Subscription-Key:{your-key}"  -F "document={path-to-your-document-with-file-extension};type={ContentType}/{file-extension}" -F "glossary={path-to-your-glossary-with-file-extension};type={ContentType}/{file-extension}" -o "{path-to-output-file}"
```
PowerShell
```
cmd /c curl "{document-translation-endpoint}/translator/document:translate?targetLanguage={target_language}&api-version={date}" -i -X POST  -H "Ocp-Apim-Subscription-Key: {your-key}" -F "{path-to-your-document-with-file-extension};type=text/{file-extension}" -o "{path-to-output-file}
```
✔️ Query parameters の詳細については、同期ドキュメント翻訳を "参照してください"。

"正常に完了した場合":

翻訳されたドキュメントが応答で返されます。
成功した POST メソッドから 200 OK 応答コードが返され、サービスによって要求が作成されたことが示されます。

以上です。お疲れさまでした。 Azure AI 翻訳サービスを使用してドキュメントを翻訳する方法を学習しました。

次のステップ

ドキュメント翻訳 REST API ガイド