你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
翻译器 3.0：Translate
翻译文本。
请求 URL
将 POST 请求发送到：
https://api.cognitive.microsofttranslator.com/translate?api-version=3.0
请参阅虚拟网络支持，以了解翻译器服务选择的网络和专用终结点配置与支持。
请求参数
查询字符串上传递的请求参数如下：
必需的参数
| 查询参数 | 说明 |
|---|---|
| api-version | 必需参数。 客户端所请求的 API 的版本。 值必须是 3.0。 |
| to | 必需参数。 指定输出文本的语言。 目标语言必须是 translation 范围中包含的支持的语言之一。 例如，若要翻译为德语，请使用 to=de。 可以在查询字符串中重复使用此参数，这样就可以同时翻译为多种语言。 例如，若要翻译为德语和意大利语，请使用 to=de&to=it。 |
可选参数
| 查询参数 | 说明 |
|---|---|
| from | 可选参数。 指定输入文本的语言。 可以使用 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 and E → Y）需要进行自定义并具有相同的类别。 如果未通过特定类别找到任何系统，此请求会返回 400 状态代码。 allowFallback=true 指定当自定义系统不存在时允许服务回退到一个常规系统。 |
请求标头包括：
| 头文件 | 说明 |
|---|---|
| 身份验证标头 | 必需的请求标头。 请参阅用于身份验证的可用选项。 |
| Content-Type | 必需的请求标头。 指定有效负载的内容类型。 接受的值为： application/json; charset=UTF-8。 |
| Content-Length | 可选。 请求正文的长度。 |
| X-ClientTraceId | 可选。 客户端生成的 GUID，用于唯一标识请求。 如果在查询字符串中使用名为 ClientTraceId 的查询参数包括了跟踪 ID，则可以省略此标头。 |
请求正文
请求的正文是一个 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 个或多个单词比对，而比对的词可能是不连续的。 当没有可用的比对信息时，比对元素将为空。 请参阅获取比对信息，了解示例和限制。
sentLen：一个对象，返回输入和输出文本中的句子边界。srcSentLen：一个整数数组，表示输入文本中句子的长度。 数组的长度是句子的数量，而各个值是每个句子的长度。transSentLen：一个整数数组，表示翻译文本中句子的长度。 数组的长度是句子的数量，而各个值是每个句子的长度。
只有在请求参数
includeSentenceLength为true时，才包括句子边界。
sourceText：一个对象，包含的名为text的单个字符串属性在源语言的默认脚本中提供输入文本。sourceText属性存在的前提是，表述输入时采用的脚本不是该语言的通用脚本。 例如，如果输入是采用拉丁语脚本编写的阿拉伯语，则sourceText.text就是转换为阿拉伯脚本的同一阿拉伯文本.
示例部分提供了 JSON 响应的示例。
响应标头
| 头文件 | 说明 |
|---|---|
| X-requestid | 服务生成的值，用于标识请求并用于故障排除目的。 |
| X-mt-system | 请求翻译时，对于每种“目标”语言，指定用于翻译的系统类型。 此值是以逗号分隔的字符串列表。 每个字符串表示一个类型： 自定义 - 请求包括一个自定义系统，并且在翻译过程中至少使用了一个自定义系统。 团队 - 所有其他请求 |
| X-metered-usage | 指定翻译作业请求的消耗量（对用户收费的字符数）。 例如，如果将单词“Hello”从英语 (en) 翻译为法语 (fr)，则此字段会返回值 5。 |
响应状态代码
下面是请求可能返回的 HTTP 状态代码。
| 状态代码 | 说明 |
|---|---|
| 200 | 成功。 |
| 400 | 查询参数之一缺失或无效。 请更正请求参数，然后重试。 |
| 401 | 无法对请求进行身份验证。 请确保凭据已指定且有效。 |
| 403 | 请求未授权。 请检查详细错误消息。 此状态代码通常表示你已使用试用订阅提供的所有免费翻译。 |
| 408 | 无法满足请求，因为缺少资源。 请检查详细错误消息。 当请求包含自定义类别时，此状态代码通常表示自定义翻译系统尚不可用于为请求提供服务。 应在等待一段时间（例如 1 分钟）后重试此请求。 |
| 429 | 由于客户端已超出请求限制，因此服务器拒绝了请求。 |
| 500 | 发生了意外错误。 如果该错误持续出现，请报告发生故障的日期和时间、响应标头“X-RequestId”中的请求标识符，以及请求标头“X-ClientTraceId”中的客户端标识符。 |
| 503 | 服务器暂不可用。 重试请求。 如果该错误持续出现，请报告发生故障的日期和时间、响应标头“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（默认值）。
| Accepted ProfanityAction 值 | ProfanityMarker 值 | 操作 | 示例：源 - 西班牙语 | 示例：目标 - 英语 |
|---|---|---|---|---|
| NoAction | 默认。 与不设置此选项等效。 不雅内容从源传递到目标。 | Que coche de<insert-profane-word> |
多么 <insert-profane-word> 的汽车 | |
| Marked | 星号 | 星号可替换不雅词语（默认值）。 | Que coche de<insert-profane-word> |
多么 *** 的汽车 |
| Marked | 标记 | 将不雅词语括在 XML 标记 <profanity>...</profanity> 内。 | Que coche de<insert-profane-word> |
多么 <profanity><insert-profane-word></profanity> 的汽车 |
| Deleted | 将不雅词语从输出中删除且不替换。 | Que coche de<insert-profane-word> |
多么的汽车 |
在上面的示例中，<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”。
换而言之，冒号分隔开始和结束索引，连字符分隔语言，空格分隔词。 一个单词可能与另一种语言中的 0 个、1 个或多个单词比对，而比对的词可能是不连续的。 当没有可用的比对信息时，比对元素将为空。 在这种情况下，该方法不会返回任何错误。
若要接收比对信息，请在查询字符串中指定 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，此动态字典功能都以相同的方式工作。 应尽量少使用此功能。 对翻译进行自定义时，一个合适且要好得多的方法是使用自定义翻译工具。 自定义翻译工具能够充分利用上下文和统计概率。 如果可以创建在上下文中显示工作或短语的训练数据，则会得到更好的结果。 详细了解自定义翻译工具。