如何翻譯 Markdown

Markdown 已成為技術文件、README 檔案以及部落格文章的事實標準，因其易讀性與可攜性。然而，當內容需要面向多語言受眾時，翻譯 Markdown 並不像翻譯純文字那麼直接。Markdown 結合了人類可讀的文本與格式語法（例如用 # 表示標題、反引號標示程式碼、方括號標示連結），若處理不當，容易導致文件格式錯亂。本指南將說明 Markdown 翻譯的難點、提出一般建議、調查現有工具與方法，並以實用技巧作結，助你打造成功的多語言文件。

為什麼翻譯 Markdown 充滿挑戰

與純文字不同，Markdown 檔案包含格式指令、程式碼片段、連結，有時甚至嵌入 HTML。多項因素讓翻譯變得複雜：

語法保留
Markdown 仰賴特定字元與模式來進行格式化。例如將 ## Heading 翻譯為 ## 標題 沒問題，但若不小心移除 ##，整個格式就會崩壞。

程式碼與技術內容
程式碼區塊、行內程式碼片段、變數名稱通常應保持原樣。若將函式名稱 getUserData() 錯誤翻譯為 obtenirDonnéesUtilisateur()，程式碼就會失效。

工具相容性
電腦輔助翻譯（CAT）工具對 Markdown 的匯入與匯出方式各異。設定不當可能會翻譯程式碼區塊或破壞文件結構。專家建議先詢問技術寫作者哪些部分需要翻譯——註解、行內程式碼、嵌入 HTML——並為 CAT 工具選擇合適的過濾器，避免盲目機器翻譯。

機器翻譯風險
自動系統可能會誤翻譯程式碼、改動表情符號，或留下格式殘跡。處理後必須檢查是否有段落被跳過，以及格式是否完整無誤。

常見翻譯錯誤

錯誤類型	範例	影響
語法錯誤	**bold text*（缺少結尾的 *）	無法正確顯示
翻譯了程式碼	function getData() → función obtenirDatos()	程式碼無法運作
連結損壞	[link](url) → [link] (url)（多了空格）	連結失效
遺失佔位符	{{username}} → {{nom d'utilisateur}}	動態內容無法顯示

一般建議

在開始任何 Markdown 翻譯專案之前，請遵循以下準備步驟：

1. 翻譯前先釐清範圍
   請向技術寫手或內容負責人確認哪些元素需要翻譯。通常使用者介面文字需要翻譯，而程式碼區塊、變數名稱及技術識別符則應保持英文。將這些決策記錄下來，以便維持一致性。

2. 選擇合適的工具與過濾器
   挑選專門支援 Markdown 的翻譯工具。許多 CAT 工具都提供 Markdown 過濾器——請設定以保留結構並跳過不需翻譯的區段。在處理大量文件前，先用小型樣本檔案測試流程。

3. 謹慎使用機器翻譯
   若採用自動翻譯，請仔細檢查程式碼片段與嵌入標籤。設定翻譯前規則，保護程式碼區塊及行內程式碼不被修改。

4. 確認完整性與格式
   翻譯後，請在標準 Markdown 編輯器或渲染器中檢查輸出結果。確認標題、清單、連結、圖片及程式碼區塊皆正確顯示。將兩種語言的渲染結果比對，找出格式差異。

翻譯 Markdown 的工具與方法

AI 驅動的翻譯平台

AI 翻譯工具在處理像 Markdown 這類結構化格式時有顯著進步，成為技術文件翻譯日益受歡迎的選擇。

OpenL Markdown Translator

OpenL 的 Markdown Translator 專為 Markdown 及類似文件格式設計。它在翻譯內容時，能出色地保留檔案結構、程式碼區塊、清單及格式元素。

主要特色：

• 支援超過 100 種語言
• 三步驟流程：上傳 Markdown 檔案、選擇目標語言、下載翻譯後文件
• 自動保留標題、項目符號清單、表格與程式碼框
• 處理多種檔案類型，不僅限於 Markdown（PDF、DOCX、PPTX、XLSX、CSV、EPUB、SRT）
• 具備理解文化細節的情境感知 AI 引擎
• 專業級翻譯品質，原始格式完整保留

最佳應用場景：

• 需要格式一致的技術文件
• 多語言知識庫
• 需支援多種檔案格式的專案
• 追求簡單流暢工作流程的團隊

該平台能處理各種文件格式，特別適合在翻譯包含多種檔案類型的完整文件集時使用，極為便利。

翻譯編輯器

專業翻譯編輯器為處理 Markdown 的人工翻譯人員提供專業級功能。

SimpleLocalize
這款翻譯編輯器將每個 Markdown 檔案視為「翻譯鍵」。流程包括建立專案、新增目標語言、上傳 Markdown 檔案、將編輯器類型設為 Markdown，並在分割視窗中翻譯內容。功能包含行號、占位符保留及原文檢視。

Phrase（前身為 Memsource）
支援 Markdown 並可自訂匯入過濾器。你可以設定哪些元素要翻譯、哪些要保護，適合需要人工審核的複雜技術文件。

在地化服務

Simpleen
提供網頁介面或 API，您可以註冊帳號，選擇預設的 Markdown 翻譯器，並上傳檔案。該工具在翻譯內容的同時，會儲存片段以便日後編輯，並維護翻譯記憶庫，確保多份文件的一致性。

Crowdin
是一個協作式本地化平台，能夠處理 Markdown 檔案並保留上下文。它允許多位翻譯人員同時作業，並為文件專案提供版本控制。

格式轉換方法

另一種方式是將 Markdown 轉換為中介格式進行翻譯，然後再轉回 Markdown。

Pandoc + CAT 工具工作流程：

1. 使用 Pandoc 將 Markdown 轉換為 HTML 或 XML：pandoc input.md -o output.html
2. 在您偏好的 CAT 工具中翻譯 HTML/XML
3. 再轉回 Markdown：pandoc output.html -o translated.md

這種方法適合既有的翻譯工作流程，但需要驗證來確保來回轉換不會產生錯誤。

Smartling 方法
像 Smartling 這類平台會自動將 Markdown 轉換為 HTML 進行翻譯，然後再轉回 Markdown，內部自動處理複雜流程。

工具比較矩陣

方法	適用對象	複雜度	速度	學習曲線
AI 平台（OpenL、DeepL）	快速翻譯並保留格式	低	非常快	低
翻譯編輯器（SimpleLocalize、Phrase）	人工審核翻譯與品質控管	中	中	中等
本地化服務（Crowdin、Simpleen）	團隊協作、大型文件集	中	中	中等
格式轉換（Pandoc 工作流程）	與既有 CAT 工具整合	高	慢	高
開源工具（i18next-parser）	自動化 CI/CD 流程	高	快	高

Markdown 翻譯最佳實踐

格式保留

請完全維持原文的所有結構元素：

• 標題（#, ##, ###）
• 清單（有序與無序）
• 粗體（**文字**）與斜體（*文字*）
• 連結（[文字](網址)）
• 圖片（![替代文字](路徑)）
• 程式碼區塊（```語言 與行內 `程式碼`）
• 表格與水平線

占位符管理

保持占位符與動態內容不變：

• 變數：{{username}}、${variable}
• 模板語法：{% include file.md %}
• 自訂短碼：{{% note %}}

這些元素必須維持原始形式，以確保在目標語言中正常運作。

品質保證檢查清單

翻譯後，請確認：

• 所有連結皆可正常運作並指向正確資源
• 圖片顯示正常（如有需要請更新圖片路徑）
• 程式碼區塊能正確呈現並具備語法高亮
• 編號清單順序正確
• 表格對齊正確且易於閱讀
• 沒有多餘空格破壞 Markdown 語法
• 前置資料（YAML/TOML）保持有效
• 特殊字元在目標語言中正確顯示

工作流程最佳化

針對大型文件專案：

• 使用行號追蹤長檔案的進度
• 建立術語表以統一技術詞彙與產品名稱
• 建立翻譯記憶庫以維持一致性
• 設置自動驗證腳本以捕捉格式錯誤
• 將翻譯檔案與原始檔案一同進行版本控制

針對持續性文件維護：

• 建立明確流程以便在原文內容變更時更新翻譯
• 使用差異工具辨識版本間的變動
• 考慮與 CI/CD 整合的持續在地化（l10n）工作流程

進階考量

Markdown 變體

請注意，不同的 Markdown 標記語言有其獨特功能：

• CommonMark - 嚴格規範，兼容性最高
• GitHub Flavored Markdown (GFM) - 增加表格、任務清單、刪除線等功能
• MDX - 支援 JSX 元件，常見於 React 文件

請確保您的翻譯工具支援您文件所使用的特定 Markdown 變體。

自動化與 CI/CD 整合

適用於維護多語言文件的技術團隊：

# 工作流程範例概念
# 1. 偵測原始 Markdown 檔案的變更
# 2. 擷取可翻譯內容
# 3. 傳送至翻譯 API
# 4. 驗證翻譯結果
# 5. 建立包含翻譯的 pull request

常用的自動化工具包括：

• 搭配 Markdown 外掛的 i18next
• 文件網站專用的 Docusaurus i18n
• 使用 OpenL 或 DeepL 等翻譯 API 的 自訂腳本

文化調適

翻譯不僅僅是語言轉換：

• 依目標文化調整範例（貨幣、姓名、地點）
• 考慮右至左語言（如阿拉伯語、希伯來語）的閱讀方向
• 根據目標受眾調整語氣與正式程度
• 檢查圖片與截圖是否符合文化適宜性

選擇合適的方式

當符合以下情況時，請使用 AI 平台（如 OpenL Markdown Translator）：

• 需要快速產出技術文件
• 必須保留複雜格式
• 同時處理多種檔案格式
• 預算允許專業級自動翻譯
• 內容量大且經常更新

當符合以下情況時，請使用翻譯編輯器：

• 需要人工翻譯審核與確認內容
• 與專業翻譯團隊合作
• 品質與語言細緻度比速度更重要
• 翻譯行銷或客戶導向內容

當符合以下情況時，請使用在地化服務：

• 多方協作翻譯需求
• 需要內建翻譯記憶庫與詞彙管理
• 管理多專案、多語言的翻譯
• 需要具備審核流程的自動化工作流程

建議使用格式轉換的情境：

• 你已經有既定的 CAT 工具工作流程
• 需要將 Markdown 翻譯整合進現有的在地化流程
• 與不直接支援 Markdown 的翻譯代理商合作

建議使用開源自動化的情境：

• 你有開發資源可以打造自訂解決方案
• 需要與版本控制和部署流程緊密整合
• 希望完全掌控翻譯流程
• 預算有限但具備技術專長

結論

Markdown 的翻譯不僅僅需要語言能力——還必須兼顧文件結構、技術準確性與格式一致性。工具的選擇取決於你的實際需求：像 OpenL Markdown Translator 這類 AI 驅動的平台，能為技術內容帶來速度與格式保留；而以人工為主的工具則能為面向客戶的內容提供更細緻的品質。

建議先評估你的專案需求：內容量、更新頻率、品質標準以及可用資源。對於大多數技術文件專案，混合式方法最為有效——先用 AI 翻譯快速產出初稿，再由人工審核把關品質與文化適應。

在大規模翻譯前，先用小樣本測試你的工作流程。記錄你的流程，包括工具設定、品質檢查與經驗教訓。當你擴展到更大規模的文件集時，考慮導入自動化以維持一致性並減少人工操作。

無論你選擇專業平台、翻譯編輯器還是自訂自動化方案，關鍵都在於效率與品質的平衡。只要結合合適的工具與細心的監督，就能在多語言間維持高品質的 Markdown 文件，同時保有 Markdown 在技術內容中最重要的清晰結構與表達力。