Translator 3.0:Translate
テキストを翻訳します。
要求 URL
POST 要求の送信先は次のとおりです。
https://api.cognitive.microsofttranslator.com/translate?api-version=3.0
Translator で選択されているネットワークとプライベート エンドポイントの構成とサポートについては、「仮想ネットワークのサポート」を "参照してください"。
要求パラメーター
クエリ文字列に渡される要求パラメーターを次に示します。
必須のパラメーター
| 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 翻訳 プロジェクトの詳細のカテゴリ ID を category パラメーターに追加します。 既定値は 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."}
]
文字と配列の制限に関する詳細については、要求の制限に関する記事を "参照" してください。
応答本文
正常な応答は、入力配列内の文字列ごとに 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 | アクション |
|---|---|
NoAction |
NoAction は既定の動作です。 不適切な表現はソースからターゲットに渡されます。 ソースの例 (日本語):彼はジャッカスです。 翻訳の例 (英語): He's a jack---. |
Deleted |
不適切な単語は、置換されずに出力から削除されます。 ソースの例 (日本語):彼はジャッカスです。 翻訳の例 (英語): He's a** |
Marked |
出力内でマークされた単語がマーカーに置き換えられます。 マーカーは ProfanityMarker パラメーターによって異なります。 の場合 ProfanityMarker=Asterisk、不適切な単語は次のように ***置き換えられます。ソースの例 (日本語):彼はジャッカスです。 翻訳の例 (英語): He's a\\\*. の場合 ProfanityMarker=Tag、不適切な単語は XML タグ <の不適切な表現> と </profanity> で囲まれています。ソースの例 (日本語):彼はジャッカスです。 翻訳の例 (英語): He's a <profanity>jack---</profanity>. |
次に例を示します。
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 testI 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 の詳細については、こちらを参照してください。