如何翻譯技術文件而不破壞程式碼

TABLE OF CONTENTS

技術文件容不得疏忽：一個破損的程式碼框、佔位符或錨點都可能導致建置失敗、讀者困惑，甚至複製貼上出錯。本指南為你提供一套可重複、安全的工作流程，讓你自信地翻譯技術文件——同時保持程式碼完整、文件可發佈。

適用對象：技術寫手、開發者推廣人員，以及負責開發者文件、API 指南、README 類內容的翻譯人員。

快速總覽：

明確哪些內容絕對不能翻譯（程式碼、鍵值、令牌）
保留工具解析的語法（程式碼框、括號、錨點）
編輯後驗證結構化資料與連結
利用自動化工具在發佈前捕捉問題

翻譯前準備

盤點內容類型

Markdown（標題、連結、表格）、程式碼區塊、行內程式碼
結構化資料：JSON/YAML/TOML 片段與設定檔
截圖、圖表及嵌入式視覺內容

定義不可翻譯的標記

檔案路徑、套件名稱、匯入語句、API 名稱、CLI 旗標、環境變數
佔位符與變數：{count}、%s、$HOME、{{token}}
檔名與副檔名：config.yaml、.env、.md、.json

建立一致性防線

專業術語與產品名稱詞彙表／術語庫
風格指南：語調、正式度、標點、大小寫、標題規則
每個語系的錨點／slug 策略（穩定或本地化）

建立安全驗證機制

分批後以預發佈建置驗證 Markdown／連結
JSON/YAML/TOML 使用解析器／語法檢查工具
CI 中執行連結檢查與錨點驗證

核心防護措施

不要翻譯程式碼、識別符、鍵值、檔名、環境變數或旗標。
保留工具解析的標點與語法（反引號、括號、管線符）。
保持重要的空白：程式碼與清單結構的縮排。
一致使用帶語言標籤的程式碼框（js、bash 等）。
優先使用譯者註釋而非「修正」程式碼邏輯——如有問題請標記給維護者。

程式碼區塊與行內程式碼

保留程式碼區塊、語言提示和內容不變。僅在需要時翻譯註解和可讀字串。

範例—安全與不安全：

// 安全：僅本註解已本地化
// 取得使用者權杖
import { getToken } from "@acme/sdk";
const token = await getToken();

// 不安全：請勿翻譯識別字、import、套件名稱
// import { obtenirJeton } from "@acme/sdk"; // ❌

行內程式碼必須保持原樣：

正確：「執行 npm install -g acme-cli，然後 acme login。」
錯誤：「執行 npm install -g acme-cli，然後 acme connexion。」 ❌

請確認可複製性：讀者複製任何片段後，應能如原文執行。

佔位符與 ICU MessageFormat

請完全保留佔位符，包括其周圍的空格與標點。

# 不要更動標記或空格
echo "Processing {count} files"   # ✅
echo "Processing { count } files" # ❌ 在大括號內新增空格

ICU 範例：

{count, plural,
  =0 {No messages}
  one {# message}
  other {# messages}
}

不要更動鍵值（count、one、other）。
僅翻譯可讀部分（「message」、「messages」）。
未經產品指示，請勿新增或刪除複數分類。

連結、錨點與 Slug

保持 Markdown 連結語法與解析策略一致。

[閱讀 API 指南](/api/getting-started)  
[參見設定區段](#configuration)

如有需要，翻譯連結文字；對 URL 與錨點要謹慎處理。
錨點：可維持跨語言穩定錨點，或依語言生成並同步更新參照。
請確認相對路徑與 hash 錨點在翻譯後仍可正確解析。
不要翻譯檔案副檔名或查詢參數。

結構化資料（JSON/YAML/TOML）

僅翻譯值—絕不更動鍵、型別或結構。編輯後務必重新解析。

JSON：

{
  "title": "使用者指南",
  "cta": "立即開始",
  "limits": { "max": 5, "unit": "requests/second" }
}

像 title、cta、limits、max 這類鍵名必須保持不變。
數字、布林值和 null 必須維持原本型態，不要翻譯成文字。

YAML（注意折疊標量）：

note: >
  行會折疊成單一段落。
  保持縮排和標記不變。

保留引號、跳脫字元、縮排，以及結尾逗號（如適用）。

檔名、CLI 和 API 名稱

不要翻譯檔名、套件名稱、端點或 CLI 旗標。
保持大小寫完全與原文一致（例如 --DryRun 與 --dry-run）。
指令必須原文呈現；如有地區差異可加註說明。

# 正確
kubectl get pods --namespace default

# 錯誤（旗標被翻譯） ❌
kubectl get pods --nom-espace defaut

Markdown 注意事項

表格：保持管線符號與對齊，不要拆分欄位。

| Option | Description           |
|-------:|-----------------------|
|   -v   | Verbose output        |
|   -q   | Quiet mode            |

提示/註記：保留工具所用的標記。
行內 HTML：避免修改標籤或屬性。
腳註：保留 id 與順序。
智慧引號：在程式碼內容中優先使用直引號。

視覺與無障礙

圖片 alt 文本請翻譯其意義，不要只描述像素內容。
優先使用語言無關的螢幕截圖（突出 UI 而非語言），或提供各語系版本。
保持圖表原始檔（如 Mermaid）在各語系間同步。
避免圖片內嵌文字；將標題與標籤外部化。

SEO 與中繼資料

使用符合在地搜尋習慣的關鍵字翻譯標題、描述與標頭。
保持 canonical URL 與 hreflang 依網站規則一致。
不要翻譯 meta/property 鍵名或 JSON‑LD 鍵名。
依你的錨點策略調整 slug，避免 404。

工作流程與自動化

使用能保留程式碼區塊與標籤的 CAT/LLM 工作流程。
透過詞彙表與禁止翻譯清單鎖定專業術語。
新增 pre-commit hooks 來檢查 Markdown 格式並驗證 JSON/YAML。
每個 PR 執行連結檢查與錨點驗證。
變更分批提交，保持小而易於審查，並追蹤差異。

建議工具（可依你的技術棧調整）：

在 CI 中執行 Markdown 格式檢查與連結檢查
加入 JSON/YAML 解析步驟以捕捉語法回歸
使用正則表達式套件掃描佔位符與數字格式

品質保證與驗證

合併前請執行以下檢查：

建置網站以捕捉語法錯誤：pnpm build
型別／內容檢查（Astro 內容集合）：pnpm astro check
預覽並抽查重點頁面：pnpm preview
驗證程式碼範例可編譯或執行（如適用）
執行連結與錨點檢查，修正所有 404 或失效錨點

常見陷阱

不小心翻譯了鍵名或佔位符。
破壞了程式碼區塊或表格分隔符。
在地化了檔案路徑、旗標或 API 名稱。
修改標題卻未同步更新錨點連結。
在程式碼或 JSON 內引入智能引號。

附錄：快速檢查清單

前置檢查（5 項）

詞彙表與禁止翻譯清單已備妥
標記／佔位符已定義並受到保護
錨點／slug 策略已確認
連結目標已對應（內部／外部）
測試環境建置可用

程式碼範例安全（5 項）

程式碼區塊與語言提示完整
識別字／匯入未變動，僅本地化註解
佔位符與引號皆保留
複製貼上測試通過
過時片段已標註給維護者

結構化資料（5 項）

鍵名與型別未變動
引號／跳脫字元／縮排皆保留
數字與布林值型別不變
本地解析器／檢查工具通過
差異檢查，避免誤改鍵名