Translator Text API 3.0: 辞書検索Translator Text API 3.0: Dictionary Lookup

単語や少数の慣用句に対し代替の翻訳を提供します。Provides alternative translations for a word and a small number of idiomatic phrases. 各翻訳には品詞と、逆翻訳のリストが含まれます。Each translation has a part-of-speech and a list of back-translations. 逆翻訳により、ユーザーはコンテキスト内の翻訳を理解することができます。The back-translations enable a user to understand the translation in context. 辞書の例操作では、さらにドリル ダウンすることで、各翻訳ペアの使用例を参照することができます。The Dictionary Example operation allows further drill down to see example uses of each translation pair.

要求 URLRequest URL

POST 要求の送信先は次のとおりです。Send a POST request to:

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

要求パラメーターRequest parameters

クエリ文字列に渡される要求パラメーターを次に示します。Request parameters passed on the query string are:

Query parameter (クエリ パラメーター)Query parameter 説明Description
api-versionapi-version "*必須のパラメーター*"。*Required parameter*.
クライアントによって要求される API のバージョン。Version of the API requested by the client. 値は `3.0` とする必要があります。Value must be `3.0`.
fromfrom "*必須のパラメーター*"。*Required parameter*.
入力テキストの言語を指定します。Specifies the language of the input text. ソース言語は、`dictionary` スコープに含まれている[サポートされている言語](./v3-0-languages.md)のいずれかとする必要があります。The source language must be one of the [supported languages](./v3-0-languages.md) included in the `dictionary` scope.
toto "*必須のパラメーター*"。*Required parameter*.
出力テキストの言語を指定します。Specifies the language of the output text. ターゲット言語は、`dictionary` スコープに含まれている[サポートされている言語](./v3-0-languages.md)のいずれかとする必要があります。The target language must be one of the [supported languages](./v3-0-languages.md) included in the `dictionary` scope.

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

headersHeaders 説明Description
認証ヘッダーAuthentication header(s) "必須の要求ヘッダー" です。Required request header.
認証に使用できるオプションに関するページをご覧ください。See available options for authentication.
Content-TypeContent-Type "*必須の要求ヘッダー*" です。*Required request header*.
ペイロードのコンテンツ タイプを指定します。Specifies the content type of the payload. 次のいずれかの値になります。`application/json`Possible values are: `application/json`.
Content-LengthContent-Length "*必須の要求ヘッダー*" です。*Required request header*.
要求本文の長さです。The length of the request body.
X-ClientTraceIdX-ClientTraceId *省略可能*。*Optional*.
要求を一意に識別する、クライアントで生成された GUID。A client-generated GUID to uniquely identify the request. `ClientTraceId` という名前のクエリ パラメーターを使用してクエリ文字列内にトレース ID を含める場合、このヘッダーは省略できます。You can omit this header if you include the trace ID in the query string using a query parameter named `ClientTraceId`.

要求本文Request body

要求の本文は JSON 配列です。The body of the request is a JSON array. 各配列要素は、Text という名前の文字列プロパティ (検索する用語を表す) を持つ JSON オブジェクトです。Each array element is a JSON object with a string property named Text, which represents the term to lookup.

[
    {"Text":"fly"}
]

次の制限事項が適用されます。The following limitations apply:

  • 配列に含めることができる要素は、最大でも 10 個です。The array can have at most 10 elements.
  • 配列要素のテキスト値は、スペースも含めて 100 文字を超えてはなりません。The text value of an array element cannot exceed 100 characters including spaces.

応答本文Response body

正常な応答は、入力配列内の文字列ごとに 1 つの結果が含まれる JSON 配列となります。A successful response is a JSON array with one result for each string in the input array. 結果オブジェクトには次のプロパティが含まれています。A result object includes the following properties:

  • normalizedSource:ソース用語の正規化された形式を与える文字列。normalizedSource: A string giving the normalized form of the source term. たとえば、要求が "JOHN" の場合、正規化された形式は "john" になります。For example, if the request is "JOHN", the normalized form will be "john". このフィールドの内容は検索例の入力となります。The content of this field becomes the input to lookup examples.

  • displaySource:エンド ユーザー表示に最適な形式でソース用語を与える文字列。displaySource: A string giving the source term in a form best suited for end-user display. たとえば、入力が "JOHN" である場合、表示形式は名前の通常の綴り方を反映し、"John" となります。For example, if the input is "JOHN", the display form will reflect the usual spelling of the name: "John".

  • translations:ソース用語の翻訳のリストです。translations: A list of translations for the source term. リストの各要素は、次のプロパティを持つオブジェクトです。Each element of the list is an object with the following properties:

    • normalizedTarget:ターゲット言語でのこの用語の正規化された形式を与える文字列。normalizedTarget: A string giving the normalized form of this term in the target language. この値を検索例の入力として使用する必要があります。This value should be used as input to lookup examples.

    • displayTarget:用語をターゲット言語の、エンド ユーザー表示に最適な形式で提供する文字列。displayTarget: A string giving the term in the target language and in a form best suited for end-user display. 通常、これは normalizedTarget とは大文字/小文字の設定の点で異なるだけとなります。Generally, this will only differ from the normalizedTarget in terms of capitalization. たとえば、"Juan" のような固有名詞の場合は、normalizedTarget = "juan"displayTarget = "Juan" が使用されます。For example, a proper noun like "Juan" will have normalizedTarget = "juan" and displayTarget = "Juan".

    • posTag:この用語を品詞タグに関連付ける文字列です。posTag: A string associating this term with a part-of-speech tag.

      タグ名Tag name 説明Description
      ADJADJ 形容詞Adjectives
      ADVADV 副詞Adverbs
      CONJCONJ 接続詞Conjunctions
      DETDET 限定詞Determiners
      MODALMODAL 動詞Verbs
      NOUNNOUN 名詞Nouns
      PREPPREP 前置詞Prepositions
      PRONPRON 代名詞Pronouns
      VERBVERB 動詞Verbs
      OTHEROTHER その他Other

      実装上の注意点として、これらのタグは、英語側で品詞タグ付けによって決定されており、ソース/ターゲット ペアごとに最も頻度の高いタグが使用されます。As an implementation note, these tags were determined by part-of-speech tagging the English side, and then taking the most frequent tag for each source/target pair. そのため、ユーザーがスペイン語の単語を頻繁に英語の別の品詞に翻訳する場合、タグは問題になる可能性があります (スペイン語の単語に対して)。So if people frequently translate a Spanish word to a different part-of-speech tag in English, tags may end up being wrong (with respect to the Spanish word).

    • confidence:値は 0.0 から 1.0 の範囲となります。この値は翻訳ペアの "信頼度" (もっと正確に言うならば、"トレーニング データでの確率") を表します。confidence: A value between 0.0 and 1.0 which represents the "confidence" (or perhaps more accurately, "probability in the training data") of that translation pair. 1 個のソース単語の信頼度スコアの合計は、1.0 になる場合とならない場合があります。The sum of confidence scores for one source word may or may not sum to 1.0.

    • prefixWord:翻訳のプレフィックスとして表示する単語を指定する文字列。prefixWord: A string giving the word to display as a prefix of the translation. 現時点では、これは性を区別する限定詞を持つ言語において、名詞の姓を区別する限定詞です。Currently, this is the gendered determiner of nouns, in languages that have gendered determiners. たとえば、スペイン語の単語 "mosca" の接頭詞は "la" です。これは "mosca" がスペイン語の女性名詞だからです。For example, the prefix of the Spanish word "mosca" is "la", since "mosca" is a feminine noun in Spanish. これは翻訳にのみ依存し、ソースには依存しません。This is only dependent on the translation, and not on the source. 接頭詞がない場合は、空の文字列となります。If there is no prefix, it will be the empty string.

    • backTranslations:ターゲットの "逆翻訳" のリストです。backTranslations: A list of "back translations" of the target. たとえば、ターゲットが翻訳されるソースの単語です。For example, source words that the target can translate to. リストには要求されたソース単語が必ず含められます (たとえば、検索されるソース単語が "fly" である場合、"fly" は必ず backTranslations リストに含められます)。The list is guaranteed to contain the source word that was requested (e.g., if the source word being looked up is "fly", then it is guaranteed that "fly" will be in the backTranslations list). ただし、それが先頭に来るという保証はなく、多くの場合先頭にはなりません。However, it is not guaranteed to be in the first position, and often will not be. backTranslations リストの各要素は、次のプロパティで記述されるオブジェクトです。Each element of the backTranslations list is an object described by the following properties:

      • normalizedText:ターゲットの逆翻訳であるソース用語の正規化された形式を与える文字列。normalizedText: A string giving the normalized form of the source term that is a back-translation of the target. この値を検索例の入力として使用する必要があります。This value should be used as input to lookup examples.

      • displayText:ターゲットの逆翻訳であるソース用語を、エンド ユーザー表示に最適な形式で与える文字列。displayText: A string giving the source term that is a back-translation of the target in a form best suited for end-user display.

      • numExamples:この翻訳ペアで利用できる例の数を表す整数。numExamples: An integer representing the number of examples that are available for this translation pair. 実際の例は、検索例の個別の呼び出しによって取得する必要があります。Actual examples must be retrieved with a separate call to lookup examples. この数は主に UX での表示を容易にすることを目的としています。The number is mostly intended to facilitate display in a UX. たとえば、例の数が 0 より大きい場合はユーザー インターフェイスによって逆翻訳へのハイパーリンクが追加され、例が存在しない場合は、逆翻訳がプレーン テキストとして表示されます。For example, a user interface may add a hyperlink to the back-translation if the number of examples is greater than zero and show the back-translation as plain text if there are no examples. 検索例の呼び出しによって返される例の実際の数は numExamples 未満となる場合があります。これは、追加のフィルター処理を適用して "悪い" 例を即時に削除することができるからです。Note that the actual number of examples returned by a call to lookup examples may be less than numExamples, because additional filtering may be applied on the fly to remove "bad" examples.

      • frequencyCount:データ内でのこの翻訳ペアの頻度を表す整数。frequencyCount: An integer representing the frequency of this translation pair in the data. このフィールドの主な目的は、最も頻繁に使用されている用語が最初に表示されるように逆翻訳を並べ替える手段をユーザー インターフェイスに提供することにあります。The main purpose of this field is to provide a user interface with a means to sort back-translations so the most frequent terms are first.

    注意

    検索した用語が辞書に存在しない場合、応答は 200 (OK) になりますが、translations リストは空のリストとなります。If the term being looked-up does not exist in the dictionary, the response is 200 (OK) but the translations list is an empty list.

Examples

この例では、英語の用語 fly についてスペイン語での代替翻訳を検索する方法を示します。This example shows how to lookup alternative translations in Spanish of the English term fly .

curl -X POST "https://api.cognitive.microsofttranslator.com/dictionary/lookup?api-version=3.0&from=en&to=es" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json" -d "[{'Text':'fly'}]"

応答本文 (わかりやすくするために短縮) は次のとおりです。The response body (abbreviated for clarity) is:

[
    {
        "normalizedSource":"fly",
        "displaySource":"fly",
        "translations":[
            {
                "normalizedTarget":"volar",
                "displayTarget":"volar",
                "posTag":"VERB",
                "confidence":0.4081,
                "prefixWord":"",
                "backTranslations":[
                    {"normalizedText":"fly","displayText":"fly","numExamples":15,"frequencyCount":4637},
                    {"normalizedText":"flying","displayText":"flying","numExamples":15,"frequencyCount":1365},
                    {"normalizedText":"blow","displayText":"blow","numExamples":15,"frequencyCount":503},
                    {"normalizedText":"flight","displayText":"flight","numExamples":15,"frequencyCount":135}
                ]
            },
            {
                "normalizedTarget":"mosca",
                "displayTarget":"mosca",
                "posTag":"NOUN",
                "confidence":0.2668,
                "prefixWord":"",
                "backTranslations":[
                    {"normalizedText":"fly","displayText":"fly","numExamples":15,"frequencyCount":1697},
                    {"normalizedText":"flyweight","displayText":"flyweight","numExamples":0,"frequencyCount":48},
                    {"normalizedText":"flies","displayText":"flies","numExamples":9,"frequencyCount":34}
                ]
            },
            //
            // ...list abbreviated for documentation clarity
            //
        ]
    }
]

この例では、検索される用語が有効な辞書ペアに存在しない場合、どうなるかを示します。This example shows what happens when the term being looked up does not exist for the valid dictionary pair.

curl -X POST "https://api.cognitive.microsofttranslator.com/dictionary/lookup?api-version=3.0&from=en&to=es" -H "X-ClientTraceId: 875030C7-5380-40B8-8A03-63DACCF69C11" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json" -d "[{'Text':'fly123456'}]"

辞書内で用語が見つからないため、応答本文には空の translations リストが含まれます。Since the term is not found in the dictionary, the response body includes an empty translations list.

[
    {
        "normalizedSource":"fly123456",
        "displaySource":"fly123456",
        "translations":[]
    }
]