翻譯工具 3.0：語言

發行項
09/22/2023

取得翻譯工具其他作業目前支援的語言集合。

要求 URL

將 GET 要求傳送至：

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

請參閱虛擬網路翻譯工具服務選取的網路和私人端點組態和支援的支援。

要求參數

在查詢字串上傳遞的要求參數為：

查詢參數	描述
api-version	必要參數用戶端所要求的 API 版本。值必須為 `3.0`。
範圍	選擇性參數。以逗號分隔的名稱列表，用於定義要傳回的語言群組。允許的組名包括： `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"