共用方式為


翻譯工具 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 選擇性參數
指定翻譯類別(網域)的字串。 此參數用來從使用 Custom Translator 所建置的自訂系統取得翻譯。 若要使用已部署的自訂系統,請將自定義翻譯工具 專案詳細 數據的類別識別元新增至類別參數。 預設值為: general
profanityAction 選擇性參數
指定在翻譯中應如何處理粗話。 可能的值為: NoAction (預設值)、 MarkedDeleted。 若要了解處理粗話的方法,請參閱 粗話處理
profanityMarker 選擇性參數
指定應該如何在翻譯中標示粗話。 可能的值為:Asterisk (預設) 或 Tag。 若要了解處理粗話的方法,請參閱 粗話處理
includeAlignment 選擇性參數
指定是否要包含來源文字到翻譯文字的對齊投影。 可能的值為: truefalse (預設值)。
includeSentenceLength 選擇性參數
指定是否要包含輸入文字和翻譯文字的句子界限。 可能的值為: truefalse (預設值)。
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的單一字串屬性 的物件,會將輸入文字對應至翻譯的文字。 只有在要求參數 includeAlignmenttrue時,才會提供對齊資訊。 對齊方式會以下列格式的字串值傳回: [[SourceTextStartIndex]:[SourceTextEndIndex]–[TgtTextStartIndex]:[TgtTextEndIndex]]。 冒號會分隔開頭和結束索引、破折號分隔語言,而空格則會分隔單字。 一個單字可以與另一種語言的零、一或多個單字對齊,而對齊的單字可以是不連續的。 當沒有可用的對齊資訊時,對齊專案是空的。 如需範例和限制,請參閱 取得對齊資訊
    • sentLen:在輸入和輸出文字中傳回句子界限的物件。

      • srcSentLen:整數陣列,表示輸入文字中句子的長度。 陣列的長度是句子數目,而值則是每個句子的長度。

      • transSentLen:整數陣列,表示翻譯文字中句子的長度。 陣列的長度是句子數目,而值則是每個句子的長度。

      只有在要求參數 includeSentenceLengthtrue時,才會包含句子界限。

  • 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 DeletedMarkedNoAction (預設值)。

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

下一步