issue-map 0.2.0 → 0.3.0

package/README.zh-TW.md

@@ -0,0 +1,133 @@
+# issue-map
+
+[English](README.md) · **繁體中文** · [简体中文](README.zh-CN.md) · [日本語](README.ja.md)
+
+> 原稿是[英文版](README.md)。翻譯落後時以它為準。
+
+把 GitHub Issues 的阻擋關係畫成一頁開發地圖：**哪幾張票現在可以動、哪幾張在等誰、關鍵路徑是哪一條。**
+
+狀態的權威永遠是 GitHub Issues。這一頁只是快照，頁面上不能改狀態——所以不會長出第二個事實來源。
+
+## 為什麼有這個專案
+
+起點是 [mattpocock/skills](https://github.com/mattpocock/skills)。團隊照它那套「把工作流寫成
+skill、讓 agent 照著跑」開始做事之後，開票變得很便宜：想到一件事就開一張票，交給 skill 去接。
+票因此長得很快——那是流程在運作的證據，不是問題。
+
+問題在下一步。Agent 一輪吃一張票，所以每一輪真正要決定的是**派哪一張**，而這個答案不在任何
+單一張票裡，它在票與票之間：誰擋著誰、哪一組子票還差幾張、最長的那條鏈有多長。GitHub Issues
+一次只讓你讀一張票，要湊出那張圖就得一張一張點開來，而且每天都要重湊一次。
+
+這一頁就是那張圖。
+
+## 用法
+
+在**要看的那個 repo** 裡跑：
+
+```bash
+bunx issue-map@latest
+```
+
+`@latest` 取 npm 上最新的一版；要釘住特定版本就寫 `bunx issue-map@0.2.0`。
+
+起在 `http://localhost:4747` **並直接開瀏覽器**。每次重新整理都重抓 GitHub，看到的一定是現在的狀態。repo 是 `gh` 從 cwd 的 git 推斷的，不必填。
+
+不要自動開分頁就設 `ISSUE_MAP_OPEN=0`。
+
+只要一份靜態 HTML 的話（`-p` 是用來選另一個 bin 的，少了它會變成起 server）：
+
+```bash
+bunx -p issue-map@latest issue-map-build            # 寫到 dist/issue-map.html
+bunx -p issue-map@latest issue-map-build out.html
+```
+
+快照就是快照——狀態會過期，要看現在的狀態就用上面的 server。
+
+## 語言
+
+頁面右上角切換，**預設英文**，另外支援繁體中文、簡體中文、日文。選了哪一種記在瀏覽器
+（localStorage 的 `issue-map:locale`），跟 repo 無關——語言是看的人的偏好，不是某個專案的設定。
+刻意不看 `navigator.language`：預設就是英文，猜錯了反而每次進來都要改回去。
+
+文案全部在 `scripts/issue-map-i18n.ts`，那是頁面上每一句話的唯一來源：
+
+- `EN` 是原稿，也是鍵的定義處。三份翻譯的型別由它推導，少翻一個鍵 `bun run typecheck` 就會紅。
+- 句子裡的代入名（`{n}`、`{issues}`）也是型別的一部分，少傳一個編不過——不然缺的那個會以
+  `{n}` 的樣子印在畫面上，而那要真的跑到那一格才看得到。
+- 英文要分單複數的鍵寫成 `{ one, other }`，中日文寫一句字串就好（`Intl.PluralRules` 對這幾種
+  語言只有 `other`）。
+
+模型與抓取那一側**不再算好句子**：`nextStep` 是 `{ kind: 'waitChildren', count: 2 }` 這種結構化
+的值，分組名字也一樣，話在 i18n 那一層才組出來。快照裡存中文句子的話，換一次語言就得重抓一次
+GitHub。
+
+CLI 那一側（產檔訊息、錯誤）刻意留中文：那是給開發者看的，不是頁面的一部分。
+
+## 前置條件
+
+- **Bun**。這幾支用了 `Bun.build`、`Bun.serve`、`Bun.file` 與 bun 的 `spawnSync`，Node 跑不起來。
+- **`gh` CLI 已登入**，而且對目標 repo 有讀取權。
+- 目標 repo 有 git remote 指向 GitHub。
+- 沒有 runtime 依賴；devDependencies 只有型別與 lint／format 工具。
+
+## 設定
+
+全部有預設值，一個都不設也跑得起來。預設值長在 `scripts/issue-map.ts` 的 `CONFIG`。
+
+| 環境變數                   | 預設                              | 意思                                                               |
+| -------------------------- | --------------------------------- | ------------------------------------------------------------------ |
+| `GH_REPO`                  | 從 cwd 的 git 推斷                | 要畫別的 repo 時設它（`gh` 自己的變數，fork 與多 remote 也交給它） |
+| `ISSUE_MAP_PARENT_HEADING` | `Parent`                          | 子票在內文指向母票的段落標題。GitHub 原生 sub-issue 有值時優先     |
+| `ISSUE_MAP_LABELS_UNREADY` | `needs-triage,needs-info`         | 掛了就是還沒評估完，不能交給誰做                                   |
+| `ISSUE_MAP_LABELS_READY`   | `ready-for-agent,ready-for-human` | 掛了才算評估完、可以動工                                           |
+| `ISSUE_MAP_LABELS_ACTIVE`  | `in-progress`                     | 掛了代表有人在做，不必有 assignee                                  |
+| `ISSUE_MAP_LABELS_HUMAN`   | `ready-for-human`                 | 這些要人做，下一步不寫實作指令                                     |
+| `ISSUE_MAP_CMD_IMPLEMENT`  | `/implement`                      | 可以動工時圖上叫人跑的指令                                         |
+| `ISSUE_MAP_CMD_TRIAGE`     | `/triage`                         | 還要評估時圖上叫人跑的指令                                         |
+| `ISSUE_MAP_PORT`           | `4747`                            | server 的 port                                                     |
+| `ISSUE_MAP_OPEN`           | 開                                | 設 `0` 就不自動開瀏覽器（`bun --watch` 的開發模式預設關掉）        |
+
+兩個要特別想過的：
+
+- **標籤字彙**：目標 repo 沒在用這套標籤就要換成它自己的名字。程式會偵測——快照裡完全沒出現 ready／unready 任何一個標籤時，就不拿 triage 當閘門，否則每張票都會變成「待評估」。
+- **指令名**：`/implement`、`/triage` 是 Claude Code 的 skill。目標 repo 沒有的話一定要換掉，不然圖上會叫人跑不存在的東西。
+
+## 常見失敗
+
+- `gh api graphql 失敗：…` — `gh` 沒登入，或 cwd 不在目標 repo 的 git 樹裡。
+- `open issue 超過 100 張，這支要改成分頁抓` — GraphQL 的 `first` 上限就是 100。要支援更多票得在 `issue-map.ts` 的 `query()` 加分頁；這是要改程式，不是設定。
+
+## 檔案
+
+| 檔案                         | 責任                                                                   |
+| ---------------------------- | ---------------------------------------------------------------------- |
+| `scripts/issue-map.ts`       | 抓快照、算每張票的狀態與下一步、產出 HTML。移植設定在裡面的 `CONFIG`   |
+| `scripts/issue-map-model.ts` | 純資料模型：分組、關鍵路徑。前後端共用                                 |
+| `scripts/issue-map-i18n.ts`  | 四種語言的文案與查表。頁面上每一句話的唯一來源                         |
+| `scripts/issue-map-page.ts`  | 瀏覽器端程式碼，建置時被打包進 HTML                                    |
+| `scripts/issue-map.html`     | 樣板。兩個佔位區塊（`issue-map-data`、`issue-map-code`）會被填入       |
+| `scripts/issue-map-serve.ts` | 本機 server，每個請求重抓一次                                          |
+| `scripts/mutate.ts`          | 突變測試：改壞一行看測試會不會紅。守門測試的反向驗證用它，不要手改檔案 |
+
+## 在這個 repo 裡開發
+
+```bash
+bun install
+bun run issue-map:serve   # --watch，改程式碼會自動重啟；刻意不自動開瀏覽器（每存一次檔就會多一個分頁）
+bun run issue-map         # 只產檔到 dist/issue-map.html
+bun run check             # lint + format:check + typecheck
+bun test                  # 純模型那一層（分組、關鍵路徑、排版）
+```
+
+這個 repo 自己還沒有 issue，`GH_REPO=<owner>/<repo>` 指到有票的 repo 才畫得出東西。
+
+`tests/` 只守會讓地圖說謊或不能看的事，外觀（顏色、形狀、間距）刻意不驗。新增守門測試要走反向驗證——把它宣稱要擋的缺陷放回產品碼，確認它會紅：
+
+```bash
+bun run mutate scripts/issue-map-model.ts tests/issue-map-layout.test.ts
+```
+
+## 兩個設計上的決定，改之前先知道
+
+- **這一頁不能改狀態。** 沒有按鈕會回寫 GitHub。刻意的：狀態只有一個事實來源，多一個入口就會不一致。
+- **票名不進地圖。** 節點只掛票號，名字在下方清單。試過在內文加短名段落，那是票名的第二個事實來源，改標題不會改它；機械縮短標題讀不通。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "issue-map",
-  "version": "0.2.0",
-  "description": "把 GitHub Issues 的阻擋關係畫成一頁開發地圖：哪幾張票現在可以動、哪幾張在等誰、關鍵路徑是哪一條。",
+  "version": "0.3.0",
+  "description": "Draws the blocking relationships between your GitHub Issues as a one-page dev map: which issues can be picked up now, which are waiting on what, and where the critical path runs.",
   "keywords": [
     "bun",
     "cli",
@@ -19,7 +19,11 @@
     "issue-map-build": "./scripts/issue-map.ts"
   },
   "files": [
+    "README.zh-TW.md",
+    "README.zh-CN.md",
+    "README.ja.md",
     "scripts/issue-map.ts",
+    "scripts/issue-map-i18n.ts",
     "scripts/issue-map-model.ts",
     "scripts/issue-map-page.ts",
     "scripts/issue-map-serve.ts",

package/scripts/issue-map-i18n.ts

@@ -0,0 +1,486 @@
+/**
+ * 頁面文案。**沒有 Bun、沒有 DOM**——它只是字典與一個查表函式，所以抓資料那一側與畫面那一側
+ * 都能 import。
+ *
+ * 這裡是頁面上所有給人看的字的唯一來源。畫面那一側不寫死任何一句話，模型那一側也不再算好
+ * 中文句子送過來——`nextStep` 與分組名字都是結構化的值，句子在這裡才組出來。少了這一層，同一
+ * 句話會同時長在模型、樣板與畫面三處，換語言只會換到其中一處。
+ *
+ * `en` 是原稿，也是鍵的定義處：`Messages` 由它推導，少翻一個鍵就編不過。翻譯缺鍵不會 fallback
+ * 成英文——那會安靜地留下半英半中的畫面。
+ *
+ * 字典的值會進 `innerHTML`（`lede.*` 刻意帶 `<strong>`），所以**翻譯裡不要放意料外的標記**；
+ * 代入的值由呼叫端負責逃脫，跟原本用模板字串時一樣。
+ */
+
+/** 支援的語言。第一個是預設。 */
+export const LOCALES = ['en', 'zh-TW', 'zh-CN', 'ja'] as const
+
+export type Locale = (typeof LOCALES)[number]
+
+export const DEFAULT_LOCALE: Locale = 'en'
+
+/** 語言選單上的字。一律寫該語言自己的說法，不翻譯。 */
+export const LOCALE_NAME: Readonly<Record<Locale, string>> = {
+  en: 'English',
+  'zh-TW': '繁體中文',
+  'zh-CN': '简体中文',
+  ja: '日本語',
+}
+
+/** 要分單複數的句子。英文才用得到，中日文寫成單一句字串就好。 */
+type Plural = { readonly one: string; readonly other: string }
+
+type Message = string | Plural
+
+// ---- 原稿 ----
+
+const EN = {
+  'lang.label': 'Language',
+
+  'title.withRepo': '{repo} dev map',
+  'title.plain': 'Dev map',
+
+  'stat.ready': 'ready now',
+  'stat.active': 'picked up',
+  'stat.blocked': 'blocked',
+  'stat.triage': 'not settled',
+  'stat.critical': 'critical path',
+  'stat.critical.unit': { one: 'issue', other: 'issues' },
+
+  'lede.allDone': 'Nothing open in this repo.',
+  'lede.open': { one: '{n} issue open.', other: '{n} issues open.' },
+  'lede.ready': {
+    one: '<strong>{n} ready now — {issues}</strong>.',
+    other: '<strong>{n} ready now, starting with {issues}</strong>.',
+  },
+  'lede.none':
+    '<strong>Nothing is ready right now</strong> — every issue waits on a prerequisite or on triage.',
+  'lede.blocked': {
+    one: '{n} issue blocked by a prerequisite.',
+    other: '{n} issues blocked by prerequisites.',
+  },
+  'lede.triage': {
+    one: '{n} issue still needs triage.',
+    other: '{n} issues still need triage.',
+  },
+  'lede.critical': 'Critical path {n} — that is the fewest rounds this can close in.',
+
+  'foot.truth':
+    'GitHub Issues is the source of truth. This page is a snapshot; you cannot change status here.',
+  'foot.refresh': 'Re-run {build} for a file, or {serve} so a refresh is always current.',
+  'foot.vocab':
+    "This run's gate: {ready} means ready to work on; {unready} or no role label means not settled.",
+  'foot.noVocab':
+    'This repo does not use triage labels, so status only reflects prerequisites and hand-offs.',
+  /** 兩種串接：`or` 是「A 或 B」，`slash` 串一票標籤名，`items` 串一串票號。 */
+  'join.or': ' or ',
+  'join.slash': ', ',
+  'join.items': ', ',
+
+  'fold.collapse': 'Collapse sub-issues of #{n}',
+  'fold.expand': 'Expand sub-issues of #{n}',
+
+  'map.stations': { one: '{n} stop', other: '{n} stops' },
+  'map.islandName': 'no prerequisites',
+  'map.islandSub': 'can start in parallel',
+  'legend.ready': 'ready now',
+  'legend.active': 'picked up',
+  'legend.blocked': 'waiting on prerequisite',
+  'legend.triage': 'not settled',
+  'legend.done': 'closed',
+  'legend.solid': 'solid = prerequisite still open',
+  'legend.dashed': 'dashed = prerequisite closed',
+  'node.aria': '#{n} {title}, {status}',
+
+  'group.linked': 'other dependency chains',
+  'group.island': 'independent issues',
+  'group.orphan': 'sub-issues of #{n}',
+  'group.islandSub': 'nothing blocks anything, all can start in parallel',
+  'group.linkedSub': 'linked by prerequisites, but under no parent issue',
+  'group.spec': '#{n} parent spec',
+  'group.progress': 'sub-issues {done} / {total} done · parent closes only when all do',
+
+  'status.ready': 'ready',
+  'status.active': 'in progress',
+  'status.blocked': 'blocked',
+  'status.triage': 'needs triage',
+  'status.done': 'done',
+
+  'step.active': 'in progress',
+  'step.manual': 'human work',
+  'step.waitIssues': 'waiting on {issues}',
+  'step.waitChildren': {
+    one: 'waiting on {n} sub-issue',
+    other: 'waiting on {n} sub-issues',
+  },
+  'step.parentReady': 'all sub-issues closed, safe to close',
+
+  'detail.status': 'status',
+  'detail.next': 'next step',
+  'detail.author': 'opened by',
+  'detail.parent': 'parent',
+  'detail.waiting': 'waiting on',
+  'detail.settled': 'cleared prerequisites',
+  'detail.unlocks': 'closing unlocks',
+  'detail.labels': 'labels',
+  'detail.assignees': 'assigned',
+  'detail.closedAt': ' closed {date}',
+  'detail.open': 'Open on GitHub ↗',
+  'detail.empty': 'No issue',
+
+  'row.waits': 'waiting on {list}',
+
+  'list.title': 'List',
+  'list.count': { one: '{n} issue', other: '{n} issues' },
+  'tabs.aria': 'Filter by status',
+  'tabs.all': 'all',
+
+  'copy.title': 'Copy {command}',
+  'copy.done': 'copied',
+  'copy.fail': 'copy failed',
+} as const satisfies Readonly<Record<string, Message>>
+
+export type MessageKey = keyof typeof EN
+
+/** 翻譯要把鍵補齊；單複數那幾句可以只寫一句。 */
+type Messages = Readonly<Record<MessageKey, Message>>
+
+// ---- 翻譯 ----
+
+const ZH_TW: Messages = {
+  'lang.label': '語言',
+
+  'title.withRepo': '{repo} 開發地圖',
+  'title.plain': '開發地圖',
+
+  'stat.ready': '現在可動',
+  'stat.active': '有人接手',
+  'stat.blocked': '被前置擋住',
+  'stat.triage': '規格未定案',
+  'stat.critical': '關鍵路徑',
+  'stat.critical.unit': '張',
+
+  'lede.allDone': '這個 repo 沒有未完成的票。',
+  'lede.open': '{n} 張未完成。',
+  'lede.ready': '<strong>現在可動 {n} 張，最前面是 {issues}</strong>。',
+  'lede.none': '<strong>現在沒有可動的票</strong>——每一張都在等前置或等 triage。',
+  'lede.blocked': '{n} 張被前置擋住。',
+  'lede.triage': '{n} 張規格還沒定案，要先 triage。',
+  'lede.critical': '關鍵路徑 {n} 張，那是最少要幾輪才收得完。',
+
+  'foot.truth': '狀態的權威是 GitHub Issues。這一頁是快照，頁面上不能改狀態。',
+  'foot.refresh': '重跑 {build} 產檔，或 {serve} 讓重新整理就是最新。',
+  'foot.vocab': '這一次的判準：掛 {ready} 才算可動；掛 {unready} 或沒掛角色標籤算未定案。',
+  'foot.noVocab': '這個 repo 沒有在用 triage 標籤，狀態只看阻擋與接手。',
+  'join.or': ' 或 ',
+  'join.slash': '／',
+  'join.items': '、',
+
+  'fold.collapse': '收起 #{n} 的子票',
+  'fold.expand': '展開 #{n} 的子票',
+
+  'map.stations': '{n} 站',
+  'map.islandName': '無前置',
+  'map.islandSub': '可各自開工',
+  'legend.ready': '現在可動',
+  'legend.active': '有人接手',
+  'legend.blocked': '等前置',
+  'legend.triage': '規格未定案',
+  'legend.done': '已關閉',
+  'legend.solid': '實線＝還沒解開的前置',
+  'legend.dashed': '虛線＝前置已關',
+  'node.aria': '#{n} {title}，{status}',
+
+  'group.linked': '其他依賴鏈',
+  'group.island': '獨立票',
+  'group.orphan': '#{n} 的子票',
+  'group.islandSub': '互不阻擋，可各自開工',
+  'group.linkedSub': '有前置關係，但不屬於任何母票',
+  'group.spec': '#{n} 母票規格',
+  'group.progress': '子票 {done} / {total} 已完成 · 全關後才關 parent',
+
+  'status.ready': '可接手',
+  'status.active': '進行中',
+  'status.blocked': '阻擋中',
+  'status.triage': '待 triage',
+  'status.done': '已完成',
+
+  'step.active': '進行中',
+  'step.manual': '人工實作',
+  'step.waitIssues': '等 {issues}',
+  'step.waitChildren': '等 {n} 張子票關完',
+  'step.parentReady': '子票全關，可以關掉了',
+
+  'detail.status': '狀態',
+  'detail.next': '下一步',
+  'detail.author': '開票',
+  'detail.parent': '母票',
+  'detail.waiting': '等誰',
+  'detail.settled': '已解鎖的前置',
+  'detail.unlocks': '關掉後解鎖',
+  'detail.labels': '標籤',
+  'detail.assignees': '接手',
+  'detail.closedAt': ' {date} 關閉',
+  'detail.open': '在 GitHub 開啟 ↗',
+  'detail.empty': '沒有 issue',
+
+  'row.waits': '等 {list}',
+
+  'list.title': '清單',
+  'list.count': '{n} 張',
+  'tabs.aria': '狀態篩選',
+  'tabs.all': '全部',
+
+  'copy.title': '複製 {command}',
+  'copy.done': '已複製',
+  'copy.fail': '複製不了',
+}
+
+const ZH_CN: Messages = {
+  'lang.label': '语言',
+
+  'title.withRepo': '{repo} 开发地图',
+  'title.plain': '开发地图',
+
+  'stat.ready': '现在可动',
+  'stat.active': '有人接手',
+  'stat.blocked': '被前置挡住',
+  'stat.triage': '规格未定案',
+  'stat.critical': '关键路径',
+  'stat.critical.unit': '张',
+
+  'lede.allDone': '这个 repo 没有未完成的票。',
+  'lede.open': '{n} 张未完成。',
+  'lede.ready': '<strong>现在可动 {n} 张，最前面是 {issues}</strong>。',
+  'lede.none': '<strong>现在没有可动的票</strong>——每一张都在等前置或等 triage。',
+  'lede.blocked': '{n} 张被前置挡住。',
+  'lede.triage': '{n} 张规格还没定案，要先 triage。',
+  'lede.critical': '关键路径 {n} 张，那是最少要几轮才收得完。',
+
+  'foot.truth': '状态的权威是 GitHub Issues。这一页是快照，页面上不能改状态。',
+  'foot.refresh': '重跑 {build} 产文件，或 {serve} 让刷新就是最新。',
+  'foot.vocab': '这一次的判准：挂 {ready} 才算可动；挂 {unready} 或没挂角色标签算未定案。',
+  'foot.noVocab': '这个 repo 没有在用 triage 标签，状态只看阻挡与接手。',
+  'join.or': ' 或 ',
+  'join.slash': '／',
+  'join.items': '、',
+
+  'fold.collapse': '收起 #{n} 的子票',
+  'fold.expand': '展开 #{n} 的子票',
+
+  'map.stations': '{n} 站',
+  'map.islandName': '无前置',
+  'map.islandSub': '可各自开工',
+  'legend.ready': '现在可动',
+  'legend.active': '有人接手',
+  'legend.blocked': '等前置',
+  'legend.triage': '规格未定案',
+  'legend.done': '已关闭',
+  'legend.solid': '实线＝还没解开的前置',
+  'legend.dashed': '虚线＝前置已关',
+  'node.aria': '#{n} {title}，{status}',
+
+  'group.linked': '其他依赖链',
+  'group.island': '独立票',
+  'group.orphan': '#{n} 的子票',
+  'group.islandSub': '互不阻挡，可各自开工',
+  'group.linkedSub': '有前置关系，但不属于任何母票',
+  'group.spec': '#{n} 母票规格',
+  'group.progress': '子票 {done} / {total} 已完成 · 全关后才关 parent',
+
+  'status.ready': '可接手',
+  'status.active': '进行中',
+  'status.blocked': '阻挡中',
+  'status.triage': '待 triage',
+  'status.done': '已完成',
+
+  'step.active': '进行中',
+  'step.manual': '人工实作',
+  'step.waitIssues': '等 {issues}',
+  'step.waitChildren': '等 {n} 张子票关完',
+  'step.parentReady': '子票全关，可以关掉了',
+
+  'detail.status': '状态',
+  'detail.next': '下一步',
+  'detail.author': '开票',
+  'detail.parent': '母票',
+  'detail.waiting': '等谁',
+  'detail.settled': '已解锁的前置',
+  'detail.unlocks': '关掉后解锁',
+  'detail.labels': '标签',
+  'detail.assignees': '接手',
+  'detail.closedAt': ' {date} 关闭',
+  'detail.open': '在 GitHub 打开 ↗',
+  'detail.empty': '没有 issue',
+
+  'row.waits': '等 {list}',
+
+  'list.title': '清单',
+  'list.count': '{n} 张',
+  'tabs.aria': '状态筛选',
+  'tabs.all': '全部',
+
+  'copy.title': '复制 {command}',
+  'copy.done': '已复制',
+  'copy.fail': '复制不了',
+}
+
+const JA: Messages = {
+  'lang.label': '言語',
+
+  'title.withRepo': '{repo} 開発マップ',
+  'title.plain': '開発マップ',
+
+  'stat.ready': '着手できる',
+  'stat.active': '対応中',
+  'stat.blocked': '前提待ち',
+  'stat.triage': '仕様未確定',
+  'stat.critical': 'クリティカルパス',
+  'stat.critical.unit': '件',
+
+  'lede.allDone': 'この repo に未完了のチケットはありません。',
+  'lede.open': '未完了 {n} 件。',
+  'lede.ready': '<strong>着手できるのは {n} 件、先頭は {issues}</strong>。',
+  'lede.none':
+    '<strong>いま着手できるチケットはありません</strong>——すべて前提か triage 待ちです。',
+  'lede.blocked': '{n} 件が前提で止まっています。',
+  'lede.triage': '{n} 件は仕様が未確定で、まず triage が必要です。',
+  'lede.critical': 'クリティカルパス {n} 件——最短でも何周かかるかを示します。',
+
+  'foot.truth':
+    '状態の正は GitHub Issues です。このページはスナップショットで、ここでは状態を変えられません。',
+  'foot.refresh': 'ファイルを作り直すなら {build}、更新が常に最新になるのは {serve}。',
+  'foot.vocab':
+    '今回の判定基準：{ready} が付いていれば着手可。{unready} または役割ラベルなしは未確定。',
+  'foot.noVocab':
+    'この repo は triage ラベルを使っていないため、状態は前提と担当だけで決まります。',
+  'join.or': ' または ',
+  'join.slash': '／',
+  'join.items': '、',
+
+  'fold.collapse': '#{n} のサブチケットを折りたたむ',
+  'fold.expand': '#{n} のサブチケットを開く',
+
+  'map.stations': '{n} 駅',
+  'map.islandName': '前提なし',
+  'map.islandSub': 'それぞれ着手可',
+  'legend.ready': '着手できる',
+  'legend.active': '対応中',
+  'legend.blocked': '前提待ち',
+  'legend.triage': '仕様未確定',
+  'legend.done': 'クローズ済み',
+  'legend.solid': '実線＝未解決の前提',
+  'legend.dashed': '破線＝前提はクローズ済み',
+  'node.aria': '#{n} {title}、{status}',
+
+  'group.linked': 'その他の依存チェーン',
+  'group.island': '独立チケット',
+  'group.orphan': '#{n} のサブチケット',
+  'group.islandSub': '互いにブロックせず、それぞれ着手できる',
+  'group.linkedSub': '依存関係はあるが、親チケットには属さない',
+  'group.spec': '#{n} 親チケットの仕様',
+  'group.progress': 'サブチケット {done} / {total} 完了 · すべて閉じてから親を閉じる',
+
+  'status.ready': '着手可',
+  'status.active': '対応中',
+  'status.blocked': 'ブロック中',
+  'status.triage': 'triage 待ち',
+  'status.done': '完了',
+
+  'step.active': '対応中',
+  'step.manual': '人が実装',
+  'step.waitIssues': '{issues} を待つ',
+  'step.waitChildren': 'サブチケット {n} 件の完了を待つ',
+  'step.parentReady': 'サブチケットは全て完了、閉じられます',
+
+  'detail.status': '状態',
+  'detail.next': '次の一手',
+  'detail.author': '起票',
+  'detail.parent': '親チケット',
+  'detail.waiting': '待っているもの',
+  'detail.settled': '解決済みの前提',
+  'detail.unlocks': '閉じると動くもの',
+  'detail.labels': 'ラベル',
+  'detail.assignees': '担当',
+  'detail.closedAt': ' {date} クローズ',
+  'detail.open': 'GitHub で開く ↗',
+  'detail.empty': 'issue がありません',
+
+  'row.waits': '{list} を待つ',
+
+  'list.title': '一覧',
+  'list.count': '{n} 件',
+  'tabs.aria': '状態で絞り込む',
+  'tabs.all': 'すべて',
+
+  'copy.title': '{command} をコピー',
+  'copy.done': 'コピーしました',
+  'copy.fail': 'コピーできません',
+}
+
+const DICTS: Readonly<Record<Locale, Messages>> = {
+  en: EN,
+  'zh-TW': ZH_TW,
+  'zh-CN': ZH_CN,
+  ja: JA,
+}
+
+// ---- 查表 ----
+
+/**
+ * 句子裡的代入名，從原稿的字面型別抽出來。少傳一個編不過——不然缺的那個會以 `{name}` 的樣子
+ * 印在畫面上，而那要真的跑到那一格才看得到。
+ */
+type Names<S extends string> = S extends `${string}{${infer K}}${infer Rest}`
+  ? K | Names<Rest>
+  : never
+
+type VarsOf<M> = M extends string
+  ? Names<M>
+  : M extends Plural
+    ? 'n' | Names<M['one']> | Names<M['other']>
+    : never
+
+type Args<K extends MessageKey> = [VarsOf<(typeof EN)[K]>] extends [never]
+  ? []
+  : [vars: Readonly<Record<VarsOf<(typeof EN)[K]>, string | number>>]
+
+/** 現在的語言只有這一份。畫面那一側先 `setLocale` 再整頁重畫。 */
+let current: Locale = DEFAULT_LOCALE
+
+export function locale(): Locale {
+  return current
+}
+
+export function isLocale(value: string | null): value is Locale {
+  return LOCALES.includes(value as Locale)
+}
+
+export function setLocale(next: Locale): void {
+  current = next
+}
+
+const RULES = new Map<Locale, Intl.PluralRules>()
+
+function pluralRules(of: Locale): Intl.PluralRules {
+  const cached = RULES.get(of)
+  if (cached) return cached
+  const made = new Intl.PluralRules(of)
+  RULES.set(of, made)
+  return made
+}
+
+export function t<K extends MessageKey>(key: K, ...args: Args<K>): string {
+  const vars = (args[0] ?? {}) as Readonly<Record<string, string | number>>
+  const message: Message = DICTS[current][key]
+  const text =
+    typeof message === 'string'
+      ? message
+      : pluralRules(current).select(Number(vars.n)) === 'one'
+        ? message.one
+        : message.other
+  return text.replace(/\{(\w+)\}/g, (whole, name: string) =>
+    name in vars ? String(vars[name]) : whole,
+  )
+}