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

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

テキストを翻訳する。

要求 URL

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

POST {Endpoint}/translate?api-version=3.0&&from={from}&to={to}

要求の例

POST https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=es

[
  {
    "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対してクエリを実行できます。
表記変換の言語サポートも参照してください。

オプションパラメーター

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

要求ヘッダー

ヘッダー	説明	条件
認証ヘッダー	認証に使用できるオプションを参照してください。	必要な要求ヘッダー
Content-Type	ペイロードのコンテンツタイプを指定します。指定できる値は `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 個です。
要求に含めるテキスト全体は、スペースも含めて 10,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

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

単一の入力を翻訳する

この例では、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 翻訳エンドポイントのクエリ (テキスト)

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

  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:{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?'}, {'Text':'I am fine, thank you.'}]"

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

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

複数の言語に変換する

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

curl -X POST "http://localhost:{port}/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:{port}/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:{port}/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 の詳細については、こちらを参照してください。

要求の制限

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

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

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

Docker compose を使用する: サポートコンテナーを使用した翻訳

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

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

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

操作	要求クエリ	ドキュメント型	コンテナーのサポート
•テキストの翻訳 • ドキュメント翻訳	`from` 指定。	Office ドキュメント	なし
•テキストの翻訳 • ドキュメント翻訳	`from` 指定されていません。ソース言語を特定するには、言語の自動検出が必要です。	Office ドキュメント	Text analytics:language コンテナー ✔️
•テキストの翻訳 • ドキュメント翻訳	`from` 指定。	スキャンされた PDF ドキュメント	Vision:read コンテナー ✔️
•テキストの翻訳 • ドキュメント翻訳	`from` は指定されていません。ソース言語を判断するために言語の自動検出が必要です。	スキャンされた PDF ドキュメント	Text analytics:language コンテナー ✔️ Vision:read コンテナー ✔️

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

Azure AI サービスのコンテナーイメージは、Microsoft アーティファクトレジストリ カタログにあります。次の表に、テキストおよびドキュメント翻訳の完全修飾イメージの場所を示します。

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

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

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

これは 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 更新されません。このコマンドを使用 docker compose up して、ファイルの更新と変更を反映する compose.yaml 必要があります。
- docker compose ps -a には、停止されているコンテナーを含むすべてのコンテナーが一覧表示されます。
- docker compose execを使用すると、実行中のコンテナーで環境変数をデタッチまたは設定するコマンドを実行できます。
詳細については、Docker CLI リファレンスを参照してください。

次のステップ

テキスト翻訳の詳細