diff --git a/.kiro/specs/i18n-frontend-ui-strings/design.md b/.kiro/specs/i18n-frontend-ui-strings/design.md new file mode 100644 index 00000000..b66a32ca --- /dev/null +++ b/.kiro/specs/i18n-frontend-ui-strings/design.md @@ -0,0 +1,544 @@ +# Technical Design — `i18n-frontend-ui-strings` + +## Overview + +**Purpose**: Externalize the remaining hard-coded Chinese UI strings in five frontend Vue files (`Process.vue`, `Step2EnvSetup.vue`, `Step3Simulation.vue`, `Step4Report.vue`, `Step5Interaction.vue`) to `vue-i18n` keys, restructure backend-coupled regex parsers in `Step4Report.vue` so they survive the upcoming backend prompt translation, and add a small audit script to verify acceptance. + +**Users**: English-locale users of the MiroFish UI (the production tablet/desktop dashboard). No backend or API consumer is affected. + +**Impact**: Translates ~50 user-visible strings, refactors three string-equality stage checks into a lookup, and centralizes 29 backend-coupled regexes into a top-of-file constants block. No behaviour change for Chinese-locale users. + +### Goals + +- Every flagged `file:line` from issue #23 either substituted with a `t()` call backed by entries in both `locales/en.json` and `locales/zh.json`, **or** explicitly classified as a deliberate Chinese token (parser marker for backend compatibility) and added to the audit allowlist. +- `Step4Report.vue` parsers continue to function while the backend remains 100% Chinese, **and** are positioned for a single-file update when the backend prompt translation lands. +- `Step2EnvSetup.vue` stage-watcher tolerates legacy Chinese display strings, current snake_case identifiers, and any future English display strings without further frontend edits. +- A `frontend/scripts/audit-i18n-strings.sh` (or `.js`) check runs in under a minute, requires no backend, and reports zero unallowlisted CJK literals across the five files. + +### Non-Goals + +- Translating backend log messages, ontology/report agent prompts, or other backend code (covered by issues #24, #25 and the open `i18n-*-prompts` specs). +- Translating Chinese comments in source files (covered by issues #7 and #9). +- Frontend changes outside the five named files. +- Adding a CI gate for this audit (tracked under issue #26). +- Restoring the missing `.kiro/specs/i18n-e2e-english-verification/audit/scripts/run_audit.sh`. + +## Boundary Commitments + +### This Spec Owns + +- `frontend/src/views/Process.vue`: every user-visible Chinese literal flagged in the ticket and any sibling Chinese literal discovered while editing the same block. +- `frontend/src/components/Step2EnvSetup.vue`: stage-watcher logic at lines 678–692 (`STAGE_PHASE_MAP`). +- `frontend/src/components/Step3Simulation.vue`: the `'启动失败'` fallback at line 423/427. +- `frontend/src/components/Step4Report.vue`: all 29 regex parser markers (lines 555–943), the no-reply marker checks (lines 850/854/1325), the `'选择理由'` literal (line 1464), the `'等待开始'` literal (line 1774), and the log-classification literals (lines 2005–2006). +- `frontend/src/components/Step5Interaction.vue`: the chat-history templating (lines 721, 723). +- `locales/en.json` and `locales/zh.json`: new keys added by this spec, mirrored across both files with structurally aligned shape. +- `frontend/scripts/audit-i18n-strings.sh` (new): the small grep-based verifier for Requirement 6. + +### Out of Boundary + +- Backend prompt strings in `backend/app/services/zep_tools.py`, `report_agent.py`, etc. — the responsibility of `i18n-report-agent-prompts` and issue #25. +- Other Vue files. Even if their templates also contain Chinese literals, they are out of scope for this spec. +- Vue Router, auth, telemetry, accessibility — not affected. +- A more elaborate keys-parity tool — explicit non-goal; the existing `wc -l` agreement and a one-liner `jq` diff suffice. + +### Allowed Dependencies + +- `vue-i18n` 11 (already adopted; default and fallback locale `'zh'`; messages loaded from `/locales/*.json`). +- `frontend/src/i18n/index.js` (no changes). +- `locales/{en,zh,languages}.json` (new keys only). +- The structure of backend-emitted markers in `zep_tools.py` (read-only reference; not modified here). + +### Revalidation Triggers + +- The downstream backend prompt translation (issue #25 / `i18n-report-agent-prompts`) lands. → Update `REPORT_MARKERS` in `Step4Report.vue` to alternate Chinese/English wording (single-file edit). +- A new pipeline stage is added in `Step2EnvSetup.vue`. → Add a row to `STAGE_PHASE_MAP`. +- `locales/en.json` or `locales/zh.json` shape changes (new namespace, key removal). → Re-run `audit-i18n-strings.sh` and the parity diff. + +## Architecture + +### Existing Architecture Analysis + +The frontend already uses `vue-i18n` 11 throughout four of the five files. The pattern is uniform: `