Foundry Tools 3.0 の Azure Translator: Translate

テキストを翻訳します。

リクエストURL

次の POST 要求を送信します。

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

Translator で選択したネットワークとプライベート エンドポイントの構成とサポートに対する仮想ネットワークのサポートを参照してください。

要求パラメーター

クエリ文字列で渡される要求パラメーターは次のとおりです。

必須のパラメーター

省略可能なパラメーター

要求ヘッダーには次のものが含まれます。

リクエストの本文

要求の本文は 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という名前の単一の文字列プロパティを持つオブジェクト。入力テキストを翻訳されたテキストにマップします。 アラインメント情報は、要求パラメーター includeAlignment が trueされている場合にのみ提供されます。 配置は、次の形式の文字列値として返されます: [[SourceTextStartIndex]:[SourceTextEndIndex]–[TgtTextStartIndex]:[TgtTextEndIndex]]。 コロンは開始インデックスと終了インデックスを区切り、ダッシュは言語を区切り、スペースは単語を区切ります。 一方の単語は、他の言語では 0、1、または複数の単語に配置でき、アラインされた単語は連続しない場合があります。 配置情報が使用できない場合、配置要素は空になります。 例と制限については、「 アライメント情報を取得 する」を参照してください。

  • sentLen: 入力テキストと出力テキスト内の文の境界を返すオブジェクト。

    • srcSentLen: 入力テキスト内の文の長さを表す整数配列。 配列の長さは文の数であり、値は各文の長さです。

    • transSentLen: 翻訳されたテキスト内の文の長さを表す整数配列。 配列の長さは文の数であり、値は各文の長さです。

    文の境界は、要求パラメーター includeSentenceLength が trueされている場合にのみ含まれます。

• sourceText: textという名前の単一の文字列プロパティを持つオブジェクト。ソース言語の既定のスクリプトで入力テキストを指定します。 sourceText プロパティは、言語の通常のスクリプトではないスクリプトで入力が表現されている場合にのみ存在します。 たとえば、入力がラテン文字で記述されたアラビア語の場合、 sourceText.text は同じアラビア語のテキストをアラブ文字に変換します.

JSON 応答の例は、 例 セクションで示されています。

応答ヘッダー

応答ステータスコード

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

エラーが発生した場合、要求は JSON エラー応答を返します。 エラー コードは、3 桁の HTTP 状態コードと 3 桁の数字を組み合わせた 6 桁の数字で、さらにエラーを分類します。 一般的なエラー コードは 、v3 Translator のリファレンス ページにあります。

例示

1 つの入力を変換する

この例では、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 つのテキストの翻訳が提供されます。

言語自動検出を使用して 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 (既定値) です。

上記の例では、 <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 で始まります。つまり、ソース テキスト (The) の最初の 3 文字は、翻訳されたテキスト (La) の最初の 2 文字にマップされます。

制限事項

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

• 配置は、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>

たとえば、英語の文 "単語の単語は辞書のエントリです" とします。翻訳で 単語の単語 を保持するには、要求を送信します。

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 の詳細については、こちらを参照してください。

次のステップ