jim800121/visionA
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
visionA/docs/autoflow/03-design/pairing-rename-mapping.md
jim800121chen df082ed308 docs(design): 配對→連接電腦 用詞 mapping 表 
41 key 舊→新對照（zh+en）、心智模型（連接電腦 vs 連線裝置）、避撞規則、
保留項清單。frontend 照此落地。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-08-03 09:41:18 +08:00

169 lines
21 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 「配對」用詞一致化 — 完整 mapping 表（frontend 照表落地）
> 狀態：待 frontend 落地 · 產出：Design Agent · 語言：zh-TW
> 目標檔：`visionA-frontend/src/lib/i18n/dictionaries/zh-Hant.ts`（zh）+ `en.ts`（en）
> **本文件只出 mapping，不改任何 code / i18n 檔。frontend 照表逐 key 替換，不需自己判斷。**
---
## 0. 為什麼要改（一句話）
「配對裝置」讓使用者誤以為在配對 KL520/KL720 **晶片**，但實際配對的是**使用者電腦上的 local-agent**（建立雲端帳號 ↔ 這台電腦的信任連結；之後這台電腦上所有 USB 裝置都能從雲端操作）。所以把主詞從「裝置」換成「電腦」。
## 1. 心智模型（frontend 理解用，務必記住）
系統裡有**兩層不同的連結**，過去都叫「連接/連線」，這次改詞就是要讓兩層在同一畫面不打架：
| 層 | 原本叫什麼 | 這次改成 | 語意 | 頻率 | 對象 |
|----|-----------|---------|------|------|------|
| **信任連結** | 配對 / pairing | **連接這台電腦 / Connect this computer** | 建立「雲端帳號 ↔ 這台電腦」的信任，一次性 | 一次 | 電腦（host / local-agent） |
| **驅動連線** | 連線 / connect（`devices.connect.*`） | **不動**（維持「連線 / 斷線」） | 每次要用某顆 USB 晶片時開啟 driver 連線 | 每次使用 | 裝置（USB 晶片） |
**一句話**：**「連接電腦」是把整台電腦接進你的雲端帳號（原 pairing）；「連線裝置」是開始使用電腦上的某顆晶片（原 device connect，不動）。**
## 2. 避撞規則（frontend 落地時的鐵則）
1. `common.connect="連接"`、`common.disconnect="中斷連線"`、`devices.connect.*`（連線/斷線/連線中）**全部保持不動**。
2. **pairing 相關新詞一律帶主詞「電腦 / 這台電腦」**，不可出現裸「連接」。靠主詞讓使用者秒分辨兩層：
- ✅「連接這台電腦」「已連接的電腦」「重新連接電腦」
- ❌「連接」「已連接」（會跟裝置層 `devices.filter.onlineRegistered="已連接"` 撞）
3. 英文同理：pairing 用 **connect (this) computer / connected computer**；裝置層維持既有 connect/disconnect 用於 device driver。英文 `Connected!`（pairing.step3.success）維持不變，因為那是「電腦已接上雲端」的成功提示，語境清楚。
## 3. 成套用詞決定（正向 / 反向 / 名詞 / 欄位）
| 類別 | 舊詞 | 新詞（zh） | 新詞（en） | 理由 |
|------|------|-----------|-----------|------|
| **正向動作** | 配對 / Pair | 連接這台電腦 / **Connect this computer**（按鈕短版「連接電腦 / Connect computer」） | 主詞換成電腦、消除晶片誤解；長句重寫成「連接你的電腦，就能從雲端使用裝置」 |
| **反向動作（unpair）** | 解除配對 / unpair | **中斷這台電腦的連接 / 解除電腦連接**（動作按鈕沿用既有「移除裝置」不動，內文用「解除電腦連接」） | Disconnect this computer / unlink | unpair 語意=「移除裝置紀錄 + 撤銷存取」；改詞**不改語意**。用「解除…連接」對應正向「連接」，成套。註：現有 `devices.remove.action="移除裝置"` 是刪 device 紀錄的動作，**保持不動**；只有描述 pairing 關係的句子才改。 |
| **名詞（Token）** | Pairing Token | **連接碼**（口語處）/ **連接 Token**（技術處） | **Pairing token → connection token**；CLI 參數 `--relay-token` **不動** | 見 §4「保留 pairing 原文」判定：token 名詞面向使用者改「連接碼」較白話；`--relay-token` 是實際 CLI flag，屬 code identifier，**絕不改**。 |
| **欄位（pairedAt）** | 配對時間 / Paired at | **連接時間 / Connected at** | i18n label 可改；底層欄位名 `pairedAt`（API/DB）**不改**，只改顯示字。 |
| **重新配對（re-pair）** | 重新配對 / re-pair | **重新連接電腦 / re-connect (the computer)** | 成套。凡「請在 local agent 重新配對一次」→「請在 local agent 重新連接一次」。 |
### 3.1 判定「保留 pairing 原文」的技術術語（不改）
| 保留項 | 出現位置 | 為何不改 |
|--------|---------|---------|
| `--relay-token` | `pairing.cli.description` | 實際 CLI flag、code identifier，改了指令會壞。 |
| i18n **key 名**（`pairing.*`、`pairedAt`、`dashboard.pairDevice` 等） | 全部 key | 只改 value，不改 key（改 key 要動用到處引用的元件，超出本次範圍且無使用者可見效益）。 |
| API/DB 欄位 `pairedAt`、後端 `pairing` endpoint、路由 `/devices/pair` | 非 i18n | 使用者拍板「不改路由」；欄位名屬後端契約，本次只改前端顯示文案。 |
---
## 4. 完整 mapping 表（涵蓋 zh 55 處 + en 57 處）
> 說明：一個 i18n key = 一列，同時給 zh/en 舊→新。frontend 逐列替換 value 即可。
> 「備註」欄標注句子有無重寫、避撞注意。行號為撰文時快照（zh-Hant.ts / en.ts），實際以 key 為準。
### 4.1 Dashboard
| i18n key | 舊 zh | 新 zh | 舊 en | 新 en | 備註 |
|----------|-------|-------|-------|-------|------|
| `dashboard.noConnectedDevices` | 目前沒有裝置線上。配對一台 Kneron 裝置開始雲端推論。 | 目前沒有裝置線上。連接你的電腦，就能從雲端使用 Kneron 裝置。 | No devices are online. Pair a Kneron device to start cloud inference. | No devices are online. Connect your computer to use Kneron devices from the cloud. | 句子重寫：主詞改電腦 |
| `dashboard.noActivity` | 還沒有任何活動。配對裝置、上傳模型或跑一次推論後就會出現。 | 還沒有任何活動。連接電腦、上傳模型或跑一次推論後就會出現。 | Nothing here yet. Activity appears after pairing, uploads, or inference runs. | Nothing here yet. Activity appears after connecting a computer, uploads, or inference runs. | pairing→connecting a computer |
| `dashboard.pairDevice` | 配對裝置 | 連接電腦 | Pair device | Connect computer | 按鈕短版 |
| `dashboard.empty.description` | 配對你的第一台 Kneron 裝置，開始雲端推論之旅 | 連接你的電腦，開始從雲端使用 Kneron 裝置 | Pair your first Kneron device to start running inference from anywhere. | Connect your computer to start using Kneron devices from anywhere. | 句子重寫 |
| `dashboard.empty.action` | 配對裝置 | 連接電腦 | Pair a device | Connect computer | 按鈕短版 |
### 4.2 Devices（列表 / 空狀態 / 詳情）
| i18n key | 舊 zh | 新 zh | 舊 en | 新 en | 備註 |
|----------|-------|-------|-------|-------|------|
| `devices.addMore` | 配對新裝置 | 連接新電腦 | Pair a new device | Connect a new computer | |
| `devices.pairAction` | 配對新裝置 | 連接新電腦 | Pair a new device | Connect a new computer | 與上同值 |
| `devices.empty.title` | 還沒有配對的裝置 | 還沒有連接任何電腦 | No devices paired yet | No computers connected yet | |
| `devices.empty.description` | 在你的電腦上執行 local agent 並完成配對，就能從任何地方存取你的 Kneron 裝置 | 在你的電腦上執行 local agent 並完成連接，就能從任何地方存取你的 Kneron 裝置 | Run local agent on your computer and complete pairing to access your Kneron devices from anywhere. | Run local agent on your computer and complete the connection to access your Kneron devices from anywhere. | 完成配對→完成連接 |
| `devices.empty.action` | 配對第一台裝置 | 連接你的電腦 | Pair your first device | Connect your computer | |
| `devices.empty.secondaryAction` | 查看配對說明 | 查看連接說明 | How pairing works | How connecting works | |
| `devices.detail.pairedAt` | 配對時間 | 連接時間 | Paired at | Connected at | 欄位 label；底層 `pairedAt` 欄位名不動 |
### 4.3 Devices：序號 missingHint（re-pair）
| i18n key | 舊 zh | 新 zh | 舊 en | 新 en | 備註 |
|----------|-------|-------|-------|-------|------|
| `devices.serial.missingHint` | 此裝置尚未回報序號，無法執行推論相關操作。請在 local agent 重新配對一次，序號回報後即可使用。 | 此裝置尚未回報序號，無法執行推論相關操作。請在 local agent 重新連接一次，序號回報後即可使用。 | This device hasn't reported its serial number, so inference-related actions are unavailable. Re-pair it once from local agent to report the serial. | This device hasn't reported its serial number, so inference-related actions are unavailable. Re-connect once from local agent to report the serial. | re-pair→re-connect |
### 4.4 Devices：移除裝置（unpair 語意，reverse action）
| i18n key | 舊 zh | 新 zh | 舊 en | 新 en | 備註 |
|----------|-------|-------|-------|-------|------|
| `devices.remove.confirm.description` | 這會解除「{name}」與你帳號的配對並撤銷其存取權限。若要再次使用，需從 local agent 重新配對。此操作無法復原。 | 這會解除「{name}」與你帳號的連接並撤銷其存取權限。若要再次使用，需從 local agent 重新連接。此操作無法復原。 | This unpairs "{name}" from your account and revokes its access. To use it again, you'll need to pair it from local agent. This cannot be undone. | This disconnects "{name}" from your account and revokes its access. To use it again, you'll need to connect it from local agent. This cannot be undone. | **反向成套**：unpairs→disconnects；「解除…配對」→「解除…連接」。unpair 語意（刪紀錄+撤存取）不變。`devices.remove.action="移除裝置"` 按鈕**不動**。 |
> 註：`devices.remove.action / removing / confirm.title / confirm.action / toast.success / error.*`（移除/移除中/確定要移除此裝置/移除/已移除裝置…）**全部不含「配對」字樣，保持不動**。這些是「移除 device 紀錄」的動作詞，與 pairing 改詞無關。
### 4.5 Models
| i18n key | 舊 zh | 新 zh | 舊 en | 新 en | 備註 |
|----------|-------|-------|-------|-------|------|
| `models.empty.description` | 上傳你的第一個 .nef 模型到雲端，就能部署到任何一台配對過的 Kneron 裝置 | 上傳你的第一個 .nef 模型到雲端，就能部署到任何一台已連接電腦上的 Kneron 裝置 | Upload your first .nef model to deploy it to any paired Kneron device. | Upload your first .nef model to deploy it to any Kneron device on a connected computer. | 「配對過的裝置」→「已連接電腦上的裝置」（語意校正：裝置本身不被配對，是它所在電腦被連接） |
### 4.6 Workspace
| i18n key | 舊 zh | 新 zh | 舊 en | 新 en | 備註 |
|----------|-------|-------|-------|-------|------|
| `workspace.empty.description` | 請先配對並確認 local agent 已連上雲端 | 請先連接你的電腦並確認 local agent 已連上雲端 | Pair a device and make sure the local agent is connected to the cloud. | Connect your computer and make sure the local agent is connected to the cloud. | 「local agent 已連上雲端」中的「連上」屬既有網路語意、不改 |
| `workspace.noSerial.description` | 推論、攝影機與媒體上傳需要裝置序號才能路由到 local agent。請在 local agent 重新配對一次，序號回報後即可操作。 | 推論、攝影機與媒體上傳需要裝置序號才能路由到 local agent。請在 local agent 重新連接一次，序號回報後即可操作。 | Inference, camera, and media upload need the device serial to route to local agent. Re-pair the device once from local agent; these actions unlock after the serial is reported. | Inference, camera, and media upload need the device serial to route to local agent. Re-connect once from local agent; these actions unlock after the serial is reported. | re-pair→re-connect |
### 4.7 Pairing 頁（F7，key namespace `pairing.*` 保留、只改 value）
| i18n key | 舊 zh | 新 zh | 舊 en | 新 en | 備註 |
|----------|-------|-------|-------|-------|------|
| `pairing.title` | 配對新裝置 | 連接這台電腦 | Pair a new device | Connect this computer | 頁標題，正向主詞 |
| `pairing.subtitle` | 讓你的 Kneron 裝置連上雲端，就能從任何地方遠端操作 | 讓這台電腦連上雲端，之後電腦上的 Kneron 裝置都能從任何地方遠端操作 | Connect your Kneron device to the cloud so you can operate it from anywhere. | Connect this computer to the cloud so its Kneron devices can be operated from anywhere. | 句子重寫：主詞電腦、點出「之後裝置都能用」 |
| `pairing.token.title` | 你的 Pairing Token | 你的連接碼 | Your pairing token | Your connection token | 名詞成套：連接碼 |
| `pairing.step1.description` | 複製下方 token，在 15 分鐘內貼到 local agent 完成配對 | 複製下方連接碼，在 15 分鐘內貼到 local agent 完成連接 | Copy the token below and paste it into your local agent within 15 minutes. | Copy the connection token below and paste it into your local agent within 15 minutes. | token→連接碼；完成配對→完成連接 |
| `pairing.copy` | 複製 | 複製 | Copy | Copy | 不動 |
| `pairing.copied` | 已複製 | 已複製 | Copied | Copied | 不動 |
| `pairing.regenerate` | 重新產生 | 重新產生 | Regenerate | Regenerate | 不動 |
| `pairing.timeRemaining` | 剩餘 {time} | 剩餘 {time} | {time} remaining | {time} remaining | 不動 |
| `pairing.generatedAt` | 產生時間：{time} | 產生時間：{time} | Generated at {time} | Generated at {time} | 不動 |
| `pairing.token.expired.label` | 此 token 已過期，請重新產生 | 此連接碼已過期，請重新產生 | This token has expired — please regenerate. | This connection token has expired — please regenerate. | token→連接碼 |
| `pairing.regenerateConfirm.title` | 確定要重新產生？ | 確定要重新產生？ | Regenerate token? | Regenerate token? | 不動（token 這裡指連接碼、但短語保留；如要一致可改「Regenerate connection token?」，見下方註） |
| `pairing.regenerateConfirm.description` | 舊 token 將立即失效，新 token 有效期 15 分鐘 | 舊連接碼將立即失效，新連接碼有效期 15 分鐘 | The old token will be invalidated immediately; the new one is valid for 15 minutes. | The old connection token will be invalidated immediately; the new one is valid for 15 minutes. | token→連接碼 |
| `pairing.security.warning` | 這組 token 15 分鐘內有效，請立刻完成配對 | 這組連接碼 15 分鐘內有效，請立刻完成連接 | This token is valid for 15 minutes — complete pairing now. | This connection token is valid for 15 minutes — complete the connection now. | token→連接碼；complete pairing→complete the connection |
| `pairing.security.oneTime` | token 是一次性使用，完成配對後自動失效 | 連接碼是一次性使用，完成連接後自動失效 | Tokens are single-use and expire automatically after pairing. | Connection tokens are single-use and expire automatically after connecting. | 成套 |
| `pairing.toast.copied` | Token 已複製到剪貼簿，15 分鐘內有效 | 連接碼已複製到剪貼簿，15 分鐘內有效 | Token copied — valid for 15 minutes. | Connection token copied — valid for 15 minutes. | token→連接碼 |
| `pairing.toast.generateFailed` | 無法產生 token，請重試 | 無法產生連接碼，請重試 | Could not generate token — please retry. | Could not generate connection token — please retry. | token→連接碼 |
| `pairing.toast.expiringSoon` | Token 即將過期，請立刻完成或重新產生 | 連接碼即將過期，請立刻完成或重新產生 | Token expiring soon — complete pairing or regenerate. | Connection token expiring soon — complete the connection or regenerate. | 成套 |
| `pairing.toast.pairedSuccess` | 裝置 {deviceName} 已成功配對 | 已成功連接電腦，偵測到裝置 {deviceName} | Device {deviceName} paired successfully. | Computer connected — device {deviceName} detected. | 語意校正：成功的是電腦連接、順帶偵測到裝置 |
| `pairing.toast.cliCopied` | 指令已複製到剪貼簿 | 指令已複製到剪貼簿 | CLI command copied. | CLI command copied. | 不動 |
| `pairing.device.unknown` | 未知裝置 | 未知裝置 | Unknown device | Unknown device | 不動 |
| `pairing.cli.title` | CLI 指令範例 | CLI 指令範例 | CLI example | CLI example | 不動 |
| `pairing.cli.description` | 在你的電腦啟動 local agent，將 token 貼到指令的 --relay-token 參數 | 在你的電腦啟動 local agent，將連接碼貼到指令的 --relay-token 參數 | Start local agent on your computer and pass the token to the --relay-token flag. | Start local agent on your computer and pass the connection token to the --relay-token flag. | token→連接碼；**`--relay-token` 保留不改** |
| `pairing.cli.copy` | 複製指令 | 複製指令 | Copy command | Copy command | 不動 |
| `pairing.cli.hint` | local agent 連上雲端後，本頁會自動偵測並跳轉到裝置列表 | local agent 連上雲端後，本頁會自動偵測並跳轉到裝置列表 | Once local agent connects to the cloud, this page detects it and forwards you to the device list. | Once local agent connects to the cloud, this page detects it and forwards you to the device list. | 不動（「連上雲端」屬網路語意、非 pairing 動作詞） |
| `pairing.step3.waiting` | 等待 local agent 連線… | 等待 local agent 連線… | Waiting for local agent to connect… | Waiting for local agent to connect… | 不動（local agent↔雲端的網路連線，非 pairing 動作詞） |
| `pairing.step3.elapsed` | 已等待 {time}（最長 3 分鐘） | 已等待 {time}（最長 3 分鐘） | Elapsed {time} (max 3 minutes) | Elapsed {time} (max 3 minutes) | 不動 |
| `pairing.step3.hints.running` | 確認 local agent 已啟動 | 確認 local agent 已啟動 | Confirm local agent is running | Confirm local agent is running | 不動 |
| `pairing.step3.hints.token` | 確認 token 貼上時無缺字或多餘空白 | 確認連接碼貼上時無缺字或多餘空白 | Confirm the token was pasted without missing or extra characters | Confirm the connection token was pasted without missing or extra characters | token→連接碼 |
| `pairing.step3.hints.network` | 確認你的網路可連線到雲端 | 確認你的網路可連線到雲端 | Confirm your network can reach the cloud endpoint | Confirm your network can reach the cloud endpoint | 不動 |
| `pairing.step3.success` | 已成功連線！ | 已成功連接電腦！ | Connected! | Connected! | zh 加主詞「電腦」避撞；en `Connected!` 語境清楚，保留 |
| `pairing.step3.success.detected` | 檢測到的裝置 | 檢測到的裝置 | Detected device | Detected device | 不動 |
| `pairing.step3.failure.timeout` | 連線超時 | 連接超時 | Connection timeout | Connection timeout | zh「連線超時」→「連接超時」對齊 pairing 語意；en 不動 |
| `pairing.step3.failure.reason` | 超過 3 分鐘沒收到 local agent 連線，可能是 local agent 尚未啟動 | 超過 3 分鐘沒收到 local agent 連線，可能是 local agent 尚未啟動 | No local agent connection within 3 minutes — agent may not be running. | No local agent connection within 3 minutes — agent may not be running. | 不動（指 agent↔雲端網路連線） |
| `pairing.step3.failure.retry` | 重新檢查 | 重新檢查 | Check again | Check again | 不動 |
> `pairing.regenerateConfirm.title` 註：為求 token 名詞完全一致，可選改 zh「確定要重新產生連接碼？」/ en「Regenerate connection token?」。frontend 若採一致版即用此；否則保留現值。此為 nice-to-have，不阻擋落地。
---
## 5. 明確「不動」清單（frontend 別誤改）
以下 key 含「連接 / 連線 / connect」但屬**裝置驅動層或網路層**，與 pairing 無關，**一律不改**：
- `common.connect="連接"`、`common.disconnect="中斷連線"`
- `devices.connect.*` 全部（action 連線 / connecting 連線中 / disconnect 斷線 / driverStatusLabel 連線狀態 / toast.* …）
- `devices.filter.onlineRegistered="已連接"`、`devices.filter.onlineUnregistered`、`devices.filter.offline`
- `devices.status.connecting/connected/disconnected`、`devices.detail.port="連接埠"`
- `devices.rescan.offlineHint`（「請先連接 local agent…」屬 agent 在線語意）
- `tunnel.status.*`、`remote.status.*`、各處「連線失敗 / 網路連線」等網路語意字串
- `devices.remove.action/removing/confirm.title/confirm.action/toast/error.*`（移除 device 紀錄動作、非 pairing 詞）
---
## 6. 落地後驗證（frontend / Design QA 自檢）
1. **同畫面不打架**：Devices 列表頁同時出現「連接新電腦」（pairing 按鈕）與裝置卡片上「連線 / 斷線」（device driver）時，主詞清楚不混淆。
2. **grep 檢查**：改完後 `pairing.*` value 與 dashboard/devices/workspace 的 pairing 文案不再出現裸「配對」；en 不再出現 `Pair`/`pairing`/`unpair`（除 `--relay-token`、i18n key 名、`pairedAt` 欄位名外）。
3. **避撞檢查**：pairing 新詞不得出現裸「連接/已連接」（無主詞），必帶「電腦」。
4. **語意不變檢查**：`devices.remove.confirm.description`（unpair）改詞後仍表達「移除裝置紀錄 + 撤銷存取 + 不可復原」。
Reference in New Issue View Git Blame Copy Permalink