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

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 等）。
Prefer translator notes over “fixing” code logic—flag issues to maintainers instead.

Code Blocks and Inline Code

Keep code fences, language hints, and content intact. Translate only comments and human‑readable strings if required.

Example—safe vs unsafe:

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

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

Inline code must stay verbatim:

Good: “Run npm install -g acme-cli and then acme login.”
Bad: “Run npm install -g acme-cli and then acme connexion.” ❌

Validate copy‑pasteability: If a reader copies any snippet, it should run as in the source.

Placeholders and ICU MessageFormat

Preserve placeholders exactly, including spacing and punctuation around them.

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

ICU example:

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

Do not change keys (count, one, other).
Translate only the human‑readable parts (“message”, “messages”).
Do not introduce or remove plural categories without product guidance.

Links, Anchors, and Slugs

Keep Markdown link syntax and resolve strategy consistent.

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

Translate link text if needed; be cautious with URLs and anchors.
Anchors: either keep stable anchors across locales or generate per‑locale anchors and update references accordingly.
Verify relative paths and hash anchors still resolve after translation.
Do not translate file extensions or query params.

Structured Data (JSON/YAML/TOML)

Translate values only—never keys, types, or structure. Always re‑parse after editing.

JSON:

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

Keys like title, cta, limits, max must remain unchanged.
Numbers, booleans, and nulls stay as types, not words.

YAML (watch folded scalars):

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

Preserve quoting, escapes, indentation, and trailing commas (where applicable).

Filenames, CLI, and API Names

Do not translate filenames, package names, endpoints, or CLI flags.
Keep case sensitivity exactly as in source (e.g., --DryRun vs --dry-run).
Maintain commands verbatim; add callouts if locale‑specific differences exist.

# 正確
kubectl get pods --namespace default

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

Markdown Gotchas

Tables: keep pipes and alignment; do not break columns.

| 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 項）

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