翻译器 3.0：Translate

项目
06/11/2024

翻译文本。

请求 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，此动态字典功能都以相同的方式工作。应尽量少使用此功能。对翻译进行自定义时，一个合适且要好得多的方法是使用自定义翻译工具。自定义翻译工具能够充分利用上下文和统计概率。如果可以创建在上下文中显示工作或短语的训练数据，则会得到更好的结果。

后续步骤

试用翻译器快速入门

通过

翻译器 3.0：Translate

请求 URL

请求参数

必需的参数

可选参数

请求正文

响应正文

响应标头

响应状态代码

示例

翻译单个输入

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

通过音译进行翻译

翻译多行文本

翻译为多种语言

处理不雅内容

翻译包含标记的内容

获取比对信息

限制

获取句子边界

使用动态词典进行翻译

后续步骤

其他资源