你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

翻译器 3.0：Languages

项目
09/25/2023

获取翻译器的其他操作当前支持的语言集。

请求 URL

将 GET 请求发送到：

https://api.cognitive.microsofttranslator.com/languages?api-version=3.0

请参阅虚拟网络支持，了解翻译服务所选网络和专用终结点配置与支持。

请求参数

查询字符串上传递的请求参数如下：

查询参数	说明
api-version	必需参数客户端请求的 API 版本。值必须是 `3.0`。
scope	可选参数。逗号分隔的名称列表，用于定义要返回的语言组。允许的组名称为：`translation`、`transliteration` 和 `dictionary`。如果未指定范围，则返回所有组，这相当于传递了 `scope=translation,transliteration,dictionary`。

查看响应正文。

请求标头为：

头文件说明

Accept-Language 可选请求标头。

可用于用户界面字符串的语言。响应中的某些字段是语言的名称，或区域的名称。使用此参数可以定义要以哪种语言返回这些名称。通过提供格式正确的 BCP 47 语言标记来指定语言。例如，使用值 fr 来请求法语名称，或使用值 zh-Hant 来请求繁体中文名称。
如果未指定目标语言或者本地化不可用，则以英语提供名称。

X-ClientTraceId 可选请求标头。
客户端生成的 GUID，用于唯一标识请求。

头文件	说明
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 小时）查询服务，以提取最新的受支持语言集。在 If-None-Match 标头字段中传递当前的 ETag 值可让服务优化响应。如果未修改资源，则服务将返回状态代码 304 和空响应正文。

响应标头

标头	说明
ETag	所请求的受支持语言组的实体标记的当前值。若要提高后续请求的效率，客户端可在 `If-None-Match` 标头字段中发送 `ETag` 值。
X-RequestId	服务生成的用于标识请求的值。它用于故障排除目的。

响应状态代码

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

状态代码	说明
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.cognitive.microsofttranslator.com/languages?api-version=3.0&scope=translation"