Translator 3.0：Transliterate

2025-09-19

文本音译 API 将源语言脚本或字母映射到目标语言脚本或字母表。

请求的 URL

POST将请求发送到：

https://api.translator.azure.cn/transliterate?api-version=3.0

请参阅“虚拟网络支持 翻译器服务”所选网络和专用终结点配置和支持。

请求参数

在查询字符串上传递的请求参数包括：

查询参数	Description
API版本 (api-version)	必需参数。客户端请求的 API 版本。值必须是 `3.0`。
语言	必需参数。指定要从一个脚本转换为另一个脚本的文本的语言。通过查询服务获取其`transliteration`，可以列出可能的语言。
fromScript	必需参数。指定输入文本使用的脚本。使用范围查找`transliteration`，查找可用于所选语言的输入脚本。
toScript	必需参数。指定输出脚本。使用范围查找`transliteration`，查找可用于输入语言和输入脚本的选定组合的输出脚本。

请求标头

Headers	Description
身份验证标头	所需的请求标头。请参阅可用的身份验证选项。
Content-Type	所需的请求标头。指定有效负载的内容类型。可能的值包括： `application/json`
内容长度	可选。请求正文的长度。
X-ClientTraceId	可选。客户端生成的 GUID，用于唯一标识请求。如果使用名为 <a0/> 的查询参数在查询字符串中包含跟踪 ID，则可以省略此标头。

请求主体

请求正文是 JSON 数组。每个数组元素都是一个 JSON 对象，其中包含一 Text个名为字符串的属性，该属性表示要转换的字符串。

[
    {"Text":"こんにちは"},
    {"Text":"さようなら"}
]

以下限制适用：

数组最多可以有 10 个元素。
数组元素的文本值不能超过 1,000 个字符，包括空格。
请求中包含的整个文本不能超过 5,000 个字符，包括空格。

响应体

成功的响应是一个 JSON 数组，其中包含输入数组中每个元素的一个结果。结果对象包含以下属性：

text：一个字符串，用于将输入字符串转换为输出脚本。
script：指定输出中使用的脚本的字符串。

JSON 响应示例为：

[
    {"text":"konnnichiha","script":"Latn"},
    {"text":"sayounara","script":"Latn"}
]

响应标头

Headers	Description
X-RequestId	服务生成的值用于标识请求，并用于故障排除目的。

响应状态代码

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

状态代码	Description
200	成功。
400	查询参数之一缺失或无效。在重试之前更正请求参数。
401	无法对请求进行身份验证。检查凭据是否已指定且有效。
403	请求未获授权。检查详细信息错误消息。此代码通常表示使用试用版订阅提供的所有免费翻译。
429	服务器拒绝了请求，因为客户端超出了请求限制。
500	发生意外错误。如果错误仍然存在，请报告失败的日期和时间、响应标头 `X-RequestId`的请求标识符和请求标头 `X-ClientTraceId`中的客户端标识符。
503	服务器暂时不可用。重试请求。如果错误仍然存在，请报告失败的日期和时间、响应标头 `X-RequestId`的请求标识符和请求标头 `X-ClientTraceId`中的客户端标识符。

如果发生错误，请求还会返回 JSON 错误响应。错误代码是一个 6 位数的数字，它组合了 3 位 HTTP 状态代码，后跟一个 3 位数字，以进一步对错误进行分类。可以在 v3 翻译器参考页上找到常见的错误代码。

例子

以下示例演示如何将两个日语字符串转换为罗马化日语。

此示例中请求的 JSON 有效负载：

[{"text":"こんにちは","script":"jpan"},{"text":"さようなら","script":"jpan"}]

如果在不支持 Unicode 字符的命令行窗口中使用 cURL，请获取以下 JSON 有效负载并将其保存到名为 request.txt的文件中。请务必使用 UTF-8 编码保存文件。

curl -X POST "https://api.translator.azure.cn/transliterate?api-version=3.0&language=ja&fromScript=Jpan&toScript=Latn" -H "X-ClientTraceId: 875030C7-5380-40B8-8A03-63DACCF69C11" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json" -d @request.txt

通过