翻译器 3.0：翻译

翻译文本。

请求的 URL

POST将请求发送到：

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

请参阅“虚拟网络支持 翻译器服务”所选网络和专用终结点配置和支持。

请求参数

在查询字符串上传递的请求参数包括：

必需的参数

可选参数

请求标头包括：

请求主体

请求正文是 JSON 数组。 每个数组元素都是一个 JSON 对象，其中包含一 Text个名为字符串属性，该属性表示要转换的字符串。

[
    {"Text":"I would really like to drive your car around the block a few times."}
]

有关字符和数组限制的信息， 请参阅请求限制。

响应体

成功的响应是一个 JSON 数组，输入数组中的每个字符串都有一个结果。 结果对象包含以下属性：

• detectedLanguage：通过以下属性描述检测到的语言的对象：

  • language：一个字符串，表示检测到的语言的代码。

  • score：指示结果置信度的浮点值。 分数介于零和 1 和低分数之间，表示置信度较低。

  仅当请求语言自动检测时，该 detectedLanguage 属性才存在于结果对象中。

• translations：翻译结果数组。 数组的大小与通过 to 查询参数指定的目标语言数匹配。 数组中的每个元素包括：

  • to：表示目标语言的语言代码的字符串。

  • text：一个字符串，提供翻译的文本。

  • transliteration：一个对象，该对象在参数指定的 toScript 脚本中提供翻译的文本。

    • script：指定目标脚本的字符串。

    • text：一个字符串，用于在目标脚本中提供翻译的文本。

    如果未进行音译，则不包括该 transliteration 对象。

    • alignment：具有名为 proj单个字符串属性的对象，该属性将输入文本映射到翻译的文本。 仅当请求参数 includeAlignment 为 true时，才提供对齐信息。 对齐方式作为以下格式的字符串值返回： [[SourceTextStartIndex]:[SourceTextEndIndex]–[TgtTextStartIndex]:[TgtTextEndIndex]] 冒号分隔开始索引和结束索引，短划线分隔语言，空格分隔单词。 一个单词可以与另一种语言的零、一个或多个单词对齐，对齐的单词可以是不连续的。 如果没有可用的对齐信息，则对齐元素为空。 有关示例和限制，请参阅 “获取对齐信息 ”。

  • sentLen：一个对象，返回输入和输出文本中的句子边界。

    • srcSentLen：一个整数数组，表示输入文本中句子的长度。 数组的长度是句子数，值是每个句子的长度。

    • transSentLen：一个整数数组，表示翻译文本中句子的长度。 数组的长度是句子数，值是每个句子的长度。

    仅当请求参数 为 时，才会包含句子边界。

• sourceText：具有名为 text单个字符串属性的对象，该属性在源语言的默认脚本中提供输入文本。 sourceText 仅当输入以不是语言的常用脚本表示的脚本中时，属性才存在。 例如，如果输入是用拉丁语脚本编写的阿拉伯语，那么 sourceText.text 将相同的阿拉伯语文本转换为阿拉伯脚本.

示例部分提供了 JSON 响应 示例 。

响应标头

响应状态代码

以下是请求返回的可能 HTTP 状态代码。

如果发生错误，请求将返回 JSON 错误响应。 错误代码是一个 6 位数的数字，它组合了 3 位 HTTP 状态代码，后跟一个 3 位数字，以进一步对错误进行分类。 可以在 v3 翻译器参考页上找到常见的错误代码。

例子

转换单个输入

此示例演示如何将单个句子从英语翻译为简体中文。

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 数组包含一个元素，该元素提供输入中单个文本片段的翻译。

使用语言自动检测翻译单个输入

此示例演示如何将单个句子从英语翻译为简体中文。 请求未指定输入语言。 改用源语言的自动检测。

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"}
        ]
    }
]

翻译为多种语言

此示例演示如何在一个请求中将同一输入翻译为多种语言。

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"}
        ]
    }
]

处理亵渎行为

通常，翻译器服务保留翻译源中存在的亵渎内容。 猥亵程度和使字词不雅不同文化的上下文程度，因此目标语言中的亵渎程度可以放大或减少。

如果要避免在翻译中获取不雅内容，无论源文本中是否存在猥亵内容，都可以使用不雅内容筛选选项。 该选项允许你选择是要看到已删除的不雅内容，是否标记有适当的标记（提供添加自己的后处理选项），或者不采取任何作。 接受的 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 元素中的内容不会翻译，而第二 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”。

换句话说，冒号分隔开始索引和结束索引，短划线分隔语言，空格分隔单词。 一个单词可以与另一种语言的零、一个或多个单词对齐，对齐的单词可以是不连续的。 如果没有可用的对齐信息，则 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）映射到翻译文本中的前两个字符（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>

例如，假设英语句子“单词单词是字典词条”。若要在翻译中保留单词 字形 ，请发送请求：

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=html方式相同textType=text。 此功能应谨慎使用。 自定义翻译的适当且更好的方法是使用自定义翻译。 自定义翻译器充分利用上下文和统计概率。 如果可以创建在上下文中显示工作或短语的训练数据，则获得更好的结果。 了解有关自定义翻译器的详细信息。

后续步骤