获取翻译器的其他作当前支持的语言集。
请求的 URL
将 GET
请求发送到:
https://api.translator.azure.cn/languages?api-version=3.0
对于虚拟网络,请使用自定义域终结点:
https://<your-custom-domain>.cognitiveservices.azure.cn/languages?api-version=3.0
有关详细信息,请参阅虚拟网络支持,了解翻译服务所选网络和专用终结点配置和支持。
请求参数
查询字符串上传递的请求参数如下:
查询参数 | DESCRIPTION |
---|---|
API版本 (api-version) |
必需参数 客户端请求的 API 版本。 值必须是 3.0 。 |
范围 |
可选参数。 一个逗号分隔的名称列表,用于定义要返回的语言组。 允许的组名称包括: translation 、transliteration 和 dictionary 。 如果未指定作用域,则返回所有组,这等效于传递 scope=translation,transliteration,dictionary 。 |
请参阅响应正文。
请求标头为:
标头 | DESCRIPTION |
---|---|
Accept-Language |
可选请求标头。 可用于用户界面字符串的语言。 响应中的某些字段是语言或区域名称的名称。 使用此参数定义返回这些名称的语言。 该语言是通过提供格式正确的 BCP 47 语言标记来指定的。 例如,使用值 fr 以法语请求名称,或使用值 zh-Hant 以中文传统形式请求名称。如果未指定目标语言或本地化不可用,则名称以英语提供。 |
X-ClientTraceId |
可选请求标头。 客户端生成的 GUID,用于唯一标识请求。 |
获取语言资源不需要身份验证。
响应体
客户端使用 scope
查询参数来定义要列出的语言组。
scope=translation
提供支持将文本从一种语言翻译成另一种语言的语言;scope=transliteration
提供将一种语言的文本从一个脚本转换为另一个脚本的功能;scope=dictionary
提供Dictionary
作返回数据的语言对。
客户端可以通过指定逗号分隔的名称列表来同时检索多个组。 例如,scope=translation,transliteration,dictionary
将返回所有组支持的语言。
成功的响应是一个 JSON 对象,其中包含每个请求组的一个属性:
{
"translation": {
//... set of languages supported to translate text (scope=translation)
},
"transliteration": {
//... set of languages supported to convert between scripts (scope=transliteration)
},
"dictionary": {
//... set of languages supported for alternative translations and examples (scope=dictionary)
}
}
每个属性的值如下所示。
translation
属性translation
属性的值是一个字典(键、值)对。 每个键都是BCP
47 种语言标记。 键标识文本可以翻译到或翻译的语言。 与键关联的值是一个 JSON 对象,其中包含描述语言的属性:name
:通过Accept-Language
标头请求的区域设置中语言的显示名称。nativeName
:此语言的区域设置中语言的显示名称。dir
:方向性,rtl
从右到左的语言,或从左到右的语言ltr
。
示例如下:
{ "translation": { ... "fr": { "name": "French", "nativeName": "Français", "dir": "ltr" }, ... } }
transliteration
属性transliteration
属性的值是一个字典(键、值)对。 每个键都是BCP
47 种语言标记。 键标识文本可从一个脚本转换为另一个脚本的语言。 与键关联的值是一个 JSON 对象,其中包含描述语言及其支持的脚本的属性:name
:通过Accept-Language
标头请求的区域设置中语言的显示名称。nativeName
:此语言的区域设置中语言的显示名称。scripts
:要从中转换的脚本列表。scripts
列表的每个元素都有属性:code
:标识脚本的代码。name
:通过Accept-Language
标头请求的区域设置中脚本的显示名称。nativeName
:语言的区域设置中语言的显示名称。dir
:方向性,rtl
从右到左的语言,或从左到右的语言ltr
。toScripts
:可用于将文本转换为的脚本列表。toScripts
列表的每个元素都具有前面所述的属性code
、name
、nativeName
和dir
。
示例如下:
{ "transliteration": { ... "ja": { "name": "Japanese", "nativeName": "日本語", "scripts": [ { "code": "Jpan", "name": "Japanese", "nativeName": "日本語", "dir": "ltr", "toScripts": [ { "code": "Latn", "name": "Latin", "nativeName": "ラテン語", "dir": "ltr" } ] }, { "code": "Latn", "name": "Latin", "nativeName": "ラテン語", "dir": "ltr", "toScripts": [ { "code": "Jpan", "name": "Japanese", "nativeName": "日本語", "dir": "ltr" } ] } ] }, ... } }
dictionary
属性dictionary
属性的值是一个字典(键、值)对。 每个键都是BCP
47 种语言标记。 该键标识了可用的替代翻译和反向翻译的语言。 该值是一个 JSON 对象,用于描述源语言和具有可用翻译的目标语言:name
:通过Accept-Language
标头请求的区域设置中源语言的显示名称。nativeName
:此语言的区域设置中语言的显示名称。dir
:方向性,rtl
从右到左的语言,或从左到右的语言ltr
。translations
:具有替代翻译的语言列表和以源语言表示的查询的示例。translations
列表的每个元素都有属性:name
:通过Accept-Language
标头请求的区域设置中目标语言的显示名称。nativeName
:目标语言的区域设置中目标语言的显示名称。dir
:方向性,rtl
从右到左的语言,或从左到右的语言ltr
。code
:标识目标语言的语言代码。
示例如下:
"es": { "name": "Spanish", "nativeName": "Español", "dir": "ltr", "translations": [ { "name": "English", "nativeName": "English", "dir": "ltr", "code": "en" } ] },
如果不更改 API 版本,响应对象的结构不会更改。 对于同一版本的 API,可用语言列表可能会随时间而变化,因为Microsoft Translator 会不断扩展其服务支持的语言列表。
支持的语言列表不会频繁更改。 为了节省网络带宽并提高响应能力,客户端应用程序应考虑缓存语言资源和相应的实体标记(ETag
)。 然后,客户端应用程序可以定期(例如,每 24 小时一次)查询服务以提取最新的受支持语言集。 在 ETag
标头字段中传递当前 If-None-Match
值可让服务优化响应。 如果未修改资源,服务将返回状态代码 304 和空响应正文。
响应标头
标头 | DESCRIPTION |
---|---|
ETag | 所请求的受支持语言组的实体标记的当前值。 若要提高后续请求的效率,客户端可能会在 ETag 标头字段中发送 If-None-Match 值。 |
X-RequestId | 服务生成的用于标识请求的值。 它用于故障排除目的。 |
响应状态代码
下面是请求可能返回的 HTTP 状态代码。
状态代码 | DESCRIPTION |
---|---|
200 | 成功。 |
304 | 资源未修改,与请求标头 If-None-Match 指定的版本保持一致。 |
400 | 查询参数之一缺失或无效。 请更正请求参数,然后重试。 |
429 | 由于客户端已超出请求限制,因此服务器拒绝了请求。 |
500 | 发生意外错误。 如果错误仍然存在,请报告失败的日期和时间、响应标头的请求标识符 X-RequestId ,以及请求标头中的客户端标识符 X-ClientTraceId 。 |
503 | 服务器暂不可用。 重试请求。 如果错误仍然存在,请报告失败的日期和时间、响应标头的请求标识符 X-RequestId ,以及请求标头中的客户端标识符 X-ClientTraceId 。 |
如果发生错误,请求还会返回 JSON 错误响应。 错误代码是一个 6 位数字,包括 3 位数的 HTTP 状态代码,后接用于进一步将错误分类的 3 位数。 常见错误代码可在 v3 翻译器参考页上找到。
例子
以下示例演示如何检索文本翻译支持的语言。
curl "https://api.translator.azure.cn/languages?api-version=3.0&scope=translation"