翻譯工具 3.0：翻譯

發行項
09/22/2023

翻譯文字。

要求 URL

將 POST 要求傳送至：

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

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

要求參數

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

必要參數

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

選擇性參數

查詢參數	描述

查詢參數	描述
從	選擇性參數。指定輸入文字的語言。使用 `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` 指出服務可在自訂系統不存在時，回復為一般系統。

要求標頭包括：

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

要求本文

要求的本文是 JSON 陣列。每個陣列項目都是字串屬性名為 Text 的 JSON 物件，其代表要翻譯的字串。

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

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

回應本文

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

detectedLanguage：物件，透過下列屬性描述偵測到的語言：
- language：字串，代表偵測到語言的代碼。
- score：浮點值，表示結果的信賴度。分數介於 0 與 1 之間，分數低表示信賴度偏低。
  
  只有在要求自動偵測語言時，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	指出要求進行翻譯的每個 'to' 語言翻譯所使用的系統類型。此值是以逗號分隔的字串清單。每個字串都指出類型：自訂 - 要求包含自訂系統，而且在翻譯期間至少使用一個自訂系統。小組 - 所有其他要求
X-metered-usage	指定取用 (使用者針對翻譯工作要求) 收費的字元數。例如，如果「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 (預設)。

ProfanityAction	動作
`NoAction`	NoAction 為預設行為。粗話會從來源傳遞到目標。範例來源 (日文)：彼はジャッカスです。範例翻譯 (英文) ：他是插孔---.
`Deleted`	將會從輸出中移除不雅單字，而不予以取代。範例來源 (日文)：彼はジャッカスです。範例翻譯 (英文) ：他是**
`Marked`	標記會取代輸出中標示的字組。標記取決於 `ProfanityMarker` 參數。對於 `ProfanityMarker=Asterisk`，不雅字眼會取代為 `*`：範例來源 (日文)：彼はジャッカスです。範例翻譯 (英文)** ：他是 \ \ \。對於 `ProfanityMarker=Tag`，不雅字眼會括上 XML 標籤 <profanity> 和 </profanity>：範例來源 (日文)：彼はジャッカスです。範例翻譯 (英文)* ：他是 < 粗話 > 插--- < /粗話 > 。

例如：

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
只會傳回一部分語言組的對齊方式：
- 英文為其他任何語言 (除了繁體中文、廣東話 (繁體) 或塞爾維亞文 (斯拉夫文)) 的目標/來源語言。
- 從日文到韓文，或從韓文到日文。
- 從日文翻譯為簡體中文，以及簡體中文翻譯為日文。
- 從簡體中文翻譯為中文繁體，以及繁體中文翻譯為簡體中文。
如果句子是無法對齊的翻譯，則不會對齊。 Canned 翻譯的範例為 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>

例如，請考慮英文句子 "The word wordomatic is a dictionary entry"。若要在翻譯中保留字組 wordomatic，請傳送要求：

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。 Custom Translator 會完全利用內容和統計機率。如果您可以建立顯示內容中工作或片語的定型資料，則會得到更好的結果。深入了解 Custom Translator。

下一步

嘗試翻譯工具快速入門

翻譯工具 3.0：翻譯

要求 URL

要求參數

必要參數

選擇性參數

要求本文

回應本文

回應標頭

回應狀態碼

範例

翻譯單一輸入

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

含轉換的翻譯

翻譯文字的多個片段

翻譯為多種語言

處理粗話

翻譯包含標記的內容，並決定翻譯內容

取得對齊方式資訊

限制

取得句子界限

使用動態字典翻譯

下一步

其他資源

其他資源