參考
功能： Azure Translator → 文件翻譯
API 版本： 2024-05-01
HTTP 方法： POST
- 使用
translate document方法來同步翻譯單一文件。 - 此方法不需要 Azure Blob 儲存體帳戶。
- 最終回應包含已翻譯的文件，並會直接傳回給呼叫用戶端。
重要事項
所有對文件轉換功能的 API 請求都需要一個位於 Azure 入口網站資源概覽頁面的自訂網域端點。
要求 URL
https://{your-document-translation-endpoint}/translator/document:translate?api-version=2024-05-01&sourceLanguage=en&targetLanguage=fr
要求標頭
若要透過 REST API 呼叫同步翻譯功能，請在每個要求中都包含下列標頭。
| 頁首 | 值 | 狀況 |
|---|---|---|
| Ocp-Apim-Subscription-Key | 來自 Azure 入口網站的翻譯工具金鑰。 | • 必要 |
要求參數
必要的查詢參數
| 查詢參數 | 描述 |
|---|---|
| api-version |
必要參數。 用戶端要求的 API 版本。 目前的值為 2024-05-01。 |
| targetLanguage |
必要參數。 指定輸出文件的語言。 目標語言必須是翻譯範圍內包含的支援語言之一。 |
選擇性查詢參數
| 查詢參數 | 描述 |
|---|---|
| sourceLanguage | 指定輸入文件的語言。 若未指定 sourceLanguage 參數，則會套用自動語言偵測來判斷來源語言。 |
| allowFallback | • 布林指明服務可在自訂系統不存在時，回復為 generalnn 系統。 接受的值為： true （預設值）或 false。 • allowFallback=false 指明翻譯只應使用針對要求所指定的類別而進行訓練的系統。• 如果沒有找到具有特定類別的系統，則要求會傳回 400 狀態碼。 • allowFallback=true 指明服務可在自訂系統不存在時，回復為 generalnn 系統。 |
| 類別 | 字串，指定翻譯的分類 (網域)。 此參數用來從使用 Custom Translator 所建置的自訂系統取得翻譯。 若要使用已部署的自訂系統進行同步文件翻譯，請將自訂翻譯工具專案詳細資料中的 Category ID 新增至 category 參數。 預設值為 generalnn。 |
備註
儘管 sourceLanguage 是選用的，但我們強烈建議明確指定。 提供來源語言比依賴自動偵測產生更高品質的翻譯。
要求本文
| 名稱 | 描述 | 內容類型 | 狀況 |
|---|---|---|---|
| 文件 | 要翻譯的來源文件。 | 任何其中一種支援的文件格式。 | 必要 |
| 詞彙 | 文件包含翻譯程序期間要使用的定義字詞清單。 | 任何其中一種支援的詞彙格式。 | 選擇性 |
回應狀態碼
| 狀態代碼 | 描述 |
|---|---|
| 200 | 請求成功，並傳回翻譯後的文件。 |
| 400 | 無效或遺漏請求參數。 |
| 401 | 驗證失敗。 檢查訂閱金鑰或令牌。 |
| 429 | 已超出速率限制。 稍稍延遲後重試。 |
| 500 | 非預期的服務錯誤。 重試或聯絡技術支援並提供請求詳細資訊。 |
| 503 | 服務暫時無法使用。 請稍後再試。 |
備註
錯誤會傳回包含物件的 error JSON 回應。
JSON 錯誤回應範例
{
"error": {
"code": "InvalidRequest",
"message": "The 'targetLanguage' parameter is required.",
"innerError": {
"requestId": "d3e4f6a9-0000-4a9b-8ad3-bdcd1323aa00",
"date": "2025-10-15T10:05:23Z"
}
}
}
翻譯 Word 文件
curl --request POST \
--url 'https://{your-document-translation-endpoint}/translator/document:translate?api-version=2024-05-01&sourceLanguage=en&targetLanguage=fr' \
--header 'Ocp-Apim-Subscription-Key: <your-subscription-key>' \
--form 'document=@<path-to-your-document>/your-document-file.docx' \
--output translated-document-fr.docx
參數
| 參數 | 描述 |
|---|---|
{your-document-translation-endpoint} |
您的文件翻譯端點。 範例：https://your-resource-name.cognitiveservices.azure.com |
<your-subscription-key> |
您的翻譯器訂閱金鑰。 |
sourceLanguage |
（選用） 原始語言程式碼。 範例： en. 若未指定，則自動偵測。 |
targetLanguage |
（必填） 要翻譯成的目標語言代碼。 範例： fr. |
document |
要翻譯的檔案路徑。 |
欲了解更多資訊， 請參閱支援文件格式。
使用詞彙表翻譯 Word 文檔
curl --request POST \
--url 'https://{your-document-translation-endpoint}/translator/document:translate?api-version=2024-05-01&sourceLanguage=en&targetLanguage=fr' \
--header 'Ocp-Apim-Subscription-Key: <your-subscription-key>' \
--form 'document=@<path-to-your-document>/your-document-file.docx' \
--form 'glossary=@<path-to-your-document>/glossary.tsv' \
--output translated-document-fr.docx
參數
| 參數 | 描述 |
|---|---|
{your-document-translation-endpoint} |
您的文件翻譯端點。 範例：https://your-resource-name.cognitiveservices.azure.com |
<your-subscription-key> |
您的翻譯器訂閱金鑰。 |
sourceLanguage |
（選用） 原始語言程式碼。 範例： en. 若未指定，則自動偵測。 |
targetLanguage |
（必填） 要翻譯成的目標語言代碼。 範例： fr. |
document |
要翻譯的檔案路徑。 |
glossary |
詞彙表檔案的路徑。 |
欲了解更多資訊， 請參閱「使用詞彙表與文件翻譯」。