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

翻译器 3.0：Languages

项目
09/01/2024

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

请求 URL

将 GET 请求发送到：

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

对于虚拟网络，请使用自定义域终结点：

https://<your-custom-domain>.cognitiveservices.azure.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"

通过