Research & Design Decisions — i18n-backfill-zh-json

Summary

Feature: i18n-backfill-zh-json
Discovery Scope: Simple Addition (data-only edits to one JSON file).
Key Findings:
- All ten flagged keys in locales/zh.json currently hold the exact English value listed in issue #8 (verified via jq).
- en.json and zh.json key sets are currently identical (paths(scalars) diff is empty), so we must preserve that invariant.
- log.prepareTaskId is consumed by Step2EnvSetup.vue:801 via addLog(t('log.prepareTaskId', { taskId: ... })) — it IS user-facing, and surrounding log.* keys are translated; therefore we translate it.

Context: Confirm the issue's claim that ten specific values are English-only.
Sources Consulted: locales/zh.json, locales/en.json (via jq).
Findings:
- Each of the ten target keys in zh.json matches the English value in en.json byte-for-byte today.
- home.heroDescBrand is the brand name MiroFish and should stay English.
Implications: Direct value replacement is safe; no upstream changes have already translated any of them.

Context: Issue requires a documented decision on whether this value is locale-neutral scaffold or a user-facing string.
Sources Consulted: Grep for prepareTaskId across the repo; inspection of frontend/src/components/Step2EnvSetup.vue:801; inspection of sibling log.* values in zh.json.
Findings:
- The key is rendered into the in-UI log panel via addLog(t(...)).
- All sibling log.* values in zh.json are translated to natural Chinese while preserving placeholders and continuation glyphs.
Implications: Translate the value; preserve the leading two-space indent, the └─ glyph, and the {taskId} placeholder.

Context: Choose Chinese wordings consistent with the existing vocabulary so reviewers don't need to debate terminology.
Sources Consulted: jq dumps of home.*, step3.*, step4.*, step5.*, graph.*, agent.*, log.* in zh.json.
Findings:
- "Agent" → "智能体" (e.g. agent.title: "🤖 智能体详情").
- "Report Agent" → "报告智能体" (e.g. step4.reportAgentReady: "报告智能体就绪").
- "Graph" → "图谱" (e.g. existing graphLoadFailed: "图谱加载失败").
- "Task ID" → "任务 ID" — keeps "ID" as a loanword, which is the standard rendering in Chinese tech UIs and matches surrounding log-line tone.
Implications: Wording table in design.md follows these conventions; a native reviewer can still suggest polish but no reviewer should be surprised by the chosen vocabulary.

Option	Description	Strengths	Risks / Limitations	Notes
In-place value `Edit` (selected)	Use the `Edit` tool for each of the ten lines in `zh.json`	No risk of key reorder; minimal blast radius; reviewable diff	Requires care that `old_string` is unique per edit	Matches surrounding convention
`jq` script rewrite	One-off `jq --arg ... '.x = $v'` script	Mechanizable	Older `jq` versions may reorder object keys, breaking structural alignment	Rejected
Manual full-file rewrite via `Write`	Rewrite the file with new values	Fewer edits	Highest risk of accidental whitespace/key-order drift	Rejected

Context: Issue allows either choice, conditional on a documented rationale.
Alternatives Considered:
1. Leave English on the grounds that it is a "log scaffold".
2. Translate, matching the surrounding log.* translations.
Selected Approach: Translate to └─ 任务 ID: {taskId}.
Rationale: The key is consumed by a user-visible log panel (Step2EnvSetup.vue:801), and every other log.* key in zh.json is already translated. Leaving this one in English would be the inconsistent choice.
Trade-offs: None material; the indent and └─ glyph carry the scaffold semantics and are preserved.
Follow-up: Document the decision in the PR description so a reviewer can override if they prefer to keep "Task ID" as a literal technical identifier.

Context: Need to change ten values without disturbing key order or the file's whitespace.
Selected Approach: One Edit per key, matching the value with enough surrounding context to be unique.
Rationale: Edit operates on raw bytes — it cannot reorder keys or drop comments/whitespace. jq rewrites are not safe across all versions for object key order.
Trade-offs: Slightly more tool calls; offset by safety.
Follow-up: After the edits, run the alignment diff and the jq empty check before committing.

Translation polish disagreements — Reviewer may prefer different wording. Mitigation: PR description lists the chosen renderings and invites suggestions; copy changes are cheap.
Accidental placeholder drift — {count} or {taskId} lost during edit. Mitigation: post-edit grep check that each placeholder still appears exactly once in its key's value.
Accidental key reorder — JSON tooling sometimes reorders keys. Mitigation: use Edit only; do not run jq write-back.