翻译器 3.0:Translate
翻译文本。
请求 URL
将 POST
请求发送到:
https://api.translator.azure.cn/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.translator.azure.cn/translate?api-version=3.0&from=en&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Ocp-Apim-Subscription-Region: your-region" -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.translator.azure.cn/translate?api-version=3.0&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Ocp-Apim-Subscription-Region: your-region" -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.translator.azure.cn/translate?api-version=3.0&to=zh-Hans&toScript=Latn" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Ocp-Apim-Subscription-Region: your-region" -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.translator.azure.cn/translate?api-version=3.0&from=en&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Ocp-Apim-Subscription-Region: your-region" -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.translator.azure.cn/translate?api-version=3.0&from=en&to=zh-Hans&to=de" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Ocp-Apim-Subscription-Region: your-region" -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 | 操作 |
---|---|
NoAction |
NoAction 是默认行为。 不雅内容从源传递到目标。 示例源(日语):彼はジャッカスです。 示例翻译(英语):他是 jack---。 |
Deleted |
将不雅词语从输出中删除且不替换。 示例源(日语):彼はジャッカスです。 示例翻译(英语):他是 ** |
Marked |
标记可替换输出中标记的单词。 标记取决于 ProfanityMarker 参数。 如果 ProfanityMarker=Asterisk ,不雅词语会被替换为 *** :示例源(日语):彼はジャッカスです。 示例翻译(英语):他是 \\\*。 如果 ProfanityMarker=Tag ,则不雅词语会被括在 XML 标记 <profanity> 和 </profanity> 中:示例源(日语):彼はジャッカスです。 示例翻译(英语):他是<不雅 >jack---</不雅>。 |
例如:
curl -X POST "https://api.translator.azure.cn/translate?api-version=3.0&from=en&to=de&profanityAction=Marked" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Ocp-Apim-Subscription-Region: your-region" -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.translator.azure.cn/translate?api-version=3.0&from=en&to=de&profanityAction=Marked&profanityMarker=Tag" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Ocp-Apim-Subscription-Region: your-region" -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.translator.azure.cn/translate?api-version=3.0&from=en&to=zh-Hans&textType=html" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Ocp-Apim-Subscription-Region: your-region" -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.translator.azure.cn/translate?api-version=3.0&from=en&to=fr&includeAlignment=true" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Ocp-Apim-Subscription-Region: your-region" -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.translator.azure.cn/translate?api-version=3.0&from=en&to=fr&includeSentenceLength=true" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Ocp-Apim-Subscription-Region: your-region" -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.translator.azure.cn/translate?api-version=3.0&from=en&to=de" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Ocp-Apim-Subscription-Region: your-region" -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
,此动态字典功能都以相同的方式工作。 应尽量少使用此功能。 对翻译进行自定义时,一个合适且要好得多的方法是使用自定义翻译工具。 自定义翻译工具能够充分利用上下文和统计概率。 如果可以创建在上下文中显示工作或短语的训练数据,则会得到更好的结果。