文本翻译 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.translator.azure.cn/dictionary/lookup?api-version=3.0

请求参数Request parameters

查询字符串上传递的请求参数如下:Request parameters passed on the query string are:

查询参数Query parameter 说明Description
api-versionapi-version 必需参数。Required parameter.
客户端所请求的 API 的版本。Version of the API requested by the client. 值必须是 3.0Value must be 3.0.
fromfrom 必需参数。Required parameter.
指定输入文本的语言。Specifies the language of the input text. 源语言必须是 dictionary 范围中包含的支持的语言之一。The source language must be one of the supported languages included in the dictionary scope.
toto 必需参数。Required parameter.
指定输出文本的语言。Specifies the language of the output text. 目标语言必须是 dictionary 范围中包含的支持的语言之一。The target language must be one of the supported languages included in the dictionary scope.

请求标头包括:Request headers include:

标头Headers 说明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/jsonPossible 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. 每个数组元素都是一个 JSON 对象,具有一个名为 Text 的字符串属性,该属性表示要查找的字词。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

成功的响应是一个 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.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. 例如,如果示例数大于零,则用户界面可以添加回译的超链接;如果没有任何示例,则以纯文本形式显示回译。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,因为可能对“fly”应用了其他筛选,以删除“错误的”示例。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.translator.azure.cn/dictionary/lookup?api-version=3.0&from=en&to=es" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Ocp-Apim-Subscription-Region: your-region" -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.translator.azure.cn/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 "Ocp-Apim-Subscription-Region: your-region" -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":[]
    }
]