From ef394667b766b5dd4f2acde1710e507d1d12095a Mon Sep 17 00:00:00 2001
From: peijunlei <pjl@suq.cn>
Date: Mon, 7 Sep 2026 14:51:35 +0800
Subject: [PATCH] docs: add EN demo UI i18n design spec

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../specs/2026-09-07-en-demo-ui-i18n-design.md     | 120 +++++++++++++++++++++
 1 file changed, 120 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-09-07-en-demo-ui-i18n-design.md

diff --git a/docs/superpowers/specs/2026-09-07-en-demo-ui-i18n-design.md b/docs/superpowers/specs/2026-09-07-en-demo-ui-i18n-design.md
new file mode 100644
index 0000000..9c2a2f3
--- /dev/null
+++ b/docs/superpowers/specs/2026-09-07-en-demo-ui-i18n-design.md
@@ -0,0 +1,120 @@
+# EN Demo UI Translation Design
+
+Date: 2026-09-07  
+Status: draft for user review  
+Approach: lightweight in-JS dictionary (Approach 1)
+
+## Goal
+
+Translate hardcoded Chinese UI copy in the English theme demo templates to English, and make shared frontend JS show English or Chinese based on the current UI language. Do not translate code comments. Do not machine-translate CMS/dynamic fields.
+
+## Scope
+
+### In scope
+
+- All HTML under `public/themes/website/1/en/demo/` (pages + `components/`), user-visible hardcoded Chinese only:
+  - Visible text nodes, button labels, placeholders, empty states
+  - `aria-label` / `title` / similar accessibility strings when Chinese
+  - Inline `<script>` user-facing strings (e.g. contact form alerts/toasts)
+  - Fix `html lang="zh-CN"` → `lang="en"` on EN demo pages
+- Shared JS under `public/themes/dist_static/static/js/` that currently hardcodes Chinese UI strings, including:
+  - `common.js` (e.g. stock quote delay note)
+  - `video.js`, `search.js`, `about.js`, `announce.js`, `category.js`
+  - `earth.js` city display names (bilingual maps)
+  - Any other shared page JS with user-visible Chinese (exclude comment-only Chinese)
+
+### Out of scope
+
+- Code comments (HTML/JS/CSS)
+- CMS / tag-driven content (`{$vo.title}`, descriptions, nav titles from backend, etc.)
+- Chinese theme templates under `website/1/zh/demo/`
+- Introducing a separate EN JS bundle or a full i18n build pipeline
+- Translating non-UI data blobs that are not shown (unless required for earth labels)
+
+## Language detection
+
+Reuse the existing front language model already used by the header switcher in `common.js`:
+
+- Allowed path prefixes include `en`, `zh`, …
+- **UI language for this work:** `en` when the first path segment is `en`; otherwise treat as `zh` for dictionary lookup (same as current EN/CN header UI mapping).
+- Optional fallback: `data-lang-current` on `.site-header__lang` when present.
+
+API:
+
+- `getUiLang()` → `'en' | 'zh'`
+- `t(key, vars?)` → localized string; supports simple `{name}` substitution if needed
+- Expose on `window` (e.g. `window.__uiLang`, `window.t`) so inline page scripts can call without imports
+
+## HTML translation rules
+
+- Prefer clear marketing / product-site English (not overly literal).
+- Brand: prefer **RAYNEN** / **Raynen Technology** where the Chinese UI said 睿能科技.
+- Stock currency: keep consistency with footer/investment (e.g. `Yuan` or `CNY` — pick one pair and use everywhere in EN templates).
+- Do not change URLs, class names, ThinkPHP tags, or CMS field bindings.
+- Leave Chinese comments in templates untouched.
+
+## JS i18n rules
+
+1. Add a small dictionary in `common.js` (zh + en) for shared keys.
+2. Replace hardcoded user-visible Chinese with `t('key')`.
+3. Module scripts that load after `common.js` (via existing `import "./common.js"`) use `t` from the shared helper (export or `window.t`).
+4. `earth.js`: keep coordinates; localize only `name` (and any other visible labels) via per-city zh/en fields or `t` keys.
+5. Comments stay Chinese; do not translate them.
+
+### Example keys (illustrative, not exhaustive)
+
+| Key | zh | en |
+|-----|----|----|
+| video.play | 视频播放 | Video |
+| filter.by_product | 按产品筛选 | Filter by product |
+| about.expand_more | 展开更多 | Show more |
+| about.collapse | 收起 | Show less |
+| stock.delay_note | 截止 {time}*报价有十五分钟或以上延迟。 | As of {time}* Quotes delayed by 15 minutes or more. |
+| contact.name_required | 请输入姓名 | Please enter your name |
+| … | … | … |
+
+Final key list is derived during implementation by scanning remaining Chinese UI strings.
+
+## Architecture
+
+```
+EN HTML templates  →  static English copy (no runtime)
+Shared JS          →  getUiLang() + t(key)  →  zh|en strings
+earth labels       →  bilingual name fields / t()
+Inline page JS     →  window.t(...)
+```
+
+No new npm dependency. No change to PHP `getStockInfo` beyond existing EN template/JS consumers.
+
+## Error handling
+
+- Missing key: fall back to zh string if present, else the key itself (dev-visible), never throw.
+- If `common.js` fails to load, inline scripts should degrade gracefully (prefer keeping EN hardcoded in EN templates; shared modules only matter for bilingual shared files).
+
+## Testing / acceptance
+
+1. Open representative `/en/...` pages: home, contact, download, search, investment, about (earth), video — UI chrome is English.
+2. Open same flows under default zh path — UI chrome remains Chinese.
+3. Contact form validation/toast strings follow language.
+4. Stock footer/investment delay sentence follows language; chart refresh still works.
+5. Earth city tooltips/labels English on `/en/`, Chinese on zh.
+6. Grep EN demo HTML for leftover user-visible Chinese in hardcoded spots (allow CMS echoes / comments).
+7. Confirm comments were not rewritten to English.
+
+## Non-goals / follow-ups
+
+- Full site localization of CMS content
+- Additional languages beyond zh/en UI mapping
+- Extracting i18n into separate JSON files (possible later refactor)
+
+## Implementation sequence (high level)
+
+1. Add `getUiLang` + `t` + base dictionary in `common.js`
+2. Wire shared JS call sites + earth city names
+3. Translate EN demo HTML page-by-page (components first: header/footer/mask/empty)
+4. Fix inline scripts + `lang` attributes
+5. Acceptance grep + smoke check
+
+## Approval
+
+Approach 1 approved by user ("方案 1直接开始"). This document captures the agreed design for the subsequent implementation plan.