MicroFish/.kiro/specs/i18n-frontend-ui-strings/research.md

# Research & Design Decisions — `i18n-frontend-ui-strings`

## Summary

- **Feature**: `i18n-frontend-ui-strings`
- **Discovery Scope**: Extension (existing Vue + vue-i18n adoption, brownfield codebase)
- **Key Findings**:
  - `Process.vue` has zero i18n adoption today; the other four files in scope are partially i18n'd. The volume of new keys lands almost entirely in `Process.vue` and falls under the existing `process.*` / `graph.*` / `step1.*` namespaces.
  - The 29 backend-coupled regexes in `Step4Report.vue` are matched against strings emitted by `backend/app/services/zep_tools.py` (and a few other services). Those backend strings are 100% Chinese today; the English translation of those prompts is owned by a *separate* spec (issue #25 / `i18n-report-agent-prompts` etc.) and has not landed.
  - The `Step5Interaction.vue` chat-history templating (`'提问者'`/`'你'`/`'以下是我们之前的对话：…'`) is *prompt content* sent to the LLM, not user-visible UI. It is safe to localize via `t()` because the backend report agent already accepts both Chinese and English (it's a multilingual LLM) and the wider initiative is moving the backend to English; the Chinese phrasing is preserved for the `zh` locale via `zh.json`.

## Research Log

### Backend marker emission audit

- **Context**: Requirement 5 demands that `Step4Report.vue` parsers tolerate post-translation backend output. We need to know what the backend emits today and whether the translated wording is already pinned.
- **Sources Consulted**:
  - `backend/app/services/zep_tools.py` (lines 47, 50, 78, 175–207, 258–276, 307–311, 379–395, 1365, 1424–1426, 1720)
  - `backend/app/services/oasis_profile_generator.py` (lines 424–475, 945)
  - GitHub issue #25 (open; backend prompt assembly translation not yet started)
  - `.kiro/specs/i18n-report-agent-prompts/` (open; tasks generated, not implemented)
- **Findings**:
  - All 29 markers/regexes used by the frontend originate from the listed backend files and are emitted as Chinese literals (e.g. `f"分析问题: {self.query}"`, `f"- 相关预测事实: {self.total_facts}条"`, `f"**采访人数:** {self.interviewed_count} / {self.total_agents} 位模拟Agent"`).
  - The English wording the backend will emit after translation is **not yet pinned** in the open spec. It will be decided when `i18n-report-agent-prompts` and #25 are implemented.
  - The no-reply markers (`（该平台未获得回复）`, `(该平台未获得回复)`, `[无回复]`) are also emitted by `zep_tools.py` as Chinese literals and used as user-visible "no answer" text in the report. These are the only markers whose translated wording we can reasonably anticipate (`(no response on this platform)` / `[no response]` etc.) and even those will be decided by the backend spec.
- **Implications**:
  - We cannot reliably encode English alternates for markers whose translated wording is undecided. Speculative English regexes risk silently failing once the backend translation chooses a different wording.
  - **Strategy**: centralize the markers in a single top-of-file constants block in `Step4Report.vue`, document them as "backend-coupled, deliberate Chinese — sync with `i18n-report-agent-prompts`", and surface them in the audit allowlist (Requirement 6). When the backend spec lands, a single-file edit updates every parser at once. This is the "deliberate" classification the ticket allows.
  - The log-severity classifier (`log.includes('错误')` / `log.includes('警告')`) is a special case: those substrings come from arbitrary log lines, not a fixed marker. Keep them with bilingual `OR` (`'ERROR'/'错误'/'WARNING'/'警告'` is already what the file does). No change required beyond noting it as deliberate.

### vue-i18n usage convention

- **Context**: Confirm the adoption pattern so the new substitutions match existing files.
- **Sources Consulted**: `frontend/src/i18n/index.js`; the four step components already using i18n; `locales/en.json` (1031 lines), `locales/zh.json` (1031 lines, aligned post-#20).
- **Findings**:
  - `<template>` uses `$t('namespace.key')` and `$t('namespace.key', { param })`; `<script setup>` uses `const { t } = useI18n()` then `t('namespace.key')`.
  - Existing namespaces: `common`, `meta`, `nav`, `home`, `main`, `step1` … `step5`, `graph`, `history`, `api`, `progress`, `log`, `report`, `console`. No `process` namespace yet; the `graph.*` namespace already covers ~5 of `Process.vue`'s graph-panel strings (refresh/maximize/loading) and should absorb those.
  - Default locale is `'zh'`; fallback locale is also `'zh'`. The frontend passes locale through `localStorage`. No SSR concerns.
- **Implications**:
  - Add a new `process.*` namespace for view-level strings. Reuse `graph.*` (already covers refresh/maximize/etc.) for graph-panel literals where a key already exists.
  - Add `step3.startFailed` (already exists — confirmed in en.json `step3.startFailed`), `step4.*` keys for the new Step4Report literals (`selectionReason`, `awaitingStart`, etc.), `step5.*` keys for the chat-history templating.

### Locale parity check

- **Context**: Issue #20 (`i18n-backfill-zh-json`) recently aligned `en.json` and `zh.json`. Don't regress that.
- **Sources Consulted**: `wc -l locales/{en,zh}.json` → both 1031.
- **Findings**: structurally aligned. Keys present in en.json are mirrored in zh.json. The discipline is fresh and respected.
- **Implications**: every new key added by this spec must land in *both* files in the same commit/PR. The existing audit script for parity is implicit — `diff <(jq -S 'keys_unsorted_recursive' en.json) <(jq -S 'keys_unsorted_recursive' zh.json)` is a one-liner that suffices. We will not add a CI gate (out of scope; tracked under issue #26).

## Architecture Pattern Evaluation

| Option | Description | Strengths | Risks / Limitations | Notes |
|--------|-------------|-----------|---------------------|-------|
| Pure extension (in-file `t()` substitution + add keys) | Match existing surrounding-file style; no new modules. | Smallest blast radius; reviewable file-by-file; aligns with steering "match the surrounding file's style." | Adds ~40 entries to each locale file; nothing centralized. | Picked for R1, R2, R3. |
| New `useStageMatcher` composable + `reportMarkers.js` util | Extract the two backend-coupled responsibilities (stage matching, parser markers) into shared modules. | Single source of truth; future backend translation is a one-line update. | More files; steering doc favours pipeline-stage logic *staying in* the matching Step component unless responsibilities truly diverge. They do diverge slightly (markers are coupled to backend, not to the Step's UI state). | Rejected for stage matcher (only 3 lines, not worth the extraction); chosen as in-file constants block for parser markers. |
| Hybrid (selected) | In-file `t()` substitution everywhere; in-file constants block for parser markers in `Step4Report.vue`; tiny in-file lookup for stage matcher in `Step2EnvSetup.vue`. | Balances clarity against the steering principle. Single edit when backend translation lands. | Constants block adds ~25 lines to `Step4Report.vue`. | **Selected**. |

## Design Decisions

### Decision: keep parser markers as in-file constants, not a separate utility

- **Context**: Requirement 5 wants the parsers to survive backend translation. The candidates for "where to put the marker definitions" are (a) inline in each parser, (b) top-of-file constants block, (c) separate `reportMarkers.js`.
- **Alternatives Considered**:
  1. **Inline** — what the file does today. Rejected: 29 markers scattered across 400+ lines makes a future single-file update impossible.
  2. **Separate utility module** — clean but pulls knowledge of report-agent output into a generic util that no other file uses. The steering doc's pipeline-aligned principle prefers staying in the Step component.
  3. **Top-of-file constants block** — selected.
- **Selected Approach**: A `const REPORT_MARKERS = { … }` block at the top of `Step4Report.vue`'s `<script setup>`, with each entry documenting the backend source line. Each parser uses `REPORT_MARKERS.foo.regex` instead of inlining the literal regex. When `i18n-report-agent-prompts` lands, the block is the only place that needs editing.
- **Rationale**: minimal architectural change; preserves the steering principle that pipeline-stage logic lives in the matching Step component; gives R5 a single defensible edit-site for the future backend update.
- **Trade-offs**: 25 extra lines in an already-large file (+0.06% of `Step4Report.vue`). Acceptable.
- **Follow-up**: when issue #25 / `i18n-report-agent-prompts` lands, edit `REPORT_MARKERS` to alternate Chinese/English forms.

### Decision: stage-matcher refactor, not stage-matcher extraction

- **Context**: `Step2EnvSetup.vue:680-689` has three string-equality checks (`'生成Agent人设'`, `'生成模拟配置'`, `'准备模拟脚本'`).
- **Alternatives Considered**:
  1. Leave alone — fails R4.
  2. Extract `useStageMatcher()` composable — over-engineered for 3 entries.
  3. Inline lookup map at top of file — selected.
- **Selected Approach**: a `const STAGE_PHASE_MAP = { 'generating_profiles': 1, '生成Agent人设': 1, 'generating_config': 2, '生成模拟配置': 2, 'copying_scripts': 2, '准备模拟脚本': 2 }`. Watcher becomes `phase.value = STAGE_PHASE_MAP[newStage] ?? phase.value`. New stages or new English forms are a one-line addition.
- **Rationale**: smallest possible refactor that satisfies R4.1, R4.2, R4.3, and R4.4.

### Decision: localize the `Step5Interaction.vue` chat-history templating

- **Context**: Lines 725 and 727 construct a prompt string that is sent **to the LLM**, not displayed to the user. There is a tension between (a) keeping it Chinese (matches the existing Chinese-tuned report agent) and (b) localizing it via `t()` (correct for English users, consistent with how the rest of the file handles strings).
- **Alternatives Considered**:
  1. Leave the literals — fails R2.3 of the spec; freezes the user's language back into Chinese once they enter the chat history flow.
  2. Always send English — breaks current Chinese behaviour.
  3. Localize via `t()` so the prompt language follows the active locale — selected.
- **Selected Approach**: introduce `step5.chatRolePrompter`, `step5.chatRoleYou`, `step5.chatHistoryPrefix`, `step5.chatNewQuestionPrefix`. Build the prompt with these keys.
- **Rationale**: report agents in this project run on multilingual LLMs (Qwen, GLM, MiniMax) that handle either input language. The Chinese phrasing is preserved exactly in `zh.json` so Chinese users see no behaviour change.
- **Trade-offs**: a Chinese-locale user chatting against an English-tuned model would have a slight mismatch — but this combination is not the production path, and would be a separate issue if/when it arises.
- **Follow-up**: if the report agent is later forced to a single language, revisit and pin to that language.

## Risks & Mitigations

- **R5 — encoding speculative English markers** that don't match what the backend ultimately emits → Mitigation: do not encode English alternates for markers whose translated wording is undecided; centralise into `REPORT_MARKERS` so the future backend spec can update them in one place. Add an explicit allowlist of deliberate Chinese tokens to the audit (Requirement 6).
- **R3 — locale-file drift** (en.json/zh.json key sets diverging) → Mitigation: add the `keys_unsorted_recursive` parity diff to the verification script in R6.
- **R1 — Process.vue review fatigue** (~40 substitutions in a 50KB file) → Mitigation: split the implementation tasks by logical block (header / building progress / errors / fallbacks / project-info modal) so the PR is reviewable section by section.
- **R2.3 — Step5 prompt language change** affects backend behaviour → Mitigation: preserve exact Chinese in `zh.json` so the production Chinese path is byte-identical to today; add an inline test or manual smoke-test note in the implementation tasks.

## References

- GitHub issue #23 — current ticket
- GitHub issue #11 — i18n epic (parent)
- GitHub issue #25 — backend LLM-prompt context label translation (downstream coordination point)
- GitHub issue #20 / spec `.kiro/specs/i18n-backfill-zh-json/` — locale parity precedent
- Open spec `.kiro/specs/i18n-report-agent-prompts/` — sibling backend translation spec; pinpointed as the future edit-trigger for `REPORT_MARKERS`
- `backend/app/services/zep_tools.py:47-1720` — canonical source of every backend marker the frontend parses
- vue-i18n 11 docs (already adopted; no new library decisions)