adventure-table

M02 — 實作規格

Phase：M02 — Traditional Chinese / English Localization
類型：M Phase（Modification / Maintenance Phase）
插入時點：M01-C — SCAG / GoS Background Expansion closeout 後，暫停 M01；M02 closeout 後回到 M01-D。
本文件定義 M02-A～M02-H 每個 Subphase 完成後什麼必須為真。具體資料格式、module、API、locale resource layout、translation authoring pipeline、migration 與接線放在 開發設計方針.md；自動與人工驗收方式放在 測試指南.md。

狀態：M02 已 closeout（2026-08-31）。M02-A～M02-H 全部完成，下一步為 M01-D。 Closeout evidence：M02-C_CLOSEOUT.md、M02-D_CLOSEOUT.md、M02-E_CLOSEOUT.md、M02-F_CLOSEOUT.md、M02-G_CLOSEOUT.md、M02-H_CLOSEOUT.md。

最後更新：2026-08-31

1. M02 定位

P0 / P1 已完成 Character Core、Character Builder、Character Sheet、Version History 與 SRD 5.1 Character Content；M01-A～M01-C 進一步建立 Multi-Source Content Pack，並加入 PHB / SCAG / GoS Character Origins / Background content。

在繼續 M01-D～M01-I 大量加入 VGM / VRGR / TCE 內容前，M02 先建立永久的雙語基礎，避免之後每新增一批規則資料都累積 English-only presentation debt。

M02 要解決的是：

  1. 網站目前 UI 文案同時存在英文、繁中與混合顯示。
  2. Content Registry、Builder DTO、Character Sheet / Review 等既有流程會直接傳遞 name / label / desc 等 presentation text，尚未有正式 locale contract。
  3. 第一版語言功能支援兩個純語言模式：繁體中文（zh-TW）與 English（en）。
  4. 語言切換必須即時完成，不重新載入頁面，不改變 Builder Draft / Character / Current State。
  5. 語言選擇只屬於瀏覽器 presentation preference，必須在下次開啟網站時沿用。
  6. M02 closeout 當下，所有已存在產品畫面會顯示的 system / rules presentation fields 必須具有完整的 zh-TW / en coverage。
  7. M02 完成後，後續 M01-D～M01-I 與其他 Phase 新增或首次 expose 的 user-visible system / rules content，都必須在該 Subphase 內同步提供所有正式支援語言。

M02 不改寫正常 P0 → P1 → P2 Roadmap，也不取消 M01-D～M01-J：

M01-A
→ M01-B
→ M01-C
→ 暫停 M01
→ M02-A～M02-H
→ M02 closeout
→ 回到 M01-D
→ M01-E～M01-J
→ P2

2. M02 第一版產品行為

2.1 只支援兩個 locale

M02 第一版正式 locale：

zh-TW — 繁體中文
en    — English

第一版不做：

2.2 純語言模式

繁中模式：所有納入 localization scope 的系統 UI、規則名稱、規則說明、系統提示與系統提供文字使用繁體中文。
English mode：所有納入 localization scope 的系統 UI、規則名稱、規則說明、系統提示與系統提供文字使用英文。

正常使用流程不得出現可避免的中英混合 presentation，例如：

種族：Wood Elf
背景：Guild Artisan
法術：Fireball

或：

Race：木精靈
Background：公會工匠

下列內容不視為語言混用缺陷：

2.3 切換行為

語言切換必須：

切換完成後，使用者不應觀察到持續性的「一部分已切換、一部分仍是上一語言」狀態。

2.4 瀏覽器記憶

locale preference 保存於目前瀏覽器。

要求：

3. Localization 共通硬原則

3.1 Rules identity 與 display language 完全分離

Canonical identity 永遠使用既有 StableKey，例如：

srd5.1:spell:fireball
phb2014:subrace:wood-elf
scag:background:city-watch
gos:background:marine

切換 locale 不得改變：

Display Name 永遠不是 foreign key，也不得因翻譯不同建立第二個 rules entity。

3.2 Localization 是 presentation，不是第二套規則資料

M02 必須維持：

同一份 mechanics / identity
→ en presentation
→ zh-TW presentation

不得建立兩份會各自演化的 mechanics content，例如：

srd5.1-en
srd5.1-zhTW

不得讓英文版與中文版具有不同 eligibility、choice、數值、grant、reference graph 或 Build 結果。

3.3 Server authoritative rules 不變

M02 只改 presentation 能力，不把 rules legality 搬進 frontend。

既有流程仍為：

Builder Draft
→ server choices / compile / validation
→ Review
→ Confirm
→ immutable CharacterBuild / Current State

同一 Draft 在 zh-TW 與 en 下，除 presentation text 外，所有 machine-readable result 必須相同。

3.4 Locale 不屬於 Draft / Build / State

第一版 locale 是 browser preference，不是遊戲狀態。

禁止把 locale 寫入：

因此切換語言不能造成 autosave、revision bump、new version 或 state write。

3.5 系統文字與使用者文字分離

M02 必須區分：

System-authored / rules-authored text：依 locale 切換。
User-authored free text：保持使用者原文，不自動翻譯、不在切換時重寫。

例如：

若系統提供的 suggestion 需要在選取後仍保有「可隨 locale 切換」的語意，必須保存可辨識的 system identity，而不是只把某一語言的 display string 當唯一身份。

既有已保存且沒有 system identity 的自由文字不得用字串比對、猜測或機器翻譯方式偷偷改寫。

3.6 Translation fallback 不可掩蓋缺漏

M02 closeout 後，正式支援的 zh-TW / en 不得以「缺繁中就顯示英文」作為正常 production 行為。

缺 required translation 必須：

3.7 Glossary 是翻譯標準，不是 runtime replace engine

M02 必須建立一致的 D&D 5e 2014 翻譯術語規則，用來約束核心術語與專有名稱。

docs/暫用規則資訊/ 既有繁中譯名是 glossary 的優先參考輸入。M02-C 定稿時必須逐一比對本次實際使用到的既有名稱；若決定採用不同譯名，必須在 glossary 記錄原參考譯名、正式採用譯名與決策原因。

M02 closeout 後：

glossary = 正式 zh-TW terminology SSOT
docs/暫用規則資訊/ = maintainer reference / legacy reference

不得讓兩者各自成為平行翻譯主來源，也不得靠 regex / global string replacement 把長篇規則文字機械替換成翻譯。

3.8 Localizable field policy 是翻譯範圍 SSOT

M02 不以「整個 category 是否存在」決定翻譯範圍，而以 field-level product visibility 決定。

M02-C 必須產出可機器驗證的 localizable field policy。某個 canonical field 在 M02 closeout 是否 required，判準為：

當且僅當該 field 在 M02 closeout 當時已存在的產品畫面／正常使用流程中會被顯示給使用者。

因此同一 category 可以同時存在：

例如現有 Character Sheet Inventory selector 已會列出 SRD magic item 名稱，因此 item.name 屬 M02 required；若 item.desc 在 M02 closeout 時仍沒有任何產品畫面顯示，則不因 item category 已存在而強迫提前翻譯。

Monster / Beast 仍依既有 P0 scope guard 延後，不因 M02 提前導入 P4 content。

4. M02 closeout 內容邊界

M02 插入時點固定在 M01-C closeout 後。

M02 closeout 當時正式 enabled packs：

srd5.1
phb2014
scag
gos

但「pack enabled」不代表該 pack 每個自然語言 field 都必須提前翻完。實際 required coverage 由 M02-C 的 localizable field policy 決定。

4.1 SRD 5.1

SRD 5.1 的 required translation scope 為：

M02-C localizable field policy
× srd5.1 runtime entries
× zh-TW / en

名稱、selector label、grant summary、目前頁面實際顯示的 structured text 與長文，只要被 policy 標成 user-visible 就必須完整雙語。

尚無 UI surface 的 SRD field 不納入 M02 completeness；未來某個 Subphase 首次讓該 field 成為 user-visible 時，由該 Subphase 一併補齊所有 supported locale。

4.2 PHB / SCAG / GoS

M01-B / M01-C 正式導入的 non-SRD content 同樣依 field policy 判斷 required scope，包括目前會出現在 selector / Review / Sheet / roleplay editor 的：

PHB / SCAG / GoS 的 zh-TW 名稱與既有翻譯內容，以對應 docs/暫用規則資訊/ 文件作為初稿／優先參考來源，再由 M02-C glossary 統一審核定稿。

4.3 M02 後的永久承接規則

M02 closeout 後恢復 M01-D 時：

任何 Subphase 新增、修改，或因新增畫面而首次 expose user-visible system / rules content，必須同步維護所有正式支援 locale；缺少 zh-TW 或 en 視為該 Subphase 未完成。

因此未來 VGM / VRGR / TCE content 的翻譯不再另開「補翻譯 Phase」，而是內容／畫面本身 Definition of Done 的一部分。

5. M02 Subphase 順序

三份 M02 文件固定使用以下名稱與順序：

M02-A — Locale Foundation & Runtime Switch
M02-B — Full UI Copy Localization
M02-C — Localized Content Model & Terminology Contract
M02-D — SRD 5.1 Names & Structured Text
M02-E — SRD 5.1 User-Visible Descriptions
M02-F — PHB / SCAG / GoS Localization
M02-G — Localized Search, Errors & Completeness Gates
M02-H — Full M02 Integration & Closeout

每個 Subphase 必須可獨立實作、驗證、commit；完成時專案必須保持可啟動、可 build、可測試，不得用「等下一個 Subphase 才修」作為已知 regression 的理由。

翻譯資料量可以在單一 Subphase 內依 category 分批產出、review、commit；batch completion 不等於 Subphase closeout。D / E / F 各自完整 scope 未完成前不得宣告該 Subphase 關門。

M02-A — Locale Foundation & Runtime Switch

目標

建立全站唯一 locale runtime state，完成 zh-TW / en 一鍵切換、即時 rerender 與瀏覽器記憶，且證明 locale 與 Draft / Character domain state 完全分離。

完成後必須為真

  1. 全站存在一致、容易找到的語言切換控制。
  2. 可在 zh-TW 與 en 間一鍵切換。
  3. 切換不做 full page reload。
  4. 切換後仍停留在相同 URL、相同功能頁與相同工作位置。
  5. locale preference 保存於瀏覽器，reload / reopen 後沿用。
  6. 無既存 preference 時預設 zh-TW。
  7. page language / accessibility metadata 能反映目前 locale。
  8. locale runtime state 可供全站 UI 與後續 content presentation 共用，不允許每個 feature 自己維護第二份 locale state。
  9. 切換 locale 不修改 Draft payload、Draft revision、Character Build 或 Current State。
  10. 在 Builder 中連續切換語言，不得觸發 Draft PATCH / autosave。
  11. locale state 本身失效或出現未知值時，系統可回到受支援的安全預設，不會破壞頁面。

本 Subphase 不要求

M02-B — Full UI Copy Localization

目標

把目前網站所有 frontend-owned UI copy 正式納入 localization，不再由 React component 到處散落不可切換的英文／中文 literal。

翻譯範圍

至少涵蓋目前既有：

完成後必須為真

  1. zh-TW 模式中，frontend-owned natural-language UI copy 只顯示繁中。
  2. en 模式中，frontend-owned natural-language UI copy 只顯示英文。
  3. 同一頁即時切換時，所有 frontend-owned UI copy 同步更新。
  4. 不以 duplicated page/component 的方式維護兩套 UI。
  5. UI 翻譯不影響 navigation、form value、selection、Draft save 或 validation semantics。
  6. Button / label 因兩語長度差異不得造成主要操作不可見、文字重疊或基本 responsive regression。
  7. Source abbreviations / D&D notation 可依共通規則保留，但其周邊句子必須使用當前 locale。

本 Subphase 不包含

Server / Content Registry 產生的 rules names / descriptions；這些由 M02-C～F 接管。

M02-C — Localized Content Model & Terminology Contract

目標

建立正式 rules-content localization contract，讓 StableKey / mechanics 與 display language 分離，同時定稿「哪些 field 現在真的需要翻譯」與正式 D&D terminology。

完成後必須為真

C.1 Stable identity 不受 locale 影響

同一 content entry 在兩語下具有相同 StableKey、source / pack identity、references、choices / grants semantics 與 mechanical data；只有 presentation 改變。

C.2 Rules presentation 可按 locale resolve

所有正式 Content Registry entry 與可見 nested rules presentation，都有一致方式取得目前 locale 對應的 name / short label / description / choice presentation / source label / user-visible structured text。

C.3 Server-generated presentation 不再綁死單一語言

Builder / Review / Character Sheet 等 server-derived view 若包含 user-visible name / label / message / description，必須能依正式 locale contract 呈現，不能永久把英文 display string 當 domain identity。

Machine-readable code / reference / id 保持語言中立。

C.4 Localizable field policy

產出正式、可機器驗證的 field-level policy，能回答至少：

pack / kind / field
→ user-visible now?
→ required locales
→ reason / surface

M02-D / E / F / G completeness 必須以此 policy 為準，不得各自再維護一份手工 category 清單。

C.5 Terminology glossary

建立 D&D 5e 2014 en ↔ zh-TW glossary。docs/暫用規則資訊/ 的既有繁中譯名必須作為 priority reference input；不同譯名決策要留下對照與理由。

C.6 System suggestion 與 free text boundary

Background / roleplay 等 system suggestion 必須能依 locale 顯示；若採用後仍要 locale-aware，persisted state 必須保留 system identity。使用者手動輸入或改寫的自由文字保持原文。

C.7 Backward compatibility

既有 Character、Build Version、Draft、Current State 不得因加入 localization 失效。M02 不以改 StableKey 或重新建立 Character Version 的方式完成翻譯。

M02-D — SRD 5.1 Names & Structured Text

目標

完成 M02-C field policy 中，SRD 5.1 目前 user-visible 的名稱、label 與短型／結構型 presentation 的 zh-TW / en localization。

翻譯範圍

以 localizable field policy 為唯一範圍來源。典型包含：

若某 category 的 name 目前可見而 desc 尚不可見，只翻 required name，不因 category 存在就提前翻全部長文。

完成後必須為真

  1. zh-TW / en 下所有 policy-required SRD names / structured fields 完整。
  2. 同一 selection 在切換語言前後 StableKey 完全相同。
  3. Builder selected values、Review grants、Character Sheet rules names、Spell / Equipment / Inventory choices 等目前可見 presentation 都能同步切換。
  4. 同名或相似名稱仍以 StableKey / source 正確區分，不以翻譯名稱 dedupe。
  5. completeness 可由 policy × dataset 自動枚舉。
  6. 翻譯可依 category 分批 commit，但 D 全 scope 未完整前不得 closeout。

M02-E — SRD 5.1 User-Visible Descriptions

目標

補齊 M02-C field policy 中，在 M02 closeout 時已存在產品畫面會顯示的 SRD 長篇／說明型文字；不為尚不存在的未來畫面提前翻完整 SRD 長文庫。

翻譯範圍

以 localizable field policy 為唯一範圍來源。只要目前 surface 實際顯示，就納入，例如可能包含 spell / feature / trait / condition / skill / weapon property 等 description；若某 field 尚無任何 UI surface，延後到首次 expose 它的 Subphase。

完成後必須為真

  1. policy-required long-form fields 具有 zh-TW 與 en。
  2. 翻譯不得改變 dice formula、數值、DC、range、duration、component、reference identity 或其他 mechanics semantics。
  3. 內文術語遵守 M02-C glossary。
  4. Markdown / rich-text / list 等既有 presentation semantics 在兩語下等價。
  5. 正式 UI 顯示這些 description 時，切換 locale 可立即更新，不需要重建 Character。
  6. Missing required description translation 可被完整性檢查抓到。
  7. 翻譯可依 category 分批 commit，但 E 全 scope 未完整前不得 closeout。

M02-F — PHB / SCAG / GoS Localization

目標

把 M01-B / M01-C 導入、且依 M02-C policy 在目前產品畫面 user-visible 的 non-SRD presentation 完整納入雙語。

F.1 PHB 2014 additions

需依 policy 涵蓋目前可見的 Backgrounds / Variants、Variant Human、PHB subraces、origin features、Background Features、starting choices、roleplay suggestions 與其他 presentation。

F.2 SCAG

需依 policy 涵蓋 SCAG Background names、目前可見的 Feature / choice / roleplay presentation、reused PHB roleplay table presentation、source labels。

Roleplay suggestion inheritance 只能重用 suggestion identity / presentation，不得因 localization 改變「roleplay inheritance != mechanical inheritance」。

F.3 GoS

需依 policy 涵蓋 GoS Background names、目前可見的 Feature / choice / equipment / optional Fisher Tale / Marine Hardship 等 flavor / roleplay presentation。

Optional flavor 在任何 locale 下都仍是 optional，不得因 localization 變成 Confirm blocking choice。

F.4 Existing Traditional Chinese reference input

PHB / SCAG / GoS 的 zh-TW 初稿優先取自對應 docs/暫用規則資訊/。若該文件文字品質有 extraction artifact、錯字或與 glossary 衝突，以 M02-C glossary / review 結果為正式準則，不直接把 reference Markdown 當 runtime translation source。

完成後必須為真

  1. phb2014 / scag / gos policy-required fields 同時具有 zh-TW / en。
  2. 跨 pack reference 在兩語下仍指向同一 StableKey。
  3. selector / Review / Sheet 可顯示正確 locale 的 source-aware names。
  4. roleplay suggestion reuse 不因翻譯造成 mechanical grant pollution。
  5. Background variant / branch 在切換語言後保持相同 active identity。
  6. 缺 required non-SRD translation 不得 silent fallback 後通過 closeout。
  7. F 可依 pack / category 分批 commit，但完整 scope 未完成前不得 closeout。

M02-G — Localized Search, Errors & Completeness Gates

目標

把 localization 從「看起來會切」提升成可長期維護的正式系統：搜尋／排序／錯誤訊息符合目前 locale，並建立 machine-verifiable translation completeness gate。

所有目前提供 rules-content 搜尋的 selector 必須：

例如繁中模式搜尋 fireball 可以命中並只顯示「火球術」。

G.2 Localized sorting

有依名稱排序的 UI，依目前 locale display name 排序；locale switch 後重新呈現符合該語言的排序。

G.3 User-visible errors / validation

validation issue、disabled reason、save / load / confirm error、not-found / invalid-selection、network fallback、rules warning 等 system-owned user-visible message 必須能依目前 locale 顯示。

Machine-readable error / validation code 保持穩定且語言中立。

G.4 Completeness gate

完整性集合為：

supported locale
× enabled content pack
× M02-C required localizable field

M02 closeout：

locales: zh-TW, en
packs:   srd5.1, phb2014, scag, gos

缺任何 required translation 必須造成 test / CI failure；不得以 silent fallback 當成通過。

G.5 Duplicate / orphan localization detection

至少能發現：

M02-H — Full M02 Integration & Closeout

目標

以真實使用流程驗證 M02 已達到「兩個純語言模式 + 完整 current-surface translation + Draft-safe instant switch」，並正式把 localization 變成後續所有內容／畫面 Subphase 的完成條件。

H.1 全站純語言驗收

至少逐頁確認：

zh-TW 與 en 都不得出現可避免的另一語言 system/rules presentation。

H.2 Draft-safe switch

在已有實際未完成 Draft 的情況下驗證 zh-TW → en → zh-TW，過程前後保持 same Draft ID / revision、name / target level、所有 selected StableKeys、ability scores、class progression、structural / spell / equipment choices 與 user roleplay text。

Locale switch 本身不得產生 Draft mutation request。

H.3 Create / reload / persistence

至少完成：

  1. zh-TW 建立角色 → Confirm → Character Sheet → reload，保持繁中。
  2. en 建立角色 → Confirm → Character Sheet → reload，保持 English。
  3. 已存在 Character 在兩語間切換只改 presentation，不建立新 Version。
  4. 關閉再開網站後沿用上次 locale preference。

H.4 Cross-source localization flow

至少驗證：

Review / Sheet / selector / grants 不得因跨 source 而漏翻、錯翻或 identity 混用。

H.5 Content completeness closeout

M02 不得關門，直到：

H.6 Regression

M02 必須保持 P0 / P1 / M01-A～C 既有核心能力：Character Sheet mechanics、Builder legality、Confirm atomicity / idempotency、immutable Build Version、Current State、content source provenance、multi-source StableKey correctness全部不變。

H.7 Human gate

M02 closeout 前需要一次真人 browser smoke，至少確認：

Blocker / Major localization 或 Draft-safety 問題必須在 M02 closeout 前修完。

H.8 Documentation closeout

M02 closeout 必須同步專案 SSOT，而不是只讓永久 localization 規則留在 M02 文件內：

6. M02 明確不做

M02 第一版不建立：

7. M02 完成後的永久專案規則

M02-H closeout 後，Localization 成為既有 platform capability。

後續所有 Phase / Subphase 必須遵守：

  1. 新增 user-visible UI copy 時，同一 Subphase 同步提供 zh-TW / en。
  2. 新增 rules content 的 user-visible presentation field 時，同一 Subphase 同步提供 zh-TW / en。
  3. 新增畫面使既有 content field 首次變成 user-visible 時，該 Subphase 同步補齊該 field 的所有 supported locale。
  4. 新增 validation / error code 時，同一 Subphase 同步提供兩語 user-facing presentation。
  5. 新增 searchable rules entity / field 時，必須接入 localized display / alias search contract。
  6. 不得以「先做英文、之後再補 M Phase」作為正常完成方式。
  7. Missing required translation 視同 regression。
  8. 未來若要新增第三種 locale，再另開對應 Phase 設計，不在 M02 預先做 universal localization platform。

M02 closeout 後的下一步固定為：

回到 M01-D — VGM Race Expansion

M01-D～M01-J 完成後，再回正常 Roadmap：

P2 — Room / Campaign / Session / Seat
This site is open source. Improve this page.