翻译器 Translate 方法 - Azure AI services

link之家
链接快照平台
输入网页链接，自动生成快照
标签化管理网页链接
请求 URL

将 POST 请求发送到：
https://api.cognitive.microsofttranslator.com/translate?api-version=3.0
查询字符串上传递的请求参数如下：
必需的参数
可选参数。  
指定输入文本的语言。 可以使用 translation 范围来查找支持的语言，了解哪些语言可以翻译。 如果未指定 from 参数，则会应用自动语言检测来确定源语言。  
  
使用动态字典功能时，必须使用 from 参数而不是自动检测。 注意：动态字典功能区分大小写。
textType
可选参数。  
定义要翻译的文本是纯文本还是 HTML 文本。 HTML 必须是格式正确的完整元素。 可能的值为 plain（默认）html。
category
可选参数。  
一个字符串，指定翻译的类别（领域）。 此参数用于从一个使用自定义翻译工具构建的自定义系统获取翻译。 将自定义翻译器项目详细信息中的类别 ID 添加到此参数，以便使用已部署的自定义系统。 默认值为 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 指定当自定义系统不存在时允许服务回退到一个常规系统。
请求标头包括：
请求的正文是一个 JSON 数组。 每个数组元素都是一个 JSON 对象，具有一个名为 Text 的字符串属性，该属性表示要翻译的字符串。
    {"Text":"I would really like to drive your car around the block a few times."}
有关字符和数组限制的信息，请参阅请求限制。
成功的响应是一个 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 个或多个单词比对，而比对的词可能是不连续的。 当没有可用的比对信息时，Alignment 元素会为空。 请参阅获取比对信息，了解示例和限制。
srcSentLen：一个整数数组，表示输入文本中句子的长度。 数组的长度是句子的数量，而各个值是每个句子的长度。
transSentLen：一个整数数组，表示翻译文本中句子的长度。 数组的长度是句子的数量，而各个值是每个句子的长度。
只有在请求参数 includeSentenceLength 为 true 时，才包括句子边界。
sourceText：一个对象，包含的名为 text 的单个字符串属性在源语言的默认脚本中提供输入文本。 sourceText 属性存在的前提是，表述输入时采用的脚本不是该语言的通用脚本。 例如，如果输入是采用拉丁语脚本编写的阿拉伯语，则 sourceText.text 就是转换为阿拉伯脚本的同一阿拉伯文本。
示例部分提供了 JSON 响应的示例。
X-mt-system
请求翻译时，对于每种“目标”语言，指定用于翻译的系统类型。 此值是以逗号分隔的字符串列表。 每个字符串指示一个类型：

* 自定义 - 请求包括一个自定义系统，并且在翻译期间至少使用了一个自定义系统。
* 团队 - 所有其他请求
X-metered-usage
指定翻译作业请求的消耗量（向用户收费的字符数）。 例如，如果单词“Hello”从英语 (en) 翻译为法语 (fr) ，则此字段将返回值“5”。
响应状态代码
下面是请求可能返回的 HTTP 状态代码。
无法满足请求，因为缺少资源。 请检查详细错误消息。 当请求包含自定义类别时，此状态代码通常表示自定义翻译系统尚不可用于为请求提供服务。 应在等待一段时间（例如 1 分钟）后重试此请求。
由于客户端已超出请求限制，服务器拒绝了请求。
发生了意外错误。 如果该错误持续出现，请报告发生故障的日期和时间、响应标头“X-RequestId”中的请求标识符，以及请求标头“X-ClientTraceId”中的客户端标识符。
服务器暂不可用。 重试请求。 如果该错误持续出现，请报告发生故障的日期和时间、响应标头“X-RequestId”中的请求标识符，以及请求标头“X-ClientTraceId”中的客户端标识符。
如果发生错误，请求也将返回 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（默认）。
ProfanityAction
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”。
换而言之，冒号分隔开始和结束索引，连字符分隔语言，空格分隔词。 一个单词可能与另一种语言中的 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) 映射到翻译文本中的头两个字符 (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>
例如，假设英语句子为“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，此动态字典功能都以相同的方式工作。 应尽量少使用此功能。 对翻译进行自定义时，一个合适且要好得多的方法是使用自定义翻译工具。 自定义翻译工具能够充分利用上下文和统计概率。 如果可以创建在上下文中显示工作或短语的训练数据，则会得到更好的结果。 详细了解自定义翻译工具。
试用翻译器快速入门