Translator 3.0:Translate

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

テキストを翻訳します。

要求 URL

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

https://api.cognitive.microsofttranslator.com/translate?api-version=3.0

Translator サービスの選択したネットワークとプライベートエンドポイントの構成とサポートについては Virtual ネットワークサポート を参照してください。

要求パラメーター

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

必須のパラメーター

Query parameter (クエリパラメーター) 説明

api-version "必須のパラメーター"。
クライアントによって要求される API のバージョン。値は 3.0 とする必要があります。

to "必須のパラメーター"。
出力テキストの言語を指定します。ターゲット言語は、translation スコープに含まれているサポートされている言語のいずれかとする必要があります。たとえば、ドイツ語に翻訳するには to=de を使用します。
クエリ文字列内でパラメーターを繰り返すことにより、同時に複数の言語に翻訳することができます。たとえば、ドイツ語とイタリア語に翻訳するには、to=de&to=it を使用します。

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

省略可能なパラメーター

Query parameter (クエリパラメーター)	説明
from	"省略可能なパラメーター"。入力テキストの言語を指定します。 `translation` スコープを使用してサポートされている言語を検索することにより、翻訳することができるソース言語を確認します。 `from` パラメーターが指定されていない場合は、自動言語検出が適用されてソース言語が特定されます。動的ディクショナリ機能を使用する場合は、自動検出ではなく、`from` パラメーターを使用する必要があります。注: 動的ディクショナリ機能では、大文字と小文字が区別されます。
textType	"省略可能なパラメーター"。翻訳するテキストがプレーンテキストか、それとも HTML テキストかを定義します。 HTML の場合は、適切な形式の完全な要素である必要があります。指定できる値は `plain` (既定値) または `html` です。
category	"省略可能なパラメーター"。翻訳のカテゴリ (ドメイン) を指定する文字列。このパラメーターは、Custom Translator でビルドしたカスタマイズされたシステムから翻訳を取得するために使用します。デプロイされたカスタマイズされたシステムを使用するには、Custom Translator project details から category パラメーターにカテゴリ ID を追加します。既定値は `general` です。
profanityAction	"省略可能なパラメーター"。翻訳での不適切な表現の処理方法を指定します。使用できる値は、 `NoAction` (既定値)、 `Marked`、または `Deleted`です。不適切な表現の処理方法を理解するには、不適切な表現の処理に関するセクションを参照してください。
profanityMarker	"省略可能なパラメーター"。翻訳での不適切な表現のマーキング方法を指定します。指定できる値は `Asterisk` (既定値) または `Tag` です。不適切な表現の処理方法を理解するには、不適切な表現の処理に関するセクションを参照してください。
includeAlignment	"省略可能なパラメーター"。ソーステキストから翻訳済みテキストへのアライメントプロジェクションを含めるかどうかを指定します。指定できる値は `true` または `false` (既定値) です。
includeSentenceLength	"省略可能なパラメーター"。入力テキストと翻訳済みテキストに対して文の境界を含めるかどうかを指定します。指定できる値は `true` または `false` (既定値) です。
suggestedFrom	"省略可能なパラメーター"。入力テキストの言語を識別できない場合のフォールバック言語を指定します。 `from` パラメーターが省略されている場合は、言語自動検出が適用されます。検出に失敗した場合は、`suggestedFrom` 言語と見なされます。
fromScript	"省略可能なパラメーター"。入力テキストのスクリプトを指定します。
toScript	"省略可能なパラメーター"。翻訳済みテキストのスクリプトを指定します。
allowFallback	"省略可能なパラメーター"。カスタムシステムが存在しない場合に、サービスが一般的なシステムに切り替えられるよう指定します。指定できる値は `true` (既定値) または `false` です。 `allowFallback=false` は、要求によって指定された `category` 向けにトレーニングされているシステムのみを翻訳で使用することを指定します。言語 X から言語 Y への翻訳で、中心言語 E を経由するチェーン処理が必要な場合、チェーン内のすべてのシステム (X → E および E → Y) はカスタムであり、同じカテゴリを持っている必要があります。特定のカテゴリを持つシステムが見つからない場合、要求は 400 状態コードを返します。 `allowFallback=true` はカスタムシステムが存在しない場合に、サービスが一般的なシステムに切り替えられるよう指定します。

要求ヘッダーには次のものがあります。

ヘッダー	説明
認証ヘッダー	"必須の要求ヘッダー" です。認証に使用できるオプションに関するページをご覧ください。
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."}
]

文字と配列の制限については、参照 Request の制限。

応答の本文

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

detectedLanguage:次のプロパティによって、検出された言語を説明するオブジェクトです。
- language:検出された言語のコードを表す文字列です。
- score:結果内の信頼度を示す浮動小数点値です。スコアは 0 から 1 の範囲であり、低いスコアは低い信頼度を示します。
detectedLanguage プロパティは、言語自動検出が要求された場合に限り、結果オブジェクト内に存在します。
translations:翻訳結果の配列です。配列のサイズは、to クエリパラメーターを通して指定されたターゲット言語の数に一致します。配列内の各要素は次のとおりです。
- to:ターゲット言語の言語コードを表す文字列です。
- text:翻訳済みテキストを提供する文字列です。
- transliteration:toScript パラメーターによって指定されたスクリプトで、翻訳済みテキストを提供するオブジェクトです。
  - script:ターゲットスクリプトを指定する文字列です。
  - text:ターゲットスクリプトで翻訳済みテキストを提供する文字列です。
  翻訳が実行されない場合、transliteration オブジェクトは含まれません。
  - alignment:proj という名前の 1 つの文字列プロパティを持つオブジェクトです。これにより、入力テキストが翻訳済みテキストにマッピングされます。アライメント情報は、要求パラメーター includeAlignment が true である場合に提供されるだけとなります。アライメントは、次の形式の文字列値として返されます: [[SourceTextStartIndex]:[SourceTextEndIndex]–[TgtTextStartIndex]:[TgtTextEndIndex]]。コロンによって開始および終了インデックスが区切られ、ダッシュによって言語が区切られ、スペースによって単語が区切られます。一方の単語は、他の言語では 0、1、または複数の単語に配置でき、アラインされた単語は連続しない場合があります。アライメント情報を使用できない場合は、alignment 要素が空です。例と制限事項については、「アライメント情報を取得する」を参照してください。
- sentLen:入力テキストと出力テキスト内で文の境界を返すオブジェクトです。
  - srcSentLen:入力テキスト内の文の長さを表す整数配列です。配列の長さは文の数であり、値は各文の長さです。
  - transSentLen: 翻訳済みテキスト内の文の長さを表す整数配列です。配列の長さは文の数であり、値は各文の長さです。
  文の境界は、要求パラメーター includeSentenceLength が true の場合にのみ含められます。
sourceText:text という名前の 1 つの文字列プロパティを持つオブジェクトです。これにより、ソース言語の既定のスクリプトで入力テキストが提供されます。 sourceText プロパティは、言語の通常のスクリプトではないスクリプトで入力が表されている場合にのみ存在します。たとえば、入力がラテン文字で記述されたアラビア語の場合、 sourceText.text は同じアラビア語のテキストをアラブ文字に変換します.

JSON 応答の例については、「例」セクションを参照してください。

応答ヘッダー

ヘッダー	説明
X-requestid	トラブルシューティングの目的で使用される要求を識別するためにサービスによって生成される値。
X-mt-system	翻訳が必要な各ターゲット言語への翻訳に使用されたシステムの種類を示します。値は、文字列のコンマ区切りの一覧です。各文字列は型を示しています。 Custom - 要求にはカスタムシステムが含まれ、翻訳中に少なくとも 1 つのカスタムシステムが使用されています。 Team - その他のすべての要求
X-metered-usage	翻訳ジョブ要求の消費量 (ユーザーが課金される文字数) を指定します。たとえば、"Hello" という単語が英語 (en) からフランス語 (fr) に翻訳されている場合、このフィールドは値 `5` を返します。

応答状態コード

要求によって返される可能性のある HTTP 状態コードを次に示します。

status code	説明
200	正常終了しました。
400	クエリパラメーターの 1 つが欠落しているか無効です。再試行する前に要求パラメーターを修正してください。
401	要求を認証できませんでした。資格情報が指定され、有効であることを確認してください。
403	要求は承認されません。詳細なエラーメッセージを確認してください。多くの場合、この状態コードは、試用版サブスクリプションで提供されるすべての無料翻訳を使用したことを示します。
408	リソースが見つからないため、要求を処理できませんでした。詳細なエラーメッセージを確認してください。要求にカスタムカテゴリが含まれている場合、この状態コードは、多くの場合、カスタム翻訳システムがまだ要求を処理できる状態ではないことを示します。要求は、待機期間 (たとえば、1 分) 後に再試行する必要があります。
429	クライアントが要求の制限を超えたため、サーバーは要求を拒否しました。
500	予期しないエラーが発生しました。エラーが解決しない場合は、エラー発生の日時、応答ヘッダー X-RequestID の要求識別子、要求ヘッダー X-ClientTraceID のクライアント識別子を添えてご報告ください。
503	サーバーが一時的に使用できません。要求をやり直してください。エラーが解決しない場合は、エラー発生の日時、応答ヘッダー X-RequestID の要求識別子、要求ヘッダー X-ClientTraceID のクライアント識別子を添えてご報告ください。

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

例

単一の入力を翻訳する

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

curl -X POST "https://api.cognitive.microsofttranslator.com/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 つの要素が含まれており、これによって入力内の単一のテキストの翻訳が提供されます。

言語自動検出を使用して単一の入力を翻訳する

この例では、1 つの文を英語から簡体中国語に翻訳する方法を示します。要求には入力言語が指定されていません。代わりに、ソース言語の自動検出が使用されます。

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&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?'}]"

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

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

応答は、前の例での応答に似ています。言語自動検出が要求されたので、応答には入力テキストで検出された言語に関する情報も含まれています。言語自動検出は、入力テキストが長いほど、うまく機能します。

音訳を使用して翻訳する

音訳を追加して、前の例を拡張してみましょう。次の要求では、ラテン文字で記述する、中国語の翻訳が求められています。

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=zh-Hans&toScript=Latn" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

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

[
    {
        "detectedLanguage":{"language":"en","score":1.0},
        "translations":[
            {
                "text":"你好, 你叫什么名字？",
                "transliteration":{"script":"Latn", "text":"nǐ hǎo , nǐ jiào shén me míng zì ？"},
                "to":"zh-Hans"
            }
        ]
    }
]

翻訳結果には transliteration プロパティが含まれるようになります。これにより、ラテン文字を使用して翻訳されたテキストが提供されます。

複数のテキストを変換する

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

curl -X POST "https://api.cognitive.microsofttranslator.com/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 "https://api.cognitive.microsofttranslator.com/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"}
        ]
    }
]

不適切な表現を処理する

通常、Translator サービスでは、ソースに存在する不適切な表現は翻訳でも保たれます。不適切な表現の程度と単語を不適切にするコンテキストは文化によって異なり、その結果、ターゲット言語の不適切な表現の程度を増幅または減少させることができます。

ソーステキスト内での不適切な表現の有無に関係なく、翻訳で不適切な表現が生じるのを防ぐには、不適切な表現のフィルター処理オプションを使用できます。このオプションを使用すると、不適切な表現を削除する、適切なタグでマークする (独自の後処理を追加するためのオプションが用意されています)、または何も操作を行わない、のいずれかを選択することができます。 ProfanityActionの許容される値は、Deleted、Marked、およびNoAction (既定値) です。

受け入れられた ProfanityAction 値	ProfanityMarker 値	アクション	例: ソース - スペイン語	例:ターゲット - 英語
NoAction		既定値。オプションを設定しない場合と同じです。不適切な表現はソースからターゲットに渡されます。	`Que coche de`<insert-profane-word>	What a <insert-profane-word> car
Marked	Asterisk	不適切な単語をアスタリスクに置き換えます (既定)。	`Que coche de`<insert-profane-word>	What a *** car
Marked	タグ	不適切な単語は XML タグ <profanity>...</profanity> で囲まれます。	`Que coche de`<insert-profane-word>	What a <profanity><insert-profane-word></profanity> car
Deleted		不適切な単語は、置換されずに出力から削除されます。	`Que coche de`<insert-profane-word>	What a car

上記の例では、<insert-profane-word> は不適切な単語のプレースホルダーです。

次に例を示します。

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de&profanityAction=Marked" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'This is an <expletive> good idea.'}]"

この要求では次が返されます。

[
    {
        "translations":[
            {"text":"Das ist eine *** gute Idee.","to":"de"}
        ]
    }
]

次の場合と比較します。

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de&profanityAction=Marked&profanityMarker=Tag" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'This is an <expletive> good idea.'}]"

その最後の要求では次が返されます。

[
    {
        "translations":[
            {"text":"Das ist eine <profanity>verdammt</profanity> gute Idee.","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 "https://api.cognitive.microsofttranslator.com/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"}
        ]
    }
]

アラインメント情報を取得する

アライメントは、ソースのすべての単語について、次の形式の文字列値として返されます。各単語の情報は、中国語のようなスペースで区切られない言語 (書記法) の場合を含め、スペースで区切られます。

[[SourceTextStartIndex]\:[SourceTextEndIndex]–[TgtTextStartIndex]\:[TgtTextEndIndex]] *

アラインメント文字列は、たとえば、"0:0-7:10 1:2-11:20 3:4-0:3 3:4-4:6 5:5-21:21" のようになります。

言い換えると、コロンによって開始および終了インデックスが区切られ、ダッシュによって言語が区切られ、スペースによって単語が区切られます。一方の単語は、他の言語では 0、1、または複数の単語に配置でき、アラインされた単語は連続しない場合があります。アライメント情報を使用できない場合は、alignment 要素が空です。このメソッドは、その場合にエラーを返しません。

アライメント情報を受信するには、クエリ文字列上で includeAlignment=true を指定します。

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=fr&includeAlignment=true" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'The answer lies in machine translation.'}]"

応答は次のとおりです。

[
    {
        "translations":[
            {
                "text":"La réponse se trouve dans la traduction automatique.",
                "to":"fr",
                "alignment":{"proj":"0:2-0:1 4:9-3:9 11:14-11:19 16:17-21:24 19:25-40:50 27:37-29:38 38:38-51:51"}
            }
        ]
    }
]

アライメント情報は 0:2-0:1 で始まっています。これは、ソーステキスト内の最初の 3 文字 (The) が翻訳済みテキスト内の最初の 2 文字 (La) にマッピングされていることを意味します。

制限事項

アラインメント情報の取得は、潜在的なフレーズマッピングを使用して研究と経験をプロトタイプ化するために有効にした実験的な機能です。アラインメントがサポートされない、注意が必要ないくつかの制限事項を次に示します。

HTML 形式のテキスト、つまり textType=html の場合、アラインメントは使用できません
アライメントは、言語ペアのサブセットに対してのみ返されます。
- 中国語 (繁体字)、広東語 (繁体字)、セルビア語 (キリル) を除く他の言語と英語の間
- 日本語から韓国語、または韓国語から日本語
- 日本語から簡体字中国語、簡体字中国語から日本語
- 簡体字中国語から繁体字中国語、繁体字中国語から簡体字中国語まで
その文章があらかじめ用意された翻訳である場合、アラインメントは行いません。翻訳の例として、 This is a test、 I love you、その他の高頻度の文があります。
こちらに記述されているような、翻訳を禁止するアプローチのどれかを適用する場合、アラインメントは使用できません

文の境界を取得する

ソーステキストと翻訳済みテキストの文の長さに関する情報を受信するには、クエリ文字列上で includeSentenceLength=true を指定します。

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=fr&includeSentenceLength=true" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'The answer lies in machine translation. The best machine translation technology cannot always provide translations tailored to a site or users like a human. Simply copy and paste a code snippet anywhere.'}]"

応答は次のとおりです。

[
    {
        "translations":[
            {
                "text":"La réponse se trouve dans la traduction automatique. La meilleure technologie de traduction automatique ne peut pas toujours fournir des traductions adaptées à un site ou des utilisateurs comme un être humain. Il suffit de copier et coller un extrait de code n'importe où.",
                "to":"fr",
                "sentLen":{"srcSentLen":[40,117,46],"transSentLen":[53,157,62]}
            }
        ]
    }
]

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

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

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

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

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

curl -X POST "https://api.cognitive.microsofttranslator.com/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\">wordomatic</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 の詳細については、こちらを参照してください。

次の手順

Translator を試してみるためのクイックスタート

次の方法で共有

Translator 3.0:Translate

要求 URL

要求パラメーター

必須のパラメーター

省略可能なパラメーター

要求本文

応答の本文

応答ヘッダー

応答状態コード

例

単一の入力を翻訳する

言語自動検出を使用して単一の入力を翻訳する

音訳を使用して翻訳する

複数のテキストを変換する

複数の言語に変換する

不適切な表現を処理する

マークアップを含むコンテンツを翻訳する

アラインメント情報を取得する

制限事項

文の境界を取得する

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

次の手順

フィードバック

その他のリソース