共用方式為

翻译器 3.0:语言

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

请求的 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
范围 可选参数

一个逗号分隔的名称列表,用于定义要返回的语言组。 允许的组名称包括:translationtransliterationdictionary。 如果未指定作用域,则返回所有组,这等效于传递 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 列表的每个元素都具有前面所述的属性 codenamenativeNamedir

    示例如下:

    {
      "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"

有关详细信息,请参阅语言支持