バッチドキュメント翻訳クライアントライブラリ

[アーティクル]
02/26/2024

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

重要

ドキュメント翻訳は現在、Translator (単一サービス) リソースでのみサポートされており、Azure AI サービス (マルチサービス) リソースには含まれていません。
ドキュメント翻訳は有料レベルでサポートされます。 Language Studio では、S1 または D3 のインスタンス層のみがサポートされます。ドキュメント翻訳を試すには、Standard S1 を選ぶことをお勧めします。「Azure AI サービスの価格 - Translator」をご覧ください。

前提条件

開始するには、以下が必要です。

アクティブな Azure アカウント。アカウントがない場合は、無料アカウントを作成できます。
単一サービス Translator リソース (マルチサービス Azure AI サービスリソースとは異なる):。マネージド ID 認可でドキュメント翻訳機能を使用する予定の場合は、米国東部などの地理的リージョンを選択します。 Standard S1 または D3 または価格レベルを選択します。
Azure Blob Storage アカウント。 Azure Blob Storage アカウント内に、ソースおよびターゲットファイル用のコンテナーを作成します。
- ソースのコンテナー。このコンテナーは、翻訳対象のファイルをアップロードする場所です (必須)。
- ターゲットのコンテナー。このコンテナーは、翻訳されたファイルを格納する場所です (必須)。

ストレージコンテナーの承認

Translator リソースへのアクセスを承認するには、次のいずれかのオプションを選択できます。

✔️マネージド ID。マネージド ID は、Microsoft Entra ID と、Azure 管理対象リソースの固有アクセス許可を作成するサービスプリンシパルです。マネージド ID を使用すると、コードに資格情報を埋め込む必要なく、Translator アプリケーションを実行できます。マネージド ID は、ストレージデータへのアクセスを許可し、ソース URL とターゲット URL に Shared Access Signature トークン (SAS) を含めるように要件を置き換えるためのより安全な方法です。

詳細については、ドキュメント翻訳のマネージド ID をご覧ください。

Screenshot of managed identity flow (RBAC).

✔️ Shared Access Signature (SAS)。共有アクセス署名は、Translator サービスに対して、指定した期間の制限付きアクセスを許可する URL です。この方法を使うには、ソースおよびターゲットコンテナー用に Shared Access Signature (SAS) トークンを作成する必要があります。 sourceUrl と targetUrl には Shared Access Signature (SAS) トークンを含める必要があり、クエリ文字列として追加します。トークンは、コンテナーまたは特定の BLOB に割り当てることができます。

ソースのコンテナーまたは BLOB には、読み取りと一覧表示のアクセス権が指定されている必要があります。
ターゲットのコンテナーまたは BLOB には、書き込みと一覧表示のアクセス権が指定されている必要があります。

詳細については、「SAS トークンの作成」をご覧ください。

Screenshot of a resource URI with a SAS token.

アプリケーションをビルドする

Translator C#/.NET アプリケーションの作成、ビルド、実行に使用できるツールがいくつかあります。ここでは、コマンドラインインターフェイス (CLI) または Visual Studio を使用する方法について説明します。開始するには、次のいずれかのタブを選択します。

.NET CLI
Visual Studio

プロジェクトの設定

コンソールウィンドウ (cmd、PowerShell、Bash など) で、dotnet new コマンドを使用し、batch-document-translation という名前で新しいコンソールアプリを作成します。このコマンドにより、1 つのソースファイルを使用する単純な "Hello World" C# プロジェクトが作成されます。Program.cs。

dotnet new console -n batch-document-translation

新しく作成されたアプリフォルダーにディレクトリを変更します。次のコマンドでアプリケーションをビルドします。

dotnet build

ビルドの出力に警告やエラーが含まれないようにする必要があります。

...
Build succeeded.
 0 Warning(s)
 0 Error(s)
...

クライアントライブラリをインストールする

アプリケーションディレクトリ内で、.NET 用のドキュメント翻訳クライアントライブラリをインストールします。

dotnet add package Azure.AI.Translation.Document --version 1.0.0

ドキュメントまたはバッチファイルを翻訳する

このプロジェクトでは、ソースコンテナーにアップロードされたソースドキュメントが必要です。このクイックスタートでは、ドキュメント翻訳のサンプルドキュメントをダウンロードできます。ソース言語は英語です。
プロジェクトディレクトリから、好みのエディターまたは IDE で Program.cs ファイルを開きます。行 Console.WriteLine("Hello World!") を含む既存のコードを削除します。
アプリケーションの Program.cs で、対象のキーとカスタムエンドポイントの変数を作成します。詳細については、「キーとカスタムドメインエンドポイントを取得する」を "参照してください"。
```
private static readonly string endpoint = "<your-document-translation-endpoint>";
private static readonly string key = "<your-key>";
```
StartTranslationAsync メソッドを呼び出して、1 つの BLOB コンテナー内の 1 つ以上のドキュメントについて翻訳操作を開始します。

StartTranslationAsync を呼び出すには、以下の sourceUri、targetUri、targetLanguageCode パラメーターを含む DocumentTranslationInput オブジェクトを初期化する必要があります。

マネージド ID 承認の場合は、次の変数を作成します。

sourceUri。翻訳するドキュメントが含まれるソースコンテナーの URI。
targetUri。翻訳されたドキュメントが書き込まれるターゲットコンテナーの URL。

targetLanguageCode。翻訳されるドキュメントの言語コード。言語コードは、言語サポートに関するページに記載されています。

ソース URL とターゲット URL を見つけるには、Azure portal のストレージアカウントに移動します。左側のサイドバーの [データストレージ] で [コンテナー] を選び、以下の手順に従ってソースドキュメントとターゲットコンテナー URLS を取得します。

source	移行先
1. ソースコンテナーの横にあるチェックボックスをオンにします。	1. ターゲットコンテナーの横にあるチェックボックスをオンにします。
2.メインウィンドウ領域から、翻訳するファイルまたはドキュメントを選びます。	2. 右側にある省略記号を選択し、[プロパティ] を選択します。
3. ソース URL は、[プロパティ] リストの上部にあります。	3. ターゲット URL は、[プロパティ] リストの上部にあります。

Shared Access Signature (SAS) 承認の場合、これらの変数を作成します
- sourceUri。変換するドキュメントを含むソースコンテナーの SAS トークンがクエリ文字列として追加された SAS URI。
- targetUri SAS URI。SAS トークンがクエリ文字列として追加され、翻訳されたドキュメントの書き込み先のターゲットコンテナーに対します。
- targetLanguageCode。翻訳されるドキュメントの言語コード。言語コードは、言語サポートに関するページに記載されています。

コードサンプル

重要

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

次のコードサンプルを入力して、アプリケーションの Program.cs ファイルに貼り付けます。


using Azure;
using Azure.AI.Translation.Document;
using System;
using System.Threading;
using System.Text;

class Program {

  // create variables for your custom endpoint and resource key
  private static readonly string endpoint = "<your-document-translation-endpoint>";
  private static readonly string key = "<your-key>";

  static async Task Main(string[] args) {

    // create variables for your sourceUrl, targetUrl, and targetLanguageCode
    Uri sourceUri = new Uri("<sourceUrl>");
    Uri targetUri = new Uri("<targetUrl>");
    string targetLanguage = "<targetLanguageCode>"

    // initialize a new instance  of the DocumentTranslationClient object to interact with the Document Translation feature
    DocumentTranslationClient client = new DocumentTranslationClient(new Uri(endpoint), new AzureKeyCredential(key));

    // initialize a new instance of the `DocumentTranslationInput` object to provide the location of input for the translation operation
    DocumentTranslationInput input = new DocumentTranslationInput(sourceUri, targetUri, targetLanguage);

    // initialize a new instance of the DocumentTranslationOperation class to track the status of the translation operation
    DocumentTranslationOperation operation = await client.StartTranslationAsync(input);

    await operation.WaitForCompletionAsync();

    Console.WriteLine($"  Status: {operation.Status}");
    Console.WriteLine($"  Created on: {operation.CreatedOn}");
    Console.WriteLine($"  Last modified: {operation.LastModified}");
    Console.WriteLine($"  Total documents: {operation.DocumentsTotal}");
    Console.WriteLine($"    Succeeded: {operation.DocumentsSucceeded}");
    Console.WriteLine($"    Failed: {operation.DocumentsFailed}");
    Console.WriteLine($"    In Progress: {operation.DocumentsInProgress}");
    Console.WriteLine($"    Not started: {operation.DocumentsNotStarted}");

    await foreach(DocumentStatusResult document in operation.Value) {
      Console.WriteLine($"Document with Id: {document.Id}");
      Console.WriteLine($"  Status:{document.Status}");
      if (document.Status == DocumentTranslationStatus.Succeeded) {
        Console.WriteLine($"  Translated Document Uri: {document.TranslatedDocumentUri}");
        Console.WriteLine($"  Translated to language: {document.TranslatedToLanguageCode}.");
        Console.WriteLine($"  Document source Uri: {document.SourceDocumentUri}");
      } else {
        Console.WriteLine($"  Error Code: {document.Error.Code}");
        Console.WriteLine($"  Message: {document.Error.Message}");
      }
    }
  }
}

アプリケーションを実行する

コードサンプルをアプリケーションに追加したら、ターミナルで次のコマンドを入力して、プロジェクトディレクトリからアプリケーションを実行します。

  dotnet run

予想される出力のスニペットを次に示します。

Screenshot of the Visual Studio Code output in the terminal window.

C#/.NET 環境を設定する

このクイックスタートでは、最新バージョンの Visual Studio IDE を使用して、アプリケーションをビルドして実行します。

Visual Studio を起動します。
[概要] ページで、[新しいプロジェクトの作成] を選択します。
[新しいプロジェクトの作成] ページで、検索ボックスに「コンソール」と入力します。 [コンソールアプリケーション] テンプレートを選択し、 [次へ] を選択します。
[新しいプロジェクトの構成] ダイアログウィンドウの [プロジェクト名] ボックスに「asynchronous-sdk」と入力します。 [次へ] を選びます。
[追加情報] ダイアログウィンドウで、[.NET 6.0 (長期的なサポート)] を選択し、[作成] を選択します。

NuGet を使用してクライアントライブラリをインストールする

Translator-text-sdk プロジェクトを右クリックし、[NuGet パッケージの管理...] を選択します。
[参照] タブを選択し、「Azure.AI.Translation.Document」と入力します。
プロジェクトでパッケージを選択してインストールします。

C# アプリケーションをビルドする

注意

.NET 6 以降では、console テンプレートを使用する新しいプロジェクトによって、以前のバージョンとは異なる新しいプログラムスタイルが生成されます。
この新しい出力では、記述する必要があるコードを簡素化できる最新の C# 機能が使用されています。
新しいバージョンで使用する場合、記述する必要があるのは、`Main` メソッドの本体のみです。最上位レベルのステートメント、グローバル using ディレクティブ、または暗黙的な using ディレクティブを含める必要はありません。
詳細については、「新しい C# テンプレートで、最上位レベルのステートメントが生成される」を "参照" してください。

Program.cs ファイルを開きます。
行 Console.WriteLine("Hello World!") を含む既存のコードを削除します。
アプリケーションの Program.cs で、対象のキーとカスタムエンドポイントの変数を作成します。詳細については、「キーとカスタムドメインエンドポイントを取得する」を "参照してください"。

private static readonly string endpoint = "<your-document-translation-endpoint>";
private static readonly string key = "<your-key>";

1 つの BLOB コンテナー内の 1 つ以上のドキュメントについて翻訳操作を開始するには、StartTranslationAsync メソッドを呼び出します。

StartTranslationAsync を呼び出すには、以下の sourceUri、targetUri パラメーターを含む DocumentTranslationInput オブジェクトを初期化する必要があります。

マネージド ID 承認の場合は、次の変数を作成します。

sourceUri。翻訳するドキュメントが含まれるソースコンテナーの URI。
targetUri。翻訳されたドキュメントが書き込まれるターゲットコンテナーの URL。

targetLanguageCode。翻訳されるドキュメントの言語コード。言語コードは、言語サポートに関するページに記載されています。

source	移行先
1. ソースコンテナーの横にあるチェックボックスをオンにします。	1. ターゲットコンテナーの横にあるチェックボックスをオンにします。
2.メインウィンドウ領域から、翻訳するファイルまたはドキュメントを選びます。	2. 右側にある省略記号を選択し、[プロパティ] を選択します。
3. ソース URL は、[プロパティ] リストの上部にあります。	3. ターゲット URL は、[プロパティ] リストの上部にあります。

Shared Access Signature (SAS) 承認の場合、これらの変数を作成します
- sourceUri。変換するドキュメントを含むソースコンテナーの SAS トークンがクエリ文字列として追加された SAS URI。
- targetUri SAS URI。SAS トークンがクエリ文字列として追加され、翻訳されたドキュメントの書き込み先のターゲットコンテナーに対します。
- targetLanguageCode。翻訳されるドキュメントの言語コード。言語コードは、言語サポートに関するページに記載されています。

コードサンプル

重要

次のコードサンプルを入力して、アプリケーションの Program.cs ファイルに貼り付けます。


using Azure;
using Azure.AI.Translation.Document;

class Program {

  // create variables for your custom endpoint and resource key
  private static readonly string endpoint = "<your-document-translation-endpoint>";
  private static readonly string key = "<your-key>";

  static async Task Main(string[] args) {

    // create variables for your sourceUrl, targetUrl, and targetLanguageCode
    Uri sourceUri = new Uri("<sourceUrl>");
    Uri targetUri = new Uri("<targetUrl>");
    string targetLanguage = "<targetLanguageCode>";

    // initialize a new instance  of the DocumentTranslationClient object to interact with the Document Translation feature
    DocumentTranslationClient client = new DocumentTranslationClient(new Uri(endpoint), new AzureKeyCredential(key));

    // initialize a new instance of the `DocumentTranslationInput` object to provide source and target locations and target language for the translation operation
    DocumentTranslationInput input = new DocumentTranslationInput(sourceUri, targetUri, targetLanguage);

    // initialize a new instance of the DocumentTranslationOperation class to track the status of the translation operation
    DocumentTranslationOperation operation = await client.StartTranslationAsync(input);

    await operation.WaitForCompletionAsync();

    Console.WriteLine($"  Status: {operation.Status}");
    Console.WriteLine($"  Created on: {operation.CreatedOn}");
    Console.WriteLine($"  Last modified: {operation.LastModified}");
    Console.WriteLine($"  Total documents: {operation.DocumentsTotal}");
    Console.WriteLine($"    Succeeded: {operation.DocumentsSucceeded}");
    Console.WriteLine($"    Failed: {operation.DocumentsFailed}");
    Console.WriteLine($"    In Progress: {operation.DocumentsInProgress}");
    Console.WriteLine($"    Not started: {operation.DocumentsNotStarted}");

    await foreach(DocumentStatusResult document in operation.Value) {
      Console.WriteLine($"Document with Id: {document.Id}");
      Console.WriteLine($"  Status:{document.Status}");
      if (document.Status == DocumentTranslationStatus.Succeeded) {
        Console.WriteLine($"  Translated Document Uri: {document.TranslatedDocumentUri}");
        Console.WriteLine($"  Translated to language: {document.TranslatedToLanguageCode}.");
        Console.WriteLine($"  Document source Uri: {document.SourceDocumentUri}");
      } else {
        Console.WriteLine($"  Error Code: {document.Error.Code}");
        Console.WriteLine($"  Message: {document.Error.Message}");
      }
    }
  }
}

アプリケーションを実行する

アプリケーションにコードサンプルを追加したら、formRecognizer_quickstart の横にある緑色の [スタート] ボタンを選んで、プログラムをビルドして実行するか、F5 キーを押します。

Screenshot: run your Visual Studio program.

予想される出力のスニペットを次に示します。

Screenshot of the Visual Studio Code output in the terminal window.

これで完了です。 .NET クライアントライブラリを使ってストレージコンテナー内のドキュメントを翻訳するプログラムを作成しました。

プロジェクトの設定

最新バージョンの Python がインストールされていることを確認します。

クライアントライブラリをインストールする

ドキュメント翻訳クライアントライブラリの最新バージョンをインストールします。

pip install azure-ai-translation-document==1.0.0

ドキュメントまたはバッチファイルを翻訳する

このプロジェクトでは、ソースコンテナーにアップロードされたソースドキュメントが必要です。このクイックスタートでは、ドキュメント翻訳のサンプルドキュメントをダウンロードできます。ソース言語は英語です。
Python アプリケーションファイルで、リソースキーとカスタムエンドポイントの変数を作成します。詳細については、「キーとカスタムドメインエンドポイントを取得する」を "参照してください"。

key = "<your-key>"
endpoint = "<your-custom-endpoint>"

DocumentTranslationClient パラメーターと endpoint パラメーターを含む key オブジェクトを初期化します。

begin_translation メソッドを呼び出し、sourceUri、targetUri、targetLanguageCode パラメーターを渡します。

マネージド ID 承認の場合は、次の変数を作成します。

sourceUri。翻訳するドキュメントが含まれるソースコンテナーの URI。
targetUri。翻訳されたドキュメントが書き込まれるターゲットコンテナーの URL。

targetLanguageCode。翻訳されるドキュメントの言語コード。言語コードは、言語サポートに関するページに記載されています。

source	移行先
1. ソースコンテナーの横にあるチェックボックスをオンにします。	1. ターゲットコンテナーの横にあるチェックボックスをオンにします。
2.メインウィンドウ領域から、翻訳するファイルまたはドキュメントを選びます。	2. 右側にある省略記号を選択し、[プロパティ] を選択します。
3. ソース URL は、[プロパティ] リストの上部にあります。	3. ターゲット URL は、[プロパティ] リストの上部にあります。

Shared Access Signature (SAS) 承認の場合、これらの変数を作成します
- sourceUri。変換するドキュメントを含むソースコンテナーの SAS トークンがクエリ文字列として追加された SAS URI。
- targetUri SAS URI。SAS トークンがクエリ文字列として追加され、翻訳されたドキュメントの書き込み先のターゲットコンテナーに対します。
- targetLanguageCode。翻訳されるドキュメントの言語コード。言語コードは、言語サポートに関するページに記載されています。

コードサンプル

重要

Python アプリケーションに次のコードサンプルを入力します。


#  import libraries
from azure.core.credentials import AzureKeyCredential
from azure.ai.translation.document import DocumentTranslationClient

# create variables for your resource key, custom endpoint, sourceUrl, targetUrl, and targetLanguage
key = "<your-key>"
endpoint = "<your-custom-endpoint>"
sourceUri = "<your-container-sourceUrl>"
targetUri = "<your-container-targetUrl>"
targetLanguage = "<target-language-code>"


# initialize a new instance of the DocumentTranslationClient object to interact with the Document Translation feature
client = DocumentTranslationClient(endpoint, AzureKeyCredential(key))

# include source and target locations and target language code for the begin translation operation
poller = client.begin_translation(sourceUri, targetUri, targetLanguage)
result = poller.result()

print("Status: {}".format(poller.status()))
print("Created on: {}".format(poller.details.created_on))
print("Last updated on: {}".format(poller.details.last_updated_on))
print(
    "Total number of translations on documents: {}".format(
        poller.details.documents_total_count
    )
)

print("\nOf total documents...")
print("{} failed".format(poller.details.documents_failed_count))
print("{} succeeded".format(poller.details.documents_succeeded_count))

for document in result:
    print("Document ID: {}".format(document.id))
    print("Document status: {}".format(document.status))
    if document.status == "Succeeded":
        print("Source document location: {}".format(document.source_document_url))
        print(
            "Translated document location: {}".format(document.translated_document_url)
        )
        print("Translated to language: {}\n".format(document.translated_to))
    else:
        print(
            "Error Code: {}, Message: {}\n".format(
                document.error.code, document.error.message
            )
        )

アプリケーションを実行する

アプリケーションにコードサンプルを追加したら、ターミナルで次のコマンドを入力します。

python asynchronous-sdk.py

予想される出力のスニペットを次に示します。

Screenshot of the Python output in the terminal window.

これで完了です。 Python クライアントライブラリを使ってストレージコンテナー内のドキュメントを翻訳するプログラムを作成しました。

次のステップ

ドキュメント翻訳操作の詳細

バッチ ドキュメント翻訳クライアント ライブラリ

前提条件

ストレージ コンテナーの承認

アプリケーションをビルドする

プロジェクトの設定

クライアント ライブラリをインストールする

ドキュメントまたはバッチ ファイルを翻訳する

コード サンプル

アプリケーションを実行する

プロジェクトの設定

クライアント ライブラリをインストールする

ドキュメントまたはバッチ ファイルを翻訳する

コード サンプル

アプリケーションを実行する

次のステップ

その他のリソース

バッチドキュメント翻訳クライアントライブラリ

ストレージコンテナーの承認

クライアントライブラリをインストールする

ドキュメントまたはバッチファイルを翻訳する

コードサンプル

クライアントライブラリをインストールする

ドキュメントまたはバッチファイルを翻訳する

コードサンプル