コンテナー: テキストを翻訳する

[アーティクル]
09/01/2024

テキストを翻訳する。

要求 URL

POST 要求の送信先は次のとおりです。

POST http://localhost:{port}/translate?api-version=3.0&&from={from}&to={to}

要求の例

curl -x POST "https:localhost:5000/translate?api-version=3.0&from=en&to=es" -H "Content-Type: application/json" -d "[{
'Text': 'I would really like to drive your car.'}]"

応答の例

[
  {
    "translations": [
      {
        "text": "Realmente me gustaría conducir su coche.",
        "to": "es"
      }
    ]
  }
]

要求パラメーター

クエリ文字列に渡される要求パラメーターを次に示します。

必須のパラメーター

Query parameter (クエリパラメーター)	説明	条件
api-version	クライアントによって要求される API のバージョン。値は `3.0` とする必要があります。	必須パラメーター
from	入力テキストの言語を指定します。	必須パラメーター
to	出力テキストの言語を指定します。たとえば、ドイツ語に翻訳するには `to=de` を使用します。クエリ文字列内でパラメーターを繰り返すことにより、同時に複数の言語に翻訳することができます。たとえば、ドイツ語とイタリア語に翻訳するには、`to=de&to=it` を使用します。	必須パラメーター

サポートされている言語スコープtranslationサービスに対してクエリを実行できます。
表記変換 Language のサポートも参照してください。

オプションパラメーター

Query parameter (クエリパラメーター)	説明
textType	"省略可能なパラメーター"。翻訳するテキストがプレーンテキストか、それとも HTML テキストかを定義します。 HTML の場合は、適切な形式の完全な要素である必要があります。指定できる値は `plain` (既定値) または `html` です。
includeSentenceLength	"省略可能なパラメーター"。入力テキストと翻訳済みテキストに対して文の境界を含めるかどうかを指定します。指定できる値は `true` または `false` (既定値) です。

要求ヘッダー

ヘッダー	説明	条件
認証ヘッダー	認証使用可能なオプションを参照してください。	必要な要求ヘッダー
コンテンツタイプ	ペイロードのコンテンツタイプを指定します。指定できる値は `application/json; charset=UTF-8` です。	必要な要求ヘッダー
Content-Length	要求本文の長さ。	オプション
X-ClientTraceId	要求を一意に識別する、クライアントで生成された GUID。 `ClientTraceId` という名前のクエリパラメーターを使用してクエリ文字列内にトレース ID を含める場合、このヘッダーは省略できます。	オプション

要求本文

要求の本文は JSON 配列です。各配列要素は、Text という名前の文字列プロパティ (翻訳するテキストを表す) を持つ JSON オブジェクトです。

[
    {"Text":"I would really like to drive your car around the block a few times."}
]

次の制限事項が適用されます。

配列に含めることができる要素は、最大でも 100 個です。
要求に含めるテキスト全体は、スペースも含めて 50,000 文字以下にする必要があります。

応答の本文

正常な応答は、入力配列内の文字列ごとに 1 つの結果が含まれる JSON 配列となります。結果オブジェクトには次のプロパティが含まれています。

translations:翻訳結果の配列です。配列のサイズは、to クエリパラメーターを通して指定されたターゲット言語の数に一致します。配列内の各要素は次のとおりです。
to:ターゲット言語の言語コードを表す文字列です。
text:翻訳済みテキストを提供する文字列です。
sentLen:入力テキストと出力テキスト内で文の境界を返すオブジェクトです。
srcSentLen:入力テキスト内の文の長さを表す整数配列です。配列の長さは文の数であり、値は各文の長さです。
transSentLen: 翻訳済みテキスト内の文の長さを表す整数配列です。配列の長さは文の数であり、値は各文の長さです。

文の境界は、要求パラメーター includeSentenceLength が true の場合にのみ含められます。
- sourceText:text という名前の 1 つの文字列プロパティを持つオブジェクトです。これにより、ソース言語の既定のスクリプトで入力テキストが提供されます。 sourceText プロパティは、言語の通常のスクリプトではないスクリプトで入力が表されている場合にのみ存在します。たとえば、入力がラテン文字で記述されたアラビア語であるならば、sourceText.text は同じアラビア語のテキストをアラビア文字に変換したものとなります。

応答ヘッダー

ヘッダー	説明
X-RequestId	要求を識別するためにサービスによって生成され、トラブルシューティングのために使用される値。
X-MT-System	翻訳が必要な各ターゲット言語への翻訳に使用されたシステムの種類を示します。値は、文字列のコンマ区切りの一覧です。各文字列は型を示しています。 ▪ Custom - 要求にはカスタムシステムが含まれ、翻訳中に少なくとも 1 つのカスタムシステムが使用されています。 ▪ Team - その他のすべての要求

ヘッダー

説明

X-RequestId

要求を識別するためにサービスによって生成され、トラブルシューティングのために使用される値。

X-MT-System

翻訳が必要な各ターゲット言語への翻訳に使用されたシステムの種類を示します。値は、文字列のコンマ区切りの一覧です。各文字列は型を示しています。

▪ Custom - 要求にはカスタムシステムが含まれ、翻訳中に少なくとも 1 つのカスタムシステムが使用されています。
▪ Team - その他のすべての要求

応答状態コード

エラーが発生した場合、要求から JSON エラー応答を返します。このエラーコードは 3 桁の HTTP ステータスコードの後に､エラーをさらに分類するための 3 桁の数字を続けた 6 桁の数字です｡一般的なエラーコードは、v3 Translator のリファレンスページで確認できます。

コードサンプル: テキストを翻訳する

Note

各サンプルは、docker run コマンドで指定したlocalhostで実行されます。
コンテナーの実行中、 localhost はコンテナー自体を指します。
localhost:5000を使用する必要はありません。ホスト環境でまだ使用されていない任意のポートを使用できます。

単一の入力を翻訳する

この例では、1 つの文を英語から簡体中国語に翻訳する方法を示します。

curl -X POST "http://localhost:{port}/translate?api-version=3.0&from=en&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

応答本文を次に示します。

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"}
        ]
    }
]

translations 配列には 1 つの要素が含まれており、これによって入力内の単一のテキストの翻訳が提供されます。

Azure AI Translator エンドポイントのクエリ (テキスト)

docker run コマンドで指定した localhost:5000 を使用した cURL HTTP 要求の例を次に示します。

  curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-HANS"
    -H "Content-Type: application/json" -d "[{'Text':'Hello, what is your name?'}]"

Note

コンテナーの準備が整う前に cURL POST 要求を実行しようとすると、「サービスは一時的に利用できません」という応答を最終的に受け取ります。コンテナーの準備が整うまで待ってから、もう一度やり直してください。

Swagger API を使用してテキストを翻訳する

英語 ↔ ドイツ語

Swagger ページに移動します。 http://localhost:5000/swagger/index.html
[POST /translate](POST /翻訳) を選択します
[試してみる]を選択します
en として、From パラメータを入力します
de として、To パラメータを入力します
3.0 として、api-version パラメーターを入力します
[テキスト] の下で、string を次の JSON に置き換えます

  [
        {
            "text": "hello, how are you"
        }
  ]

[実行] を選択すると、結果として得られる翻訳が [応答本文] に出力されます。次のような応答が表示されます。

"translations": [
      {
          "text": "hallo, wie geht es dir",
          "to": "de"
      }
    ]

Python を使用してテキストを翻訳する

英語 (フランス語) ↔

import requests, json

url = 'http://localhost:5000/translate?api-version=3.0&from=en&to=fr'
headers = { 'Content-Type': 'application/json' }
body = [{ 'text': 'Hello, how are you' }]

request = requests.post(url, headers=headers, json=body)
response = request.json()

print(json.dumps(
    response,
    sort_keys=True,
     indent=4,
     ensure_ascii=False,
     separators=(',', ': ')))

C#/.NET コンソールアプリでテキストを翻訳する

英語 ↔ (スペイン語)

Visual Studio を起動し、新しいコンソールアプリケーションを作成します。 *.csproj ファイルを編集して、<LangVersion>7.1</LangVersion> ノードを追加します。これは、C# 7.1 を指定します。 Newtoonsoft.Json NuGet パッケージバージョン 11.0.2 を追加します。

Program.cs で、すべての既存のコードを次のスクリプトに置き換えます。

using Newtonsoft.Json;
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

namespace TranslateContainer
{
    class Program
    {
        const string ApiHostEndpoint = "http://localhost:5000";
        const string TranslateApi = "/translate?api-version=3.0&from=en&to=es";

        static async Task Main(string[] args)
        {
            var textToTranslate = "Sunny day in Seattle";
            var result = await TranslateTextAsync(textToTranslate);

            Console.WriteLine(result);
            Console.ReadLine();
        }

        static async Task<string> TranslateTextAsync(string textToTranslate)
        {
            var body = new object[] { new { Text = textToTranslate } };
            var requestBody = JsonConvert.SerializeObject(body);

            var client = new HttpClient();
            using (var request =
                new HttpRequestMessage
                {
                    Method = HttpMethod.Post,
                    RequestUri = new Uri($"{ApiHostEndpoint}{TranslateApi}"),
                    Content = new StringContent(requestBody, Encoding.UTF8, "application/json")
                })
            {
                // Send the request and await a response.
                var response = await client.SendAsync(request);

                return await response.Content.ReadAsStringAsync();
            }
        }
    }
}

複数の文字列を翻訳する

一度に複数の文字列を翻訳するには、要求本文に文字列の配列を指定するだけです。

curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}, {'Text':'I am fine, thank you.'}]"

応答には、テキストの全箇所の翻訳が要求とまったく同じ順序で含まれます。応答本文を次に示します。

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"}
        ]
    },
    {
        "translations":[
            {"text":"我很好，谢谢你。","to":"zh-Hans"}
        ]
    }
]

複数の言語に変換する

この例では、1 つの要求で同じ入力を複数の言語に翻訳する方法を示します。

curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-Hans&to=de" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

応答本文を次に示します。

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"},
            {"text":"Hallo, was ist dein Name?","to":"de"}
        ]
    }
]

マークアップを使用してコンテンツを翻訳し、翻訳されたコンテンツを指定する

HTML ページからのコンテンツや XML ドキュメントからのコンテンツなど、マークアップを含むコンテンツを翻訳することは一般的です。タグ付きのコンテンツを翻訳する場合は、クエリパラメーター textType=html を含めます。さらに、特定のコンテンツを翻訳から除外すると便利な場合があります。属性 class=notranslate を使用すると、元の言語のまま残す必要があるコンテンツを指定できます。次の例では、最初の div 要素内のコンテンツは翻訳されませんが、2 番目の div 要素内のコンテンツは翻訳されます。

<div class="notranslate">This will not be translated.</div>
<div>This will be translated. </div>

次のサンプル要求で説明します。

curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-Hans&textType=html" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'<div class=\"notranslate\">This will not be translated.</div><div>This will be translated.</div>'}]"

応答は次のとおりです。

[
    {
        "translations":[
            {"text":"<div class=\"notranslate\">This will not be translated.</div><div>这将被翻译。</div>","to":"zh-Hans"}
        ]
    }
]

動的ディクショナリを使用して翻訳する

単語や語句に適用する翻訳があらかじめわかっている場合は、それを要求内でマークアップとして指定することができます。動的ディクショナリは、人名や製品名などの固有名詞に対してのみ安全に使用できます。

指定するマークアップでは、次の構文を使用します。

<mstrans:dictionary translation="translation of phrase">phrase</mstrans:dictionary>

たとえば、"The word wordomatic is a dictionary entry." という英語の文を考えてみます。翻訳に wordomatic という単語を保持するには、次のように要求を送信します。

curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=de" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'The word <mstrans:dictionary translation=\"wordomatic\">word or phrase</mstrans:dictionary> is a dictionary entry.'}]"

結果は次のとおりです。

[
    {
        "translations":[
            {"text":"Das Wort \"wordomatic\" ist ein Wörterbucheintrag.","to":"de"}
        ]
    }
]

この機能は、textType=text または textType=html の場合も同じように動作します。この機能は慎重に使用する必要があります。翻訳をカスタマイズするには、Custom Translator を使用するのが適切で望ましい方法です。 Custom Translator では、コンテキストおよび統計的確率を最大限に活用します。コンテキスト内の作業またはフレーズを示すトレーニングデータを作成した場合、より良い結果が得られます。 Custom Translator の詳細については、こちらを参照してください。

要求の制限

各翻訳要求は、翻訳先のターゲット言語すべての合計で 50,000 文字までに制限されています。たとえば、3,000 文字を 3 つの異なる言語に翻訳する翻訳要求を送信すると、要求のサイズは 3,000 x 3 = 9,000 文字となり、要求の制限が満たされます。要求の数ではなく、文字単位で課金されます。短い要求を送信することをお勧めします。

次の表には、Translator の翻訳操作に関する配列要素および文字の制限が一覧表示されています。

操作	配列要素の最大サイズ	配列要素の最大数	最大要求サイズ (文字数)
translate	10,000	100	50,000

Docker compose を使用する: Translator とサポートするコンテナー

Docker compose は、通常は compose.yaml という名前の 1 つの YAML ファイルを使用してマルチコンテナーアプリケーションを構成できるツールです。 docker compose up コマンドを使用してコンテナーアプリケーションを起動し、docker compose down コマンドを使用してコンテナーを停止および削除します。

Docker Desktop CLI をインストールした場合は、Docker Compose とその前提条件が含まれます。 Docker Desktop がない場合は、Docker Compose のインストールに関する概要を参照してください。

次の表に、テキスト翻訳やドキュメント翻訳の操作に必要なサポートコンテナーを一覧表示します。翻訳コンテナーは、Azure アカウント上の Azure AI 翻訳リソースを介して、Azure に課金情報を送信します。

操作	クエリの要求	ドキュメント型	サポートコンテナー
• テキスト翻訳 • ドキュメント翻訳	`from` が指定されています。	Office ドキュメント	なし
• テキスト翻訳 • ドキュメント翻訳	`from` は指定されていません。ソース言語を特定するための自動言語検出が必要です。	Office ドキュメント	✔️ テキスト分析: 言語コンテナー
• テキスト翻訳 • ドキュメント翻訳	`from` が指定されています。	スキャンされた PDF ドキュメント	✔️ ビジョン: 読み取りコンテナー
• テキスト翻訳 • ドキュメント翻訳	ソース言語を特定するための自動言語検出が必要な `from` は指定されていません。	スキャンされた PDF ドキュメント	✔️ テキスト分析: 言語コンテナー ✔️ ビジョン: 読み取りコンテナー

コンテナーイメージとタグ

Azure AI サービスのコンテナーイメージは、Microsoft アーティファクトレジストリ カタログで見つけることができます。次の表に、テキスト翻訳やドキュメント翻訳用の完全修飾イメージの場所を一覧表示します。

コンテナー	画像の場所	メモ
Translator: テキスト翻訳	`mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest`	MCR の Azure AI サービステキスト翻訳バージョンタグの完全な一覧を表示できます。
Translator: ドキュメント翻訳	TODO	TODO
テキスト分析: 言語	`mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest`	MCR の Azure AI サービス Text Analytics Language バージョンタグの完全な一覧を表示できます。
Vision: 読み取り	`mcr.microsoft.com/azure-cognitive-services/vision/read:latest`	MCR の Azure AI サービス Computer Vision Read の `OCR` バージョンタグの完全な一覧を表示できます。

アプリケーションを作成する

任意のエディターまたは IDE を使用して、container-environment または希望の名前のアプリ用の新しいディレクトリを作成します。
compose.yaml という名前の新しい YAML ファイルを作成します。 compose ファイルには .yml または .yml 拡張子を使用できます。
次の YAML コードサンプルをコピーして、compose.yaml ファイルに貼り付けます。 {TRANSLATOR_KEY} と {TRANSLATOR_ENDPOINT_URI} を Azure portal Translator インスタンスの値からキー値とエンドポイント値に置き換えます。 document translation endpointを使用していることを確認します。
上位レベル名 (azure-ai-translator、azure-ai-language、azure-ai-read) は、指定したパラメーターです。

container_name はオプションのパラメーターで、docker compose に名前を生成させるのではなく、実行時にコンテナーの名前を設定します。

services:
  azure-ai-translator:
    container_name: azure-ai-translator
    image: mcr.microsoft.com/product/azure-cognitive-services/translator/text-translation:latest
    environment:
        - EULA=accept
        - billing={TRANSLATOR_ENDPOINT_URI}
        - apiKey={TRANSLATOR_KEY}
        - AzureAiLanguageHost=http://azure-ai-language:5000
        - AzureAiReadHost=http://azure-ai-read:5000
    ports:
          - "5000:5000"
    azure-ai-language:
      container_name: azure-ai-language
      image:  mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest
      environment:
          - EULA=accept
          - billing={TRANSLATOR_ENDPOINT_URI}
          - apiKey={TRANSLATOR_KEY}
    azure-ai-read:
      container_name: azure-ai-read
      image:  mcr.microsoft.com/azure-cognitive-services/vision/read:latest
      environment:
          - EULA=accept
          - billing={TRANSLATOR_ENDPOINT_URI}
          - apiKey={TRANSLATOR_KEY}

ターミナルを開いて container-environment フォルダーに移動し、次の docker-composeコマンドを使用してコンテナーを起動します。
```
docker compose up
```
コンテナーを停止するには、次のコマンドを使用します。
```
docker compose down
```
ヒント

docker compose コマンド：
- docker compose pause は実行中のコンテナーを一時停止します。
- docker compose unpause {your-container-name} は一時停止したコンテナーを再開します。
- docker compose restartは、以前の変更はすべてそのままに、停止中および実行中のすべてのコンテナーを再起動します。 compose.yaml 構成を変更しても、その変更は docker compose restart コマンドでは更新されません。 compose.yaml ファイルの更新や変更を反映するには、docker compose up コマンドを使用する必要があります。
- docker compose ps -a は、停止中のものも含めて、すべてのコンテナーを一覧表示します。
- docker compose exec により、実行中のコンテナーで lto detach コマンドまたは set 環境変数コマンドを実行できます。
詳細については、Docker CLI リファレンスを参照してください。

次のステップ

テキスト翻訳の詳細

次の方法で共有

コンテナー: テキストを翻訳する

要求 URL

要求パラメーター

必須のパラメーター

オプションパラメーター

要求ヘッダー

要求本文

応答の本文

応答ヘッダー

応答状態コード

コードサンプル: テキストを翻訳する

単一の入力を翻訳する

Azure AI Translator エンドポイントのクエリ (テキスト)

Swagger API を使用してテキストを翻訳する

英語 ↔ ドイツ語

Python を使用してテキストを翻訳する

英語 (フランス語) ↔

C#/.NET コンソールアプリでテキストを翻訳する

英語 ↔ (スペイン語)

複数の文字列を翻訳する

複数の言語に変換する

マークアップを使用してコンテンツを翻訳し、翻訳されたコンテンツを指定する

動的ディクショナリを使用して翻訳する

要求の制限

Docker compose を使用する: Translator とサポートするコンテナー

コンテナーイメージとタグ

アプリケーションを作成する

次のステップ

フィードバック

その他のリソース

次の方法で共有

コンテナー: テキストを翻訳する

要求 URL

要求パラメーター

必須のパラメーター

オプション パラメーター

要求ヘッダー

要求本文

応答の本文

応答ヘッダー

応答状態コード

コード サンプル: テキストを翻訳する

単一の入力を翻訳する

Azure AI Translator エンドポイントのクエリ (テキスト)

Swagger API を使用してテキストを翻訳する

英語 ↔ ドイツ語

Python を使用してテキストを翻訳する

英語 (フランス語) ↔

C#/.NET コンソール アプリでテキストを翻訳する

英語 ↔ (スペイン語)

複数の文字列を翻訳する

複数の言語に変換する

マークアップを使用してコンテンツを翻訳し、翻訳されたコンテンツを指定する

動的ディクショナリを使用して翻訳する

要求の制限

Docker compose を使用する: Translator とサポート するコンテナー

コンテナー イメージとタグ

アプリケーションを作成する

次のステップ

フィードバック

その他のリソース

オプションパラメーター

コードサンプル: テキストを翻訳する

C#/.NET コンソールアプリでテキストを翻訳する

Docker compose を使用する: Translator とサポートするコンテナー

コンテナーイメージとタグ