Azure 翻译器 3.0：翻译

转换文本。

请求网址

将 POST 请求发送到：

https://api.translator.azure.cn/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]] 格式的字符串值返回比对内容。 冒号分隔开始索引和结束索引，短划线分隔语言，空格分隔单词。 一个单词可能与另一种语言中的 0 个、1 个或多个单词比对，而比对的词可能是不连续的。 当没有可用的比对信息时，比对元素将为空。 请参阅获取比对信息，了解示例和限制。

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

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

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

    只有在请求参数 includeSentenceLength 为 true 时，才包括句子边界。

• sourceText：一个对象，包含的名为 text 的单个字符串属性在源语言的默认脚本中提供输入文本。 sourceText 属性存在的前提是，表述输入时采用的脚本不是该语言的通用脚本。 例如，如果输入是采用拉丁语脚本编写的阿拉伯语，则 sourceText.text 就是转换为阿拉伯脚本的同一阿拉伯文本.

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

响应头

响应状态代码

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

如果发生错误，请求会返回 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 "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 "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 "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 "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 "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.translator.azure.cn/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.translator.azure.cn/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.translator.azure.cn/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.translator.azure.cn/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.translator.azure.cn/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.translator.azure.cn/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，此动态字典功能都以相同的方式工作。 应尽量少使用此功能。

后续步骤