ドキュメント翻訳クライアント ライブラリ SDK

  • [アーティクル]

ドキュメント翻訳は、Azure Translator サービスのクラウドベースの機能です。 元のドキュメントの構造と形式を維持したまま、ドキュメント全体を翻訳したり、さまざまなファイル形式のバッチ ドキュメント翻訳を処理したりすることができます。 この記事では、ドキュメント翻訳サービスの C#/.NET および Python クライアント ライブラリを使用する方法について説明します。 REST API については、クイックスタート ガイドを参照してください。

前提条件

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

  • アクティブな Azure アカウント。 アカウントがない場合は、無料アカウントを作成できます。

  • 単一サービス Translator リソース (マルチサービス Cognitive Services リソースとは異なる)。 ご自身のビジネスまたはアプリケーションが特定のリージョンを必要としない限り、 [グローバル] を選択します。 始めるには [Standard S1] 価格レベルを選びます (ドキュメント翻訳は無料レベルではサポートされていません)。

  • Azure Blob Storage アカウント。 Azure BLOB ストレージ アカウント内に、ソースおよびターゲット ファイル用のコンテナーを作成します。

    • ソースのコンテナー。 このコンテナーは、翻訳対象のファイルをアップロードする場所です (必須)。
    • ターゲットのコンテナー。 このコンテナーは、翻訳されたファイルを格納する場所です (必須)。

  • ソースおよびターゲット コンテナー用に Shared Access Signature (SAS) トークンを作成する必要もあります。 sourceUrl と targetUrl には Shared Access Signature (SAS) トークンを含める必要があり、クエリ文字列として追加します。 トークンは、コンテナーまたは特定の BLOB に割り当てることができます。 「ドキュメント翻訳プロセスの SAS トークンを作成する」を "参照してください"。

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

詳細については、SAS トークンの作成に関するページを "参照してください"。

クライアント ライブラリ

| パッケージ (NuGet)| クライアント ライブラリ | REST API | 製品ドキュメント | サンプル |

プロジェクトの設定

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

dotnet new console -n batch-document-translation

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

dotnet build

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

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

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

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

.NET CLI

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

NuGet パッケージ マネージャー

Install-Package Azure.AI.Translation.Document -Version 1.0.0

NuGet PackageReference

<ItemGroup>
    <!-- ... -->
<PackageReference Include="Azure.AI.Translation.Document" Version="1.0.0" />
    <!-- ... -->
</ItemGroup>

プロジェクト ディレクトリから、好みのエディターまたは IDE で Program.cs ファイルを開きます。 ディレクティブを使用して以下を追加します。

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

using System;
using System.Threading;

アプリケーションの Program クラスで、対象のキーとカスタム エンドポイントの変数を作成します。 詳細については、カスタム ドメイン名とキーに関するセクションを "参照してください"。

private static readonly string endpoint = "<your custom endpoint>";
private static readonly string key = "<your key>";

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

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

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

  • sourceUri。 翻訳するドキュメントが含まれるソース コンテナーの SAS URI。

  • targetUri。翻訳されたドキュメントが書き込まれるターゲット コンテナーの SAS URI。

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


public void StartTranslation() {
  Uri sourceUri = new Uri("<sourceUrl>");
  Uri targetUri = new Uri("<targetUrl>");

  DocumentTranslationClient client = new DocumentTranslationClient(new Uri(endpoint), new AzureKeyCredential(key));

  DocumentTranslationInput input = new DocumentTranslationInput(sourceUri, targetUri, "es")

  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.DocumentId}");
    Console.WriteLine($ "  Status:{document.Status}");
    if (document.Status == TranslationStatus.Succeeded) {
      Console.WriteLine($ "  Translated Document Uri: {document.TranslatedDocumentUri}");
      Console.WriteLine($ "  Translated to language: {document.TranslatedTo}.");
      Console.WriteLine($ "  Document source Uri: {document.SourceDocumentUri}");
    }
    else {
      Console.WriteLine($ "  Error Code: {document.Error.ErrorCode}");
      Console.WriteLine($ "  Message: {document.Error.Message}");
    }
  }
}

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

次のステップ

REST API クイックスタートを試す