文本翻译 API 3.0:语言Translator Text API 3.0: Languages

获取文本翻译 API 的其他操作当前支持的语言集。Gets the set of languages currently supported by other operations of the Translator Text API.

请求 URLRequest URL

GET 请求发送到:Send a GET request to:

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

请求参数Request parameters

查询字符串上传递的请求参数如下:Request parameters passed on the query string are:

查询参数Query parameter 说明Description
api-versionapi-version 必需参数。Required parameter.
客户端所请求的 API 的版本。Version of the API requested by the client. 值必须是 3.0Value must be 3.0.
scopescope 可选参数。Optional parameter.
逗号分隔的名称列表,用于定义要返回的语言组。A comma-separated list of names defining the group of languages to return. 允许的组名称为:translationtransliterationdictionaryAllowed group names are: translation, transliteration and dictionary. 如果未指定范围,则返回所有组,这相当于传递了 scope=translation,transliteration,dictionaryIf no scope is given, then all groups are returned, which is equivalent to passing scope=translation,transliteration,dictionary. 若要确定哪个支持的语言集适合你的场景,请参阅响应对象的说明。To decide which set of supported languages is appropriate for your scenario, see the description of the response object.

请求标头为:Request headers are:

标头Headers 说明Description
Accept-LanguageAccept-Language 可选请求标头。Optional request header.
要用于用户界面字符串的语言。The language to use for user interface strings. 响应中的某些字段是语言的名称,或区域的名称。Some of the fields in the response are names of languages or names of regions. 使用此参数可以定义要以哪种语言返回这些名称。Use this parameter to define the language in which these names are returned. 通过提供格式正确的 BCP 47 语言标记来指定语言。The language is specified by providing a well-formed BCP 47 language tag. 例如,使用值 fr 来请求法语名称,或使用值 zh-Hant 来请求繁体中文名称。For instance, use the value fr to request names in French or use the value zh-Hant to request names in Chinese Traditional.
如果未指定目标语言或者本地化不可用,则以英语提供名称。Names are provided in the English language when a target language is not specified or when localization is not available.
X-ClientTraceIdX-ClientTraceId 可选请求标头。Optional request header.
客户端生成的 GUID,用于唯一地标识请求。A client-generated GUID to uniquely identify the request.

无需身份验证即可获取语言资源。Authentication isn't required to get language resources.

响应正文Response body

客户端使用 scope 查询参数来定义它关注的语言组。A client uses the scope query parameter to define which groups of languages it's interested in.

  • scope=translation 提供支持将文本从一种语言翻译成另一种语言的语言;scope=translation provides languages supported to translate text from one language to another language;

  • scope=transliteration 提供将一种语言的文本从一个脚本转换为另一个脚本的功能;scope=transliteration provides capabilities for converting text in one language from one script to another script;

  • scope=dictionary 提供语言对,Dictionary 操作针对这些语言对返回数据。scope=dictionary provides language pairs for which Dictionary operations return data.

客户端可以通过指定逗号分隔的名称列表同时检索多个组。A client may retrieve several groups simultaneously by specifying a comma-separated list of names. 例如,scope=translation,transliteration,dictionary 将返回所有组支持的语言。For example, scope=translation,transliteration,dictionary would return supported languages for all groups.

成功的响应是一个 JSON 对象,其中包含请求的每个组的一个属性:A successful response is a JSON object with one property for each requested group:

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

每个属性的值如下。The value for each property is as follows.

  • translation 属性translation property

    translation 属性的值是 (键, 值) 对的字典。The value of the translation property is a dictionary of (key, value) pairs. 每个键是一个 BCP 47 语言标记。Each key is a BCP 47 language tag. 键标识文本的翻译目标语言或源语言。A key identifies a language for which text can be translated to or translated from. 与键关联的值是一个 JSON 对象,其中包含描述语言的属性:The value associated with the key is a JSON object with properties that describe the language:

    • name:通过 Accept-Language 标头请求的区域设置中语言的显示名称。name: Display name of the language in the locale requested via Accept-Language header.

    • nativeName:此语言的当地区域设置中的语言的显示名称。nativeName: Display name of the language in the locale native for this language.

    • dir:方向性,rtl 表示语言从右向左,ltr 表示语言从左到右。dir: Directionality, which is rtl for right-to-left languages or ltr for left-to-right languages.

    示例如下:An example is:

    {
      "translation": {
        ...
        "fr": {
          "name": "French",
          "nativeName": "Français",
          "dir": "ltr"
        },
        ...
      }
    }
    
  • transliteration 属性transliteration property

    transliteration 属性的值是 (键, 值) 对的字典。The value of the transliteration property is a dictionary of (key, value) pairs. 每个键是一个 BCP 47 语言标记。Each key is a BCP 47 language tag. 键标识某种语言,该语言的文本可以从一个脚本转换为另一个脚本。A key identifies a language for which text can be converted from one script to another script. 与键关联的值是一个 JSON 对象,其中包含描述语言及其支持的脚本的属性:The value associated with the key is a JSON object with properties that describe the language and its supported scripts:

    • name:通过 Accept-Language 标头请求的区域设置中语言的显示名称。name: Display name of the language in the locale requested via Accept-Language header.

    • nativeName:此语言的当地区域设置中的语言的显示名称。nativeName: Display name of the language in the locale native for this language.

    • scripts:要转换的源脚本列表。scripts: List of scripts to convert from. scripts 列表中的每个元素具有属性:Each element of the scripts list has properties:

      • code:标识脚本的代码。code: Code identifying the script.

      • name:通过 Accept-Language 标头请求的区域设置中脚本的显示名称。name: Display name of the script in the locale requested via Accept-Language header.

      • nativeName:语言的当地区域设置中的语言的显示名称。nativeName: Display name of the language in the locale native for the language.

      • dir:方向性,rtl 表示语言从右向左,ltr 表示语言从左到右。dir: Directionality, which is rtl for right-to-left languages or ltr for left-to-right languages.

      • toScripts:文本可转换到的目标脚本列表。toScripts: List of scripts available to convert text to. toScripts 列表的每个元素具有前面所述的属性 codenamenativeNamedirEach element of the toScripts list has properties code, name, nativeName, and dir as described earlier.

    示例如下:An example is:

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

    dictionary 属性的值是 (键, 值) 对的字典。The value of the dictionary property is a dictionary of (key, value) pairs. 每个键是一个 BCP 47 语言标记。Each key is a BCP 47 language tag. 键标识支持替代翻译和回译的语言。The key identifies a language for which alternative translations and back-translations are available. 值是一个 JSON 对象,描述提供可用翻译的源语言和目标语言:The value is a JSON object that describes the source language and the target languages with available translations:

    • name:通过 Accept-Language 标头请求的区域设置中源语言的显示名称。name: Display name of the source language in the locale requested via Accept-Language header.

    • nativeName:此语言的当地区域设置中的语言的显示名称。nativeName: Display name of the language in the locale native for this language.

    • dir:方向性,rtl 表示语言从右向左,ltr 表示语言从左到右。dir: Directionality, which is rtl for right-to-left languages or ltr for left-to-right languages.

    • translations:提供替代翻译以及为源语言中表达的查询提供示例的语言列表。translations: List of languages with alterative translations and examples for the query expressed in the source language. translations 列表中的每个元素具有属性:Each element of the translations list has properties:

      • name:通过 Accept-Language 标头请求的区域设置中目标语言的显示名称。name: Display name of the target language in the locale requested via Accept-Language header.

      • nativeName:目标语言的当地区域设置中的目标语言的显示名称。nativeName: Display name of the target language in the locale native for the target language.

      • dir:方向性,rtl 表示语言从右向左,ltr 表示语言从左到右。dir: Directionality, which is rtl for right-to-left languages or ltr for left-to-right languages.

      • code:标识目标语言的语言代码。code: Language code identifying the target language.

    示例如下:An example is:

    "es": {
      "name": "Spanish",
      "nativeName": "Español",
      "dir": "ltr",
      "translations": [
        {
          "name": "English",
          "nativeName": "English",
          "dir": "ltr",
          "code": "en"
        }
      ]
    },
    

在不更改 API 版本的情况下,响应对象的结构不会更改。The structure of the response object will not change without a change in the version of the API. 对于相同的 API 版本,可用语言的列表可能会不断变化,因为 Microsoft Translator 在不断扩展其服务支持的语言列表。For the same version of the API, the list of available languages may change over time because Microsoft Translator continually extends the list of languages supported by its services.

支持的语言列表不会频繁变化。The list of supported languages will not change frequently. 若要节省网络带宽并提高响应能力,客户端应用程序应考虑缓存语言资源和相应的实体标记 (ETag)。To save network bandwidth and improve responsiveness, a client application should consider caching language resources and the corresponding entity tag (ETag). 然后,客户端应用程序可以定期(例如,每隔 24 小时)查询服务,以提取最新的受支持语言集。Then, the client application can periodically (for example, once every 24 hours) query the service to fetch the latest set of supported languages. If-None-Match 标头字段中传递当前的 ETag 值可让服务优化响应。Passing the current ETag value in an If-None-Match header field will allow the service to optimize the response. 如果未修改资源,则服务将返回状态代码 304 和空响应正文。If the resource has not been modified, the service will return status code 304 and an empty response body.

响应标头Response headers

标头Headers 说明Description
ETagETag 所请求的受支持语言组的实体标记的当前值。Current value of the entity tag for the requested groups of supported languages. 若要提高后续请求的效率,客户端可在 If-None-Match 标头字段中发送 ETag 值。To make subsequent requests more efficient, the client may send the ETag value in an If-None-Match header field.
X-RequestIdX-RequestId 服务生成的用于标识请求的值。Value generated by the service to identify the request. 它用于故障排除目的。It is used for troubleshooting purposes.

响应状态代码Response status codes

下面是请求可能返回的 HTTP 状态代码。The following are the possible HTTP status codes that a request returns.

状态代码Status Code 说明Description
200200 成功。Success.
304304 自请求标头 If-None-Match 指定版本以来,资源尚未修改。The resource has not been modified since the version specified by request headers If-None-Match.
400400 查询参数之一缺失或无效。One of the query parameters is missing or not valid. 请更正请求参数,然后重试。Correct request parameters before retrying.
429429 由于客户端已超出请求限制,服务器拒绝了请求。The server rejected the request because the client has exceeded request limits.
500500 发生了意外错误。An unexpected error occurred. 如果错误持续存在,请报告相关信息:发生故障的日期和时间、响应标头 X-RequestId 中的请求标识符、请求标头 X-ClientTraceId 中的客户端标识符。If the error persists, report it with: date and time of the failure, request identifier from response header X-RequestId, and client identifier from request header X-ClientTraceId.
503503 服务器暂不可用。Server temporarily unavailable. 重试请求。Retry the request. 如果错误持续存在,请报告相关信息:发生故障的日期和时间、响应标头 X-RequestId 中的请求标识符、请求标头 X-ClientTraceId 中的客户端标识符。If the error persists, report it with: date and time of the failure, request identifier from response header X-RequestId, and client identifier from request header X-ClientTraceId.

如果发生错误,请求也将返回 JSON 错误响应。If an error occurs, the request will also return a JSON error response. 错误代码是一个 6 位数字,包括 3 位数的 HTTP 状态代码,后接用于进一步将错误分类的 3 位数。The error code is a 6-digit number combining the 3-digit HTTP status code followed by a 3-digit number to further categorize the error. 常见错误代码可在 v3 文本翻译 API 参考页面上找到。Common error codes can be found on the v3 Translator Text API reference page.

示例Examples

以下示例演示如何检索文本翻译支持的语言。The following example shows how to retrieve languages supported for text translation.

curl "https://api.translator.azure.cn/languages?api-version=3.0&scope=translation"