翻譯工具 3.0：語言

發行項
09/02/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 翻譯工具會持續擴充其服務所支援的語言清單。

支援的語言清單不會經常變更。若要節省網路頻寬並改善回應性，用戶端應用程式應考慮快取語言資源和對應的實體卷標（ETag）。然後，用戶端應用程式可以定期（例如每 24 小時一次）查詢服務，以擷取最新的支援語言集。傳遞 If-None-Match 標頭欄位中目前的 ETag 值，可讓服務達到最佳化的回應。如果未修改資源，服務會傳回狀態代碼 304 和空的回應本文。

回應標頭

標題	描述
ETag	所要求語言群組的實體標籤目前值。若要讓後續要求更有效率，用戶端可能會傳送`ETagIf-None-Match`標頭欄位中的值。
X-RequestId	服務所產生的值，以識別要求。其用於疑難解答目的。

回應狀態代碼

以下是要求傳回的可能 HTTP 狀態碼。

狀態碼	描述
200	成功。
304	資源不會修改，且與要求標頭 `If-None-Match`所指定的版本一致。
400	其中一個查詢參數遺失或無效。重試之前，請先更正要求參數。
429	伺服器因為客戶端超過要求限制而拒絕要求。
500	發生未預期的錯誤。如果錯誤持續發生，請報告失敗的日期和時間、回應標頭的要求標識碼，以及來自要求標頭`X-RequestIdX-ClientTraceId`的用戶端標識符。
503	伺服器暫時無法使用。重試要求。如果錯誤持續發生，請報告失敗的日期和時間、回應標頭的要求標識碼，以及來自要求標頭`X-RequestIdX-ClientTraceId`的用戶端標識符。

如果發生錯誤，要求也會傳回 JSON 錯誤回應。錯誤碼是6位數的數字，結合3位數 HTTP狀態代碼，後面接著3位數的數位，以進一步分類錯誤。 v3 翻譯工具參考頁面上可找到常見的錯誤碼。

範例

下列範例示範如何擷取文字翻譯支持的語言。

curl "https://api.cognitive.microsofttranslator.com/languages?api-version=3.0&scope=translation"

共用方式為