翻譯工具 3.0：翻譯

  • 發行項

翻譯文字。

要求 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 選擇性參數。
指定翻譯類別（網域）的字串。 此參數可用來從使用自定義 翻譯工具 建置的自定義系統取得翻譯。 若要使用已部署的自訂系統，請將自定義 翻譯工具 專案詳細數據的類別標識元新增至類別參數。 預設值為： 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"}
        ]
    }
]

處理粗話

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

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

ProfanityAction 動作
NoAction NoAction 是預設行為。 粗話會從來源傳遞到目標。

範例來源（日文）：基はジャッカスです。
範例翻譯（英文）：他是個傑克---.
Deleted 將會從輸出中移除不雅單字，而不予以取代。

範例來源（日文）：基はジャッカスです。
範例翻譯（英文）：他是**
Marked 標記會取代輸出中標示的字組。 標記取決於 ProfanityMarker 參數。

針對 ProfanityMarker=Asterisk，粗話字會取代為 ***：
範例來源（日文）：基はジャッカスです。
範例翻譯（英文）：他是 \\\*。

針對 ProfanityMarker=Tag，粗話字會以 XML 標記 <粗話> 和 </粗話>括住：
範例來源（日文）：基はジャッカスです。
範例翻譯（英文）：他是 <粗話>傑克---</粗話>。

例如：

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 會完全利用內容和統計機率。 如果您可以建立訓練數據，以在內容中顯示您的工作或片語，您會取得更好的結果。 深入瞭解自定義 翻譯工具。

下一步

試用 翻譯工具 快速入門