MicroFish/.kiro/specs/i18n-frontend-ui-strings/gap-analysis.md

# Gap Analysis — `i18n-frontend-ui-strings`

## 1. Scope and current state

The five files in scope are at very different stages of i18n adoption. The audit drilled into each one and uncovered substantially more flagged sites than the ticket body enumerated; the spec is broader in practice than its evidence list suggests.

| File                          | i18n adoption today                                                                                   | Touch surface                                                |
| ----------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `views/Process.vue`           | **None**. No `useI18n()` import, no `$t` calls. ~40 user-visible Chinese literals across template + JS. | All template headers, status badges, modal/info labels, error strings, fallback names. |
| `components/Step2EnvSetup.vue` | High (~70%). Templates already use `$t`. Remaining: 3 backend-stage equality checks (lines 680/682/689) and a few `console.warn` strings (not user-visible). | Stage-watcher logic only.                                   |
| `components/Step3Simulation.vue` | Sparse (1 `$t` call). The template is mostly English already, but the JS has `startError.value = res.error \|\| '启动失败'` (line 423/427). | A single fallback string.                                   |
| `components/Step4Report.vue`  | Sparse (2 `$t` calls). The bulk of the file is **29 regex patterns** matching Chinese section markers emitted by `report_agent.py`, plus three string-equality checks for the no-reply marker, plus a log-severity classifier. | Parser/regex layer + a small set of UI literals (e.g. line 1464 `'选择理由'`, line 1774 `'等待开始'`). |
| `components/Step5Interaction.vue` | Extensive (~35 `$t` calls). Two literals remain: lines 725 and 727 — both **prompt strings sent to the backend LLM**, not user-visible UI. | Prompt construction in the chat-history feature.            |

`createI18n` lives at `frontend/src/i18n/index.js`. Default locale is `'zh'` (read from `localStorage`), fallback `'zh'`. Locales come from repo-root `/locales/*.json` via `import.meta.glob`. Both `en.json` and `zh.json` are aligned at 1031 lines after issue #20's backfill.

The audit script the original ticket refers to (`.kiro/specs/i18n-e2e-english-verification/audit/scripts/run_audit.sh`) **does not exist** — only the empty directory shell remains. Verification has to be done by direct grep over the five files (Requirement 6).

## 2. Requirement-to-asset map

| Req | Need                                                                                  | Existing asset (file)                                                | Gap label                                              |
| --- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------ |
| R1  | Wire `useI18n()` into `Process.vue`; route ~40 strings through new `process.*` keys    | No i18n import; no `process.*` namespace yet                         | **Missing** — both wiring and namespace                |
| R2  | Externalize remaining UI literals in Step3/Step4/Step5                                 | `useI18n()` already imported in all three; namespaces `step3/4/5.*` exist | **Constraint** — match existing namespace structure   |
| R3  | en.json/zh.json parity for new keys                                                    | Issue #20 / spec `i18n-backfill-zh-json` already aligned them         | **Constraint** — must not regress; checker exists informally |
| R4  | Stage-name comparator that survives backend translation                                | `Step2EnvSetup.vue:679-692` watcher; backend emits both Chinese display strings and snake_case ids | **Missing** — small lookup map needed                  |
| R5  | Bilingual (Chinese + English) tolerance for 29 regex parsers + 3 marker checks + log classifier | `Step4Report.vue:557-943` regex block; `:1334`, `:2014-2015` checks | **Missing** — backend-coupled; depends on what translated prompts emit |
| R6  | Local verification check                                                               | Audit script gone; vanilla `grep` available                          | **Missing** — small script or documented one-liner    |

### Research-needed flags

- **Backend-emitted English strings** (R5) — issues #25 (LLM prompt assembly translation) and the open `i18n-report-agent-prompts` spec dictate what English markers `report_agent.py` will eventually emit (e.g., will it become `Analysis question:`, `Analyze question:`, or stay as a stable `分析问题:`?). The frontend can't pin its English regexes to specific wording until that backend spec is settled. **Mitigation strategy**: keep the existing Chinese regexes intact (for backwards compat with current backend) and add deliberately permissive English alternates that match a documented set of likely renderings, plus keep an explicit allowlist of "deliberate Chinese tokens for backend compatibility" so the audit doesn't re-flag them.
- **Step5Interaction.vue prompt strings** (lines 725, 727) — these are not UI; they are *prompt content sent to the LLM*. If the user is on `zh` locale and chats with a Chinese-trained agent, the Chinese phrasing is intentional. Two viable strategies: (a) localize to active locale via `t()` (correct linguistically; assumes the agent handles both), or (b) keep Chinese literally because the agent is currently Chinese-tuned. The wider initiative is moving the backend to English, so option (a) aligns better — but coordinating with the report agent's actual prompt translation (separate spec) would be ideal. For this spec, route through i18n keys and let the active locale dictate; document the assumption.

## 3. Implementation approach options

### Option A — Pure extension (recommended)

Treat this as a localized cleanup of five existing files plus locale-file additions. All work is "match the surrounding file's style," no new abstractions.

- **Files extended**: 5 Vue files + 2 locale files. No new files (or 1 new file: a small grep-based verifier).
- **Compatibility**: The new i18n keys layer onto an existing pattern (`step2.*`, `step4.*`, etc.). No public surface changes.
- **Complexity**: Low to medium. The big number is the count of strings, not their individual difficulty. The two genuinely tricky pieces are (i) the bilingual regex strategy in `Step4Report.vue`, (ii) the stage-comparator refactor in `Step2EnvSetup.vue`.

**Trade-offs**:

- ✅ Least architectural change; matches the steering principle "match the surrounding file's style."
- ✅ Each file's edits are independent; reviewable in isolation.
- ❌ Adds size to `Process.vue` (already ~50KB) — but the additions are mostly `t()` substitutions, not new logic.

### Option B — Extract a `useStageMatcher()` composable + a `parseReportSection()` utility

Make new files for the two backend-coupled responsibilities (R4 and R5):

- `frontend/src/composables/useStageMatcher.js` — owns the legacy-Chinese ↔ snake_case ↔ future-English equivalence map.
- `frontend/src/utils/reportParsers.js` — owns the bilingual regex set and exposes typed extractors.

**Trade-offs**:

- ✅ Cleaner separation; future backend-output changes localize into one parser file.
- ❌ Moves regexes out of `Step4Report.vue` where today they sit alongside the consumer; the steering doc favors keeping pipeline-stage logic in the matching Step component unless responsibilities truly diverge. Arguably they don't yet.
- ❌ Larger PR, more files for reviewers to navigate.

### Option C — Hybrid

Apply Option A everywhere, but extract `useStageMatcher()` (Option B's smaller half) because the stage equality check is duplicated three times in one watcher and obviously benefits from a single source of truth. Leave the `Step4Report.vue` parsers in place and add the bilingual alternates inline; this avoids designing an extraction boundary against a backend that's still being translated.

## 4. Recommendation

**Hybrid (Option C)**.

- **R1, R2, R3**: pure extension — substitute `t('…')` and add keys to both locale files.
- **R4**: introduce a tiny in-file lookup (or, if it earns its keep, a small composable) so that future stage strings only need adding in one place.
- **R5**: extend the existing regexes inline. Each parser becomes `chineseRegex.test(...) ? extract(chineseRegex) : englishRegex.exec(...)` (or an explicitly bilingual single regex like `/(?:分析问题|Analysis question):/`). Document the deliberate Chinese tokens at the top of the parser block so the verifier in R6 can allowlist them.
- **R6**: a `frontend/scripts/audit-i18n-strings.{sh,js}` (the existing repo has no equivalent yet) that greps the five files for unicode CJK literals minus an allowlist; runnable locally in seconds, no backend required. Keep it tiny — this is verification, not a new test framework.

**Effort**: **M** (3–7 days of focused work). The volume in `Process.vue` is significant (~40 keys), but each substitution is mechanical. R5 is the only piece with real design content.

**Risk**: **Medium**. Risk concentration:

- **R5 (parsers)** — Medium. If the backend prompt translations land between this PR's merge and a release, and the actual English wording doesn't match the alternates we encoded, reports degrade silently. Mitigation: write the alternates against the actual prompts in `backend/app/services/report_agent.py` rather than guessing, and keep all Chinese regexes alive as fallbacks for as long as the backend is partially-translated.
- **R3 (locale parity)** — Low. Tooling-aided; #20 just established the discipline.
- **R1 (Process.vue)** — Low individually, but the volume means review fatigue is a real risk. Recommend the PR call out logical chunks (header / progress / errors / fallback labels) so the reviewer can sign off section by section.

## 5. Research items to carry into design

1. Read `backend/app/services/report_agent.py` (and any prompt template referenced by it) to enumerate the *actual* English strings it emits *today*, not what we assume it will emit. The R5 regex alternates must be grounded in real backend output. Cross-reference the open spec `i18n-report-agent-prompts` for the planned English wording.
2. Confirm whether `Step2EnvSetup.vue:680-689` ever sees backend-emitted English display strings now, or only the snake_case identifiers. If only snake_case, the comparator can prefer those and treat the Chinese as backwards-compat-only.
3. Confirm that `Step5Interaction.vue:725-727` (chat history templating) is acceptable to localize via `t()` — i.e., that the report agent handles both `Question: …` and `提问者：…` framings of chat history. If not, leave Chinese in for now and open a separate ticket to migrate alongside the backend agent prompt translation.
4. Decide naming for the new `process.*` namespace: align with adjacent step namespaces (`step1.*` etc.) or use a fresher grouping. The existing `graph.*` namespace already covers some of the graph-panel headers and may absorb several of `Process.vue`'s strings rather than duplicating them.

---

## Output checklist

- ✅ Requirement-to-asset map with gaps tagged
- ✅ Options A/B/C with trade-offs
- ✅ Effort **M**, Risk **Medium** with justification
- ✅ Recommendation: Option C (hybrid)
- ✅ Research items carried forward