翻譯工具 3.0：翻譯

發行項
09/27/2024

翻譯文字。

要求 URL

將 POST 要求傳送至：

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

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

要求參數

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

必要參數

查詢參數	描述
api-version	必要參數。用戶端要求的 API 版本。值必須為 `3.0`。
打給	必要參數。指定輸出文字的語言。目標語言必須是範圍中包含的`translation`其中一種支持語言。例如，使用 `to=de` 來翻譯為德文。藉由在查詢字串中重複參數，即可同時轉譯成多種語言。例如，使用 `to=de&to=it` 來翻譯為德文和義大利文。

選擇性參數

查詢參數	描述
from	選擇性參數。指定輸入文字的語言。使用範圍查閱支持的語言，以尋找可從中翻譯的語言。`translation` 若未指定 `from` 參數，則會套用自動語言偵測來判斷來源語言。使用動態字典功能時，您必須使用 `from` 參數，而不是自動偵測。注意：動態字典功能區分大小寫。
textType	選擇性參數。定義翻譯的文字是純文本還是 HTML 文字。任何 HTML 都必須是格式正確的完整專案。可能的值為：`plain` (預設) 或 `html`。
category	選擇性參數。指定翻譯類別（網域）的字串。此參數用來從使用 Custom Translator 所建置的自訂系統取得翻譯。若要使用已部署的自訂系統，請將自定義翻譯工具專案詳細數據的類別識別元新增至類別參數。預設值為： `general`。
profanityAction	選擇性參數。指定在翻譯中應如何處理粗話。可能的值為： `NoAction` （預設值）、 `Marked`或 `Deleted`。若要了解處理粗話的方法，請參閱粗話處理。
profanityMarker	選擇性參數。指定應該如何在翻譯中標示粗話。可能的值為：`Asterisk` (預設) 或 `Tag`。若要了解處理粗話的方法，請參閱粗話處理。
includeAlignment	選擇性參數。指定是否要包含來源文字到翻譯文字的對齊投影。可能的值為： `true` 或 `false` （預設值）。
includeSentenceLength	選擇性參數。指定是否要包含輸入文字和翻譯文字的句子界限。可能的值為： `true` 或 `false` （預設值）。
suggestedFrom	選擇性參數。如果無法識別輸入文字的語言，則指定後援語言。省略參數時 `from` ，會套用語言自動偵測。如果偵測失敗，則會 `suggestedFrom` 假設語言。
fromScript	選擇性參數。指定輸入文字的腳本。
toScript	選擇性參數。指定翻譯文字的腳本。
allowFallback	選擇性參數。指定當自定義系統不存在時，允許服務回復為一般系統。可能的值為：`true` (預設) 或 `false`。 `allowFallback=false` 指定翻譯應該只使用針對 `category` 要求所指定定型的系統。如果從語言 X 到語言 Y 的翻譯需要透過樞紐語言 E 進行鏈結，則鏈結中的所有系統（X → E 和 E → Y）都必須是自定義且具有相同類別。如果找不到具有特定類別的系統，要求會傳回 400 狀態代碼。 `allowFallback=true` 指定當自定義系統不存在時，允許服務回復為一般系統。

要求標頭包括：

標題	描述
驗證標頭	必要的要求標頭。請參閱可用的驗證選項。
內容-類型	必要的要求標頭。指定承載的內容類型。接受的值為 `application/json; charset=UTF-8`。
Content-Length	選擇性。要求本文的長度。
X-ClientTraceId	選擇性。用於識別唯一要求的 GUID，由用戶端產生。如果您使用名為 `ClientTraceId`的查詢參數，在查詢字串中包含追蹤標識碼，則可以省略此標頭。

要求本文

要求的主體是 JSON 陣列。每個陣列元素都是 JSON 物件，其具有名為 Text的字串屬性，代表要翻譯的字串。

[
    {"Text":"I would really like to drive your car around the block a few times."}
]

如需字元和陣列限制的相關信息，請參閱要求限制。

回應本文

成功的回應是 JSON 陣列，輸入數位中的每個字串都有一個結果。結果物件包含下列屬性：

detectedLanguage：對象，透過下列屬性描述偵測到的語言：
- language：字串，表示偵測到語言的程序代碼。
- score：指出結果信賴度的浮點數。分數介於零和一和低分數之間，表示信賴度較低。
detectedLanguage只有在要求語言自動偵測時，屬性才會出現在結果物件中。
translations：翻譯結果的陣列。陣列的大小符合透過 to 查詢參數指定的目標語言數目。陣列中的每個元素都包含：
- to：字串，表示目標語言的語言代碼。
- text：提供翻譯文字的字串。
- transliteration：物件，在參數所指定的腳本中提供翻譯的 toScript 文字。
  - script：指定目標文稿的字串。
  - text：字串，提供目標腳本中翻譯的文字。
  transliteration如果未進行音譯，則不會包含物件。
  - alignment：具有名為 proj的單一字串屬性的物件，會將輸入文字對應至翻譯的文字。只有在要求參數 includeAlignment 為 true時，才會提供對齊資訊。對齊方式會以下列格式的字串值傳回： [[SourceTextStartIndex]:[SourceTextEndIndex]–[TgtTextStartIndex]:[TgtTextEndIndex]]。冒號會分隔開頭和結束索引、破折號分隔語言，而空格則會分隔單字。一個單字可以與另一種語言的零、一或多個單字對齊，而對齊的單字可以是不連續的。當沒有可用的對齊資訊時，對齊專案是空的。如需範例和限制，請參閱取得對齊資訊。
- sentLen：在輸入和輸出文字中傳回句子界限的物件。
  - srcSentLen：整數陣列，表示輸入文字中句子的長度。陣列的長度是句子數目，而值則是每個句子的長度。
  - transSentLen：整數陣列，表示翻譯文字中句子的長度。陣列的長度是句子數目，而值則是每個句子的長度。
  只有在要求參數 includeSentenceLength 為 true時，才會包含句子界限。
sourceText：具有名為 text的單一字串屬性的物件，其會提供來源語言默認腳本中的輸入文字。 sourceText 只有在輸入以不是語言一般腳本的腳本表示時，屬性才會存在。例如，如果輸入是以拉丁文腳本撰寫的阿拉伯文，則會 sourceText.text 是轉換成阿拉伯腳本的相同阿拉伯文文字.

範例區段中會提供 JSON 回應的範例。

回應標頭

標題	描述
X-requestid	服務所產生的值，以識別用於疑難解答目的的要求。
X-mt-system	指定用於翻譯每個要求翻譯之「到」語言的系統類型。值是以逗號分隔的字串清單。每個字串都指出類型：自定義 - 要求包含自定義系統，而且翻譯期間至少使用了一個自定義系統。小組 - 所有其他要求
X 計量使用量	指定翻譯工作要求的取用次數（使用者需付費的字元數）。例如，如果「Hello」這個字是從英文（en）轉譯為法文（fr），則此字段會傳回值 `5`。

回應狀態代碼

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

狀態碼	描述
200	成功。
400	其中一個查詢參數遺失或無效。重試之前，請先更正要求參數。
401	無法驗證要求。檢查是否已指定認證且有效。
403	要求未獲授權。檢查詳細數據錯誤訊息。此狀態代碼通常表示您使用試用版訂用帳戶所提供的所有免費翻譯。
408	因為缺少資源，因此無法完成要求。檢查詳細數據錯誤訊息。當要求包含自定義類別時，此狀態代碼通常表示自定義翻譯系統尚無法提供要求。要求應在等候期間後重試（例如 1 分鐘）。
429	伺服器因為客戶端超過要求限制而拒絕要求。
500	發生未預期的錯誤。如果錯誤持續發生，請報告失敗的日期和時間、來自響應標頭 X-RequestId 的要求標識碼，以及來自要求標頭 X-ClientTraceId 的用戶端識別符。
503	伺服器暫時無法使用。請重試要求。如果錯誤持續發生，請報告失敗的日期和時間、來自響應標頭 X-RequestId 的要求標識碼，以及來自要求標頭 X-ClientTraceId 的用戶端識別符。

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

範例

轉譯單一輸入

此範例示範如何將單一句子從英文翻譯成簡體中文。

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

回應本文為：

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"}
        ]
    }
]

數位包含 translations 一個元素，提供輸入中單一文字片段的翻譯。

使用語言自動偵測來翻譯單一輸入

此範例示範如何將單一句子從英文翻譯成簡體中文。要求不會指定輸入語言。會改用來源語言的自動偵測。

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

回應本文為：

[
    {
        "detectedLanguage": {"language": "en", "score": 1.0},
        "translations":[
            {"text": "你好, 你叫什么名字？", "to": "zh-Hans"}
        ]
    }
]

回應類似於上一個範例的回應。由於要求語言自動偵測，回應也包含輸入文字偵測到之語言的相關信息。語言自動偵測效果較適合較長的輸入文字。

使用音譯翻譯

讓我們藉由新增音譯來擴充先前的範例。下列要求要求以拉丁文腳本撰寫的中文翻譯。

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=zh-Hans&toScript=Latn" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

回應本文為：

[
    {
        "detectedLanguage":{"language":"en","score":1.0},
        "translations":[
            {
                "text":"你好, 你叫什么名字？",
                "transliteration":{"script":"Latn", "text":"nǐ hǎo , nǐ jiào shén me míng zì ？"},
                "to":"zh-Hans"
            }
        ]
    }
]

翻譯結果現在包含 transliteration 屬性，該屬性會使用拉丁字元來提供翻譯的文字。

翻譯多個文字片段

一次翻譯多個字串只是在要求本文中指定字串數位的問題。

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}, {'Text':'I am fine, thank you.'}]"

回應包含所有文字片段的翻譯，順序與要求完全相同。回應本文為：

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"}
        ]
    },
    {
        "translations":[
            {"text":"我很好，谢谢你。","to":"zh-Hans"}
        ]
    }
]

翻譯成多種語言

此範例示範如何在一個要求中將相同的輸入轉譯成數種語言。

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=zh-Hans&to=de" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

回應本文為：

[
    {
        "translations":[
            {"text":"你好, 你叫什么名字？","to":"zh-Hans"},
            {"text":"Hallo, was ist dein Name?","to":"de"}
        ]
    }
]

處理粗話

一般而言，翻譯工具服務會保留翻譯來源中存在的粗話。粗話程度和使語言不雅內容在文化特性之間不雅，因此目標語言的粗話程度可以放大或減少。

如果您想要避免在翻譯中取得粗話，不論來源文字中是否有粗話，都可以使用粗話篩選選項。此選項可讓您選擇是否要看到已刪除粗話、標示為適當的標籤（讓您選擇新增自己的後置處理），或不採取任何動作。的接受值為 ProfanityAction Deleted、 Marked和 NoAction （預設值）。

接受的不雅內容Action 值	ProfanityMarker 值	動作	範例：來源 - 西班牙文	範例：目標 - 英文
NoAction		預設值。與未設定此選項時相同。粗話會從來源傳遞到目標。	`Que coche de`<插入-不雅-字詞>	What a <insert-profane-word> car
Marked	Asterisk	星號取代不雅字詞 (預設值)。	`Que coche de`<插入-不雅-字詞>	What a *** car
Marked	標籤	不雅的單字會括上 XML 標籤 <profanity>...</profanity>。	`Que coche de`<插入-不雅-字詞>	What a <profanity><insert-profane-word></profanity> car
已刪除		將會從輸出中移除不雅單字，而不予以取代。	`Que coche de`<插入-不雅-字詞>	What a car

在上述範例中，<insert-profane-word> 是不雅字組的預留位置。

例如：

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de&profanityAction=Marked" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'This is an <expletive> good idea.'}]"

此要求會傳回：

[
    {
        "translations":[
            {"text":"Das ist eine *** gute Idee.","to":"de"}
        ]
    }
]

儗：

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de&profanityAction=Marked&profanityMarker=Tag" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'This is an <expletive> good idea.'}]"

最後一個要求會傳回：

[
    {
        "translations":[
            {"text":"Das ist eine <profanity>verdammt</profanity> gute Idee.","to":"de"}
        ]
    }
]

翻譯包含標記的內容

通常轉譯包含標記的內容，例如 HTML 頁面的內容或 XML 檔的內容。使用標籤翻譯內容時包含查詢參數 textType=html 。此外，從翻譯中排除特定內容有時很有用。您可以使用屬性 class=notranslate 來指定應該維持在其原始語言中的內容。在下列範例中，不會翻譯第一個項目 div 內的內容，而第二 div 個元素中的內容則會轉譯。

<div class="notranslate">This will not be translated.</div>
<div>This will be translated. </div>

以下是要說明的範例要求。

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=zh-Hans&textType=html" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'<div class=\"notranslate\">This will not be translated.</div><div>This will be translated.</div>'}]"

回應是:

[
    {
        "translations":[
            {"text":"<div class=\"notranslate\">This will not be translated.</div><div>这将被翻译。</div>","to":"zh-Hans"}
        ]
    }
]

取得對齊資訊

系統會以下列格式的字串值，傳回來源每個單字的對齊方式。每個單字的資訊會以空格分隔，包括中文這類非以空格分隔的語言 (指令碼)：

[[SourceTextStartIndex]:[SourceTextEndIndex]–[TgtTextStartIndex]:[TgtTextEndIndex]] *

範例對齊方式字串："0:0-7:10 1:2-11:20 3:4-0:3 3:4-4:6 5:5-21:21"。

換句話說，冒號會分隔開始與結束索引、虛線會分隔語言，而空格則分隔單字。一個單字可以與另一種語言的零、一或多個單字對齊，而對齊的單字可以是不連續的。沒有對齊方式資訊可用時，Alignment 元素便會空白。在該情況下，方法不會傳回任何錯誤。

若要接收對齊資訊，請在查詢字串上指定 includeAlignment=true 。

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=fr&includeAlignment=true" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'The answer lies in machine translation.'}]"

回應是:

[
    {
        "translations":[
            {
                "text":"La réponse se trouve dans la traduction automatique.",
                "to":"fr",
                "alignment":{"proj":"0:2-0:1 4:9-3:9 11:14-11:19 16:17-21:24 19:25-40:50 27:37-29:38 38:38-51:51"}
            }
        ]
    }
]

對齊資訊會以 0:2-0:1開頭，這表示來源文字The中的前三個字元會對應至翻譯文字中的前兩個字元（La）。

限制

取得對齊資訊是一項實驗性功能，我們針對潛在片語對應的原型研究和體驗而啟用。以下是不支援對齊方式的一些值得注意的限制：

對齊不適用於 HTML 格式為 textType=html 的文字
只有語言組的子集才會傳回對齊方式：
- 除繁體中文、粵語或塞爾維亞文（斯拉夫文）以外的任何其他語言的英文
- 從日文到韓文或從韓文到日文
- 從日文到簡體中文和簡體中文到日文
- 從簡體中文到繁體中文和繁體中文到簡體中文
如果句子是罐頭翻譯，則不會對齊。罐式翻譯的範例為 This is a test、 I love you和其他高頻率句子
當您套用任何方法來防止翻譯時，無法使用對齊方式，如這裡所述

取得句子界限

若要接收來源文字和翻譯文字中句子長度的相關信息，請在查詢字串上指定 includeSentenceLength=true 。

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=fr&includeSentenceLength=true" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'The answer lies in machine translation. The best machine translation technology cannot always provide translations tailored to a site or users like a human. Simply copy and paste a code snippet anywhere.'}]"

回應是:

[
    {
        "translations":[
            {
                "text":"La réponse se trouve dans la traduction automatique. La meilleure technologie de traduction automatique ne peut pas toujours fournir des traductions adaptées à un site ou des utilisateurs comme un être humain. Il suffit de copier et coller un extrait de code n'importe où.",
                "to":"fr",
                "sentLen":{"srcSentLen":[40,117,46],"transSentLen":[53,157,62]}
            }
        ]
    }
]

使用動態字典轉譯

如果已經知道想要套用至單字或片語的翻譯，則可以在要求內以標記來提供。動態字典僅適用於適當的名詞，例如個人名稱和產品名稱。注意：動態字典功能區分大小寫。

要提供的標記會使用下列語法。

<mstrans:dictionary translation="translation of phrase">phrase</mstrans:dictionary>

例如，請考慮英文句子「文字文字是字典專案」。若要在翻譯中保留文字 文字， 請傳送要求：

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'The word <mstrans:dictionary translation=\"wordomatic\">wordomatic</mstrans:dictionary> is a dictionary entry.'}]"

結果如下：

[
    {
        "translations":[
            {"text":"Das Wort \"wordomatic\" ist ein Wörterbucheintrag.","to":"de"}
        ]
    }
]

這個動態字典功能的運作方式 textType=text 與或相同 textType=html。此功能應該謹慎使用。自訂翻譯的適當且更好的方式是使用自定義翻譯工具。 Custom Translator 會完全利用內容和統計機率。如果您可以建立訓練數據，以在內容中顯示您的工作或片語，您會取得更好的結果。深入瞭解自定義翻譯工具。

下一步

試用翻譯工具快速入門

共用方式為

翻譯工具 3.0：翻譯

要求 URL

要求參數

必要參數

選擇性參數

要求本文

回應本文

回應標頭

回應狀態代碼

範例

轉譯單一輸入

使用語言自動偵測來翻譯單一輸入

使用音譯翻譯

翻譯多個文字片段

翻譯成多種語言

處理粗話

翻譯包含標記的內容

取得對齊資訊

限制

取得句子界限

使用動態字典轉譯

下一步

意見反應

其他資源