DeepL 術語表怎麼建才吃得到繁中？2026 實查：建表只能填 zh、翻譯才填 ZH-HANT，填錯直接建不起來

翻譯工具最惱人的不是譯得不順，是同一個詞每次譯法都不一樣。品牌名被意譯、產品名被拆開、專有名詞這次叫「智慧助理」下次叫「智能助手」——校稿的時間全花在改同一批字。

DeepL 對這件事的官方解法叫術語表（glossary）：你指定「這個詞就要翻成那個詞」，翻譯時它照辦，而且官方寫明會依大小寫、性別、時態自動變形（目標語言有屈折變化時），不是死板的字串取代。

但繁體中文有一個坑，官方文件寫得很清楚、卻幾乎沒人在教學文裡提：建立術語表的語言代碼只能填 zh，填 zh-Hant 會失敗。這篇把整套流程走一遍。

一、先確認：繁中到底能不能用術語表

能。這一點本次直接讀官方支援語言表（2026-09-03 查核），繁中相關的三個代碼都標示支援術語表：

看到這張表，多數人的下一步就是拿 zh-Hant 去建表——然後失敗。

二、關鍵坑：建表用根碼，翻譯才用變體

DeepL 把語言分成根語言代碼（zh、pt、fr）與變體代碼（zh-Hant、pt-BR、fr-CA）。官方在「語言變體的客製化」文件裡列了一張對照表，直接寫明術語表必須用哪一欄：

官方原句是：客製化（術語表、風格規則）必須用根代碼建立，用變體代碼建立會失敗。

那繁簡怎麼分？在翻譯請求那一步分。術語表用 zh 建立，翻譯時 target_lang 填 ZH-HANT，術語表照樣生效。官方對英文舉的例子是同一個道理：目標語言 EN 的術語表，翻成 EN-US 和 EN-GB 都吃得到。

實務上的做法：如果你的繁中和簡中用語不同（「軟體／软件」「網路／网络」），就建兩個術語表、都用 zh 當目標語言、但條目內容不同，翻譯時依 ZH-HANT 或 ZH-HANS 各帶各的 glossary_id。官方文件裡的葡萄牙文範例（PT-BR 用「nota fiscal」、PT-PT 用「fatura」，兩表都以 PT 建立）就是這個模式。

三、五分鐘建第一個術語表（v3 端點）

先搞懂 v3 的結構：一個術語表（glossary）裝一個以上的字典（dictionary），一個字典＝一個語言對、單向。要雙向就加第二個反向字典。

建立指令（官方範例，語言對改成英翻中）：

curl -X POST https://api.deepl.com/v3/glossaries \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "AMPM Brand Glossary",
    "dictionaries": [
      {
        "source_lang": "en",
        "target_lang": "zh",
        "entries": "prompt\t提示詞\nagent\t代理程式",
        "entries_format": "tsv"
      }
    ]
}'

成功會回 201，內容像這樣：

{
  "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7",
  "ready": true,
  "name": "AMPM Brand Glossary",
  "dictionaries": [
    { "source_lang": "en", "target_lang": "zh", "entry_count": 2 }
  ],
  "creation_time": "2025-08-03T14:16:18.329Z"
}

把 glossary_id 存起來，翻譯時要用。

如果你的詞彙本來就是 CSV 檔，官方給的做法是用 jq -Rs 把整個檔案內容塞進請求的 entries 欄位，不必自己處理跳脫。

註：使用免費 API 金鑰的人，網域要換成 api-free.deepl.com；付費金鑰才是 api.deepl.com。這是官方入門文件明列的差別。

四、翻譯時怎麼帶——這裡有第二個必踩條件

curl -X POST https://api.deepl.com/v2/translate \
  --header "Authorization: DeepL-Auth-Key $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "text": ["Write a better prompt for the agent."],
    "source_lang": "EN",
    "target_lang": "ZH-HANT",
    "glossary_id": "def3a26b-3e84-45b3-84ae-0c0aaf3525f7"
}'

三件事一定要記住：

1. source_lang 必填。官方原文寫得很直白：術語表還不能搭配自動來源語言偵測。平常靠 auto detect 的人，這裡一定會踩到——回傳不會報錯，只是術語表默默沒生效。
2. 術語表管理走 v3、翻譯還是走 v2。官方明講：v3 端點只管術語表的建立與維護，翻譯本身留在 v2。看到 v3 就以為翻譯端點也要換，會找不到路徑。
3. 語言對要對得上。術語表的語言對必須和請求的語言對相符；另外 glossary_id 不能和 glossary_ids（一次最多 5 個）同時使用。

五、改、查、刪：PUT 和 PATCH 語意不一樣

v3 相對 v2 最大的價值就是可以改（v2 的術語表是不可變的，只能刪掉重建）。但兩個修改端點的行為完全不同，用錯會刪掉你不想刪的東西：

一句話記法：要加詞用 PATCH（合併），要整批換掉用 PUT（取代）。官方也註明：一次 PUT 或 PATCH 只能動一個字典，要跨多個語言對改同一個詞，就得一個字典呼叫一次。

查詢與刪除：

• GET /v3/glossaries：列出全部術語表與各字典的中繼資料（不含條目）
• GET /v3/glossaries/{id}/entries：取單一字典的條目，用 source_lang、target_lang 查詢參數指定；目前只回 TSV 格式
• DELETE /v3/glossaries/{id}：刪整個術語表
• DELETE /v3/glossaries/{id}/dictionaries?source_lang=...&target_lang=...：只刪一個字典

一個會咬人的相容性陷阱：官方警告不要在同一個整合裡混用 v2 與 v3。術語表一旦用 v3 編輯過，v2 端點就無法正確查詢它；為了避免資料遺失，這種術語表用 v2 刪除是被停用的，只能走 v3 的刪除端點。

六、五個會讓條目被靜默忽略的格式規則

這一節是實際會出事的地方——條目寫錯通常不會噴錯，只是那條規則不生效，你以為設定好了。官方限制清單裡的重點：

1. 不能有重複的來源詞，來源或目標也不能留空。
2. 不能含控制字元（詞彙內部不能有 \t、\n）、不能有 Unicode 換行、不能有前後空白。從試算表複製貼上時最容易帶到尾端空白。
3. CSV 欄位含逗號或雙引號時要用雙引號包起來，欄位內的雙引號要寫兩次跳脫。TSV 規則相同，只是分隔符改成 Tab。
4. CSV 可在詞彙後面附加來源／目標語言欄位；語言和該字典語言對不符的條目會被忽略——被忽略，不是報錯。
5. 大小限制：每個字典的條目最多 10 MB，一個含五個字典的術語表最多 50 MB；術語表名稱、每個來源詞、每個目標詞各自上限 1024 UTF-8 位元組。

七、帳號能放幾個術語表？依方案而定

這是最容易被二手文章寫錯的一項。本次查核到的兩組數字，性質不同，別混在一起看：

• API 端：v2 術語表端點文件寫「每個帳號允許 1,000 個術語表」；但 v3 的管理文件對數量只寫一句「每個帳號的術語表數量由你的方案決定」，並把讀者導回官方 API 方案頁。
• DeepL 翻譯器（網頁／App）端：官方方案頁 2026-09-03 直讀顯示，免費版每月 50,000 字元、1 個術語表；Individual 為每月 300,000 字元、1 個術語表；Team 為每人每月 1,000,000 字元、5 個術語表；Business 與 Enterprise 標示為不限術語表數量。

這兩套額度是分開的：翻譯器方案的術語表額度，不等於 API 金鑰能用的術語表數量。要用 API 就看 API 方案。

八、這篇查不到、不寫死的部分

• API 各方案（Free／Developer／Growth）現行的字元額度、月費與術語表數量上限：官方 API 定價區塊是動態載入，本次以純文字方式直讀沒有取得價格數值，因此本文不列 API 價格，一律待查核。站上工具頁另有一則來源標示為第二手、未經官網確認的紀錄（「2026 年 7 月起 API Free 與 API Pro 停售、改導向 Developer 或 Growth」），在拿到官網一手畫面之前，請當成未確認的線索、不要當事實引用。
• 官方支援術語表的語言總數：v2 端點文件列出的清單與現行支援語言表不完全一致（前者敘述含泰文、後者的術語表旗標未涵蓋）。本文只採用逐語言的支援旗標這一組資料，總數不寫死。
• 免費 API 金鑰目前是否仍開放新申請：官方 API 頁面上仍存在「Free API Key」的註冊連結（productId=api-developer），但本次未實際完成註冊流程驗證，不宣稱一定申請得到。

九、動手順序（照這個走不會卡）

1. 先查你的語言在不在支援清單，並取根代碼（繁中＝zh）。
2. 用 POST /v3/glossaries 建表，目標語言填根代碼，記下 glossary_id。
3. 翻譯時 target_lang 才填 ZH-HANT，並且務必帶 source_lang。
4. 跑一段含目標詞的真實句子驗收——沒生效多半是漏了 source_lang，或條目帶了尾端空白。
5. 之後加詞用 PATCH、整批換用 PUT；整個專案只用 v3，不要和 v2 混。

官方連結

• 術語表管理（v3 端點、本文指令來源）：https://developers.deepl.com/docs/customize/managing-glossaries
• 語言變體的客製化（根代碼對照表來源）：https://developers.deepl.com/docs/customize/customizations-for-variants
• v2 與 v3 端點差異：https://developers.deepl.com/docs/customize/glossary-v2-vs-v3-endpoints
• 支援語言（術語表支援旗標來源）：https://developers.deepl.com/docs/getting-started/supported-languages
• 翻譯端點參數（glossary_id 條件）：https://developers.deepl.com/api-reference/translate/request-translation

延伸閱讀

• DeepL 工具頁（方案與免費額度查核紀錄）
• DeepL 方案與價格實查
• Gemini API 帳單先砍一半：Batch 與快取的實際開法
• 免費 AI API 額度比較：Groq、OpenRouter、Google