docs: add EN demo UI i18n implementation plan

Co-authored-by: Cursor <cursoragent@cursor.com>
2 weeks ago · 079c74fa18
1 changed files with 504 additions and 0 deletions
--- a/docs/superpowers/plans/2026-09-07-en-demo-ui-i18n.md
+++ b/docs/superpowers/plans/2026-09-07-en-demo-ui-i18n.md
@ -0,0 +1,504 @@
 # EN Demo UI i18n Implementation Plan
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 **Goal:** Make `website/1/en/demo` hardcoded UI English, and make shared JS show zh/en copy from a lightweight `t()` dictionary based on URL language.
 **Architecture:** Add `getUiLang()` + `t(key, vars?)` + a zh/en map in `common.js` (exposed on `window`). Replace user-visible Chinese in shared JS with `t()`. Translate EN demo HTML/static strings in place. Leave comments and CMS-bound fields alone.
 **Tech Stack:** ThinkPHP theme HTML, shared Vite-built static JS under `public/themes/dist_static/static/js/`, existing URL lang prefix (`/en/...`).
 **Spec:** `docs/superpowers/specs/2026-09-07-en-demo-ui-i18n-design.md`
 ## Global Constraints
 - Translate **user-visible hardcoded UI only** (not code comments).
 - Do **not** translate CMS/tag output (`{$vo.title}`, nav titles from backend, etc.).
 - Do **not** modify `website/1/zh/demo/` templates for copy (shared JS only, bilingual).
 - Do **not** translate SVG internal `id="矢量…"` / `id="微信 1"` attributes (not user-visible).
 - Brand in EN UI: **RAYNEN** / **Raynen Technology**.
 - Currency wording in EN: use **Yuan** (e.g. footer unit text).
 - UI lang: first path segment `en` → `en`, else `zh` (same as header EN/CN mapping).
 - Missing `t` key: return zh string if present, else the key; never throw.
 - Verification is **grep + manual smoke** (no PHPUnit/Jest in this theme path).
 ## File map
 | File | Responsibility |
 |------|----------------|
 | `public/themes/dist_static/static/js/common.js` | `getUiLang`, `t`, dictionary, stock delay string via `t` |
 | `video.js` / `search.js` / `about.js` / `announce.js` / `category.js` | Replace hardcoded UI Chinese with `t()` |
 | `earth.js` | Bilingual city names + Fuzhou tooltip |
 | `public/themes/website/1/en/demo/components/*.html` | Header/footer/mask/empty EN chrome |
 | `public/themes/website/1/en/demo/*.html` | Page EN chrome + `lang="en"` + inline script strings |
 ---
 ### Task 1: Add `getUiLang` + `t` + base dictionary in `common.js`
 **Files:**
 - Modify: `public/themes/dist_static/static/js/common.js`
 - Test: browser console / grep (no unit test harness)
 **Interfaces:**
 - Produces:
  - `getUiLang(): 'en' | 'zh'`
  - `t(key: string, vars?: Record<string, string|number>): string`
  - `window.getUiLang`, `window.t` (same functions)
 - Consumes: `location.pathname`; optional `.site-header__lang[data-lang-current]`
 - [ ] **Step 1: Insert helper + dictionary near top of the `$(function(){...})` region (after Lenis/AOS init is fine; before stock refresh)**
 Add (exact initial keys — extend later if grep finds more):
 ```javascript
 	const UI_I18N = {
 		zh: {
 			"video.play": "视频播放",
 			"filter.by_product": "按产品筛选",
 			"about.expand_more": "展开更多",
 			"about.collapse": "收起",
 			"brand.short": "睿能科技",
 			"stock.delay_note": "截止 {time}*报价有十五分钟或以上延迟。",
 			"contact.name_required": "请输入姓名",
 			"contact.phone_required": "请输入手机号",
 			"contact.company_required": "请输入公司名称",
 			"contact.email_required": "请输入邮箱",
 			"contact.submitting": "提交中...",
 			"contact.submit": "提交",
 			"contact.success": "提交成功，我们会尽快与您联系！",
 			"contact.fail": "提交失败，请稍后重试",
 			"contact.network_error": "网络错误，请稍后重试",
 			"earth.hq_fuzhou": "全球总部福州",
 			"earth.hq_fuzhou_html": "全球总部<br>福州"
 		},
 		en: {
 			"video.play": "Video",
 			"filter.by_product": "Filter by product",
 			"about.expand_more": "Show more",
 			"about.collapse": "Show less",
 			"brand.short": "RAYNEN",
 			"stock.delay_note": "As of {time}* Quotes delayed by 15 minutes or more.",
 			"contact.name_required": "Please enter your name",
 			"contact.phone_required": "Please enter your phone number",
 			"contact.company_required": "Please enter your company name",
 			"contact.email_required": "Please enter your email",
 			"contact.submitting": "Submitting...",
 			"contact.submit": "Submit",
 			"contact.success": "Submitted successfully. We will contact you soon.",
 			"contact.fail": "Submission failed. Please try again later.",
 			"contact.network_error": "Network error. Please try again later.",
 			"earth.hq_fuzhou": "Global HQ Fuzhou",
 			"earth.hq_fuzhou_html": "Global HQ<br>Fuzhou"
 		}
 	};
 	function getUiLang() {
 		const fromHeader = document.querySelector(".site-header__lang")?.getAttribute("data-lang-current");
 		if (fromHeader === "en" || fromHeader === "zh") return fromHeader;
 		const seg = location.pathname.replace(/^\//, "").split("/")[0] || "";
 		return seg === "en" ? "en" : "zh";
 	}
 	function t(key, vars) {
 		const lang = getUiLang();
 		const table = UI_I18N[lang] || UI_I18N.zh;
 		let str = table[key] ?? UI_I18N.zh[key] ?? key;
 		if (vars && typeof vars === "object") {
 			Object.keys(vars).forEach((k) => {
 				str = str.replace(new RegExp(`\\{${k}\\}`, "g"), String(vars[k]));
 			});
 		}
 		return str;
 	}
 	window.getUiLang = getUiLang;
 	window.t = t;
 ```
 - [ ] **Step 2: Replace stock delay assignment to use `t`**
 Find in `initStockQuoteRefresh` / `applyQuote`:
 ```javascript
 timeEl.textContent = `截止 ${data.updateTime}*报价有十五分钟或以上延迟。`;
 ```
 Replace with:
 ```javascript
 timeEl.textContent = t("stock.delay_note", { time: data.updateTime });
 ```
 - [ ] **Step 3: Verify helper in browser**
 Open `/en/` any page with DevTools:
 ```javascript
 getUiLang()  // "en"
 t("video.play")  // "Video"
 t("stock.delay_note", { time: "2026-09-07 10:00:00" })
 ```
 Open a zh page: `getUiLang()` → `"zh"`, `t("video.play")` → `"视频播放"`.
 - [ ] **Step 4: Commit**
 ```bash
 git add public/themes/dist_static/static/js/common.js
 git commit -m "feat(i18n): add getUiLang/t dictionary for shared UI strings"
 ```
 ---
 ### Task 2: Wire shared page JS to `t()`
 **Files:**
 - Modify: `public/themes/dist_static/static/js/video.js`
 - Modify: `public/themes/dist_static/static/js/search.js`
 - Modify: `public/themes/dist_static/static/js/about.js`
 - Modify: `public/themes/dist_static/static/js/announce.js`
 - Modify: `public/themes/dist_static/static/js/category.js`
 **Interfaces:**
 - Consumes: `window.t` / `t` (common.js loaded first via `import "./common.js"`)
 - [ ] **Step 1: Update `video.js`**
 Replace `"视频播放"` defaults with `t("video.play")`.  
 Replace `$btn.find("span").text("按产品筛选")` with `t("filter.by_product")`.
 - [ ] **Step 2: Update `search.js`**
 Replace `"视频播放"` fallbacks with `t("video.play")`.  
 Keep the `/^播放[：:]/` strip for aria-label parsing (works for Chinese CMS labels); if EN aria uses `Play:`, also allow:
 ```javascript
 card.getAttribute("aria-label")?.replace(/^(播放|Play)\s*[：:]\s*/i, "").trim() || t("video.play")
 ```
 - [ ] **Step 3: Update `about.js`**
 ```javascript
 btn.querySelector("span").textContent = expanded ? t("about.collapse") : t("about.expand_more");
 ```
 - [ ] **Step 4: Update `announce.js`**
 ```javascript
 $btn.find("span").text(t("filter.by_product"));
 ```
 - [ ] **Step 5: Update `category.js`**
 ```javascript
 if (name) document.title = `${name} - ${t("brand.short")}`;
 ```
 - [ ] **Step 6: Smoke**
 - `/en/video.html` (or routed EN video): default modal title English when empty.  
 - `/about` zh: toggle still 展开更多/收起.  
 - `/en/about`: Show more / Show less.
 - [ ] **Step 7: Commit**
 ```bash
 git add public/themes/dist_static/static/js/video.js public/themes/dist_static/static/js/search.js public/themes/dist_static/static/js/about.js public/themes/dist_static/static/js/announce.js public/themes/dist_static/static/js/category.js
 git commit -m "feat(i18n): localize shared page JS UI strings via t()"
 ```
 ---
 ### Task 3: Localize `earth.js` city names + HQ tooltip
 **Files:**
 - Modify: `public/themes/dist_static/static/js/earth.js`
 **Interfaces:**
 - Consumes: `getUiLang()`, `t()`
 - Produces: markers whose displayed `name` matches UI lang
 - [ ] **Step 1: Change `markersData` entries to bilingual names**
 Pattern for each city:
 ```javascript
 {
  nameZh: "上海",
  nameEn: "Shanghai",
  lat: 31.2304,
  lon: 121.4737
 },
 ```
 Full English map (use exactly):
 | nameZh | nameEn |
 |--------|--------|
 | 上海 | Shanghai |
 | 东京 | Tokyo |
 | 伊斯坦布尔 | Istanbul |
 | 伦敦 | London |
 | 加尔各答 | Kolkata |
 | 北京 | Beijing |
 | 华沙 | Warsaw |
 | 南京 | Nanjing |
 | 吉隆坡 | Kuala Lumpur |
 | 圣保罗 | São Paulo |
 | 圣安东尼奥 | San Antonio |
 | 墨西哥城 | Mexico City |
 | 多伦多 | Toronto |
 | 奥克兰 | Auckland |
 | 孟买 | Mumbai |
 | 安地比斯 | (keep transliteration from existing intent; if unclear use original pinyin/English already known — **Antananarivo** only if that was the city; otherwise keep a clear English label matching lat/lon) |
 | 山景城 | Mountain View |
 | 巴黎 | Paris |
 | 布宜诺斯艾利斯 | Buenos Aires |
 | 开普敦 | Cape Town |
 | 悉尼 | Sydney |
 | 新加坡 | Singapore |
 | 新德里 | New Delhi |
 | 曼谷 | Bangkok |
 | 法兰克福 | Frankfurt |
 | 波哥大 | Bogotá |
 | 深圳 | Shenzhen |
 | 牛津 | Oxford |
 | 特拉维夫 | Tel Aviv |
 | 科伦坡 | Colombo |
 | 米兰 | Milan |
 | 纽约 | New York |
 | 莫斯科 | Moscow |
 | 达卡 | Dhaka |
 | 迪拜 | Dubai |
 | 邦加罗尔 | Bengaluru |
 | 金奈 | Chennai |
 | 雅加达 | Jakarta |
 | 首尔 | Seoul |
 | 香港 | Hong Kong |
 | 全球总部福州 | Global HQ Fuzhou |
 If “安地比斯” coordinates are unclear, keep `nameEn` as a reasonable English label and do not invent a wrong city.
 - [ ] **Step 2: Resolve display name when creating markers**
 Replace `data.name` usage:
 ```javascript
 function markerName(data) {
  return getUiLang() === "en" ? (data.nameEn || data.nameZh) : (data.nameZh || data.nameEn);
 }
 ```
 Update:
 - `if (data.name === "全球总部福州")` → `if (data.nameZh === "全球总部福州")`
 - `marker.userData = { name: markerName(data) };`
 - `fuzhouTooltip.innerHTML = t("earth.hq_fuzhou_html");`
 Ensure `earth.js` runs after `common.js` on pages that load both (home/about already modulepreload common via page entry). If `earth.js` is a standalone module without import, add at top of its runtime:
 ```javascript
 const getUiLang = window.getUiLang || (() => (location.pathname.split("/")[1] === "en" ? "en" : "zh"));
 const t = window.t || ((k) => k);
 ```
 - [ ] **Step 3: Smoke**
 - `/en/` home or about: hover marker → English city name; Fuzhou tooltip English.  
 - zh home: Chinese names unchanged.
 - [ ] **Step 4: Commit**
 ```bash
 git add public/themes/dist_static/static/js/earth.js
 git commit -m "feat(i18n): bilingual earth marker city names"
 ```
 ---
 ### Task 4: Translate EN shared components (header / footer / mask / empty)
 **Files:**
 - Modify: `public/themes/website/1/en/demo/components/header.html`
 - Modify: `public/themes/website/1/en/demo/components/footer.html`
 - Modify: `public/themes/website/1/en/demo/components/mask.html`
 - Modify: `public/themes/website/1/en/demo/components/empty.html`
 - [ ] **Step 1: Translate user-visible hardcoded strings**
 Examples (apply consistently; leave PHP comments Chinese):
 - `aria-label="社交账号"` → `Social accounts`
 - `aria-label="微信"` → `WeChat` (popup caption `官方微信` → `Official WeChat`)
 - `aria-label="抖音"` → `Douyin` (or TikTok if product prefers — use **Douyin**)
 - `微博` → `Weibo`; `知乎` → `Zhihu`
 - `切换语言` → `Switch language`
 - `主导航` / `移动导航` → `Main navigation` / `Mobile navigation`
 - `搜索` → `Search`; `关闭导航菜单` → `Close menu`
 - `展开/收起` → `Expand/collapse`
 - Logo `aria-label` / `alt`: `RAYNEN` or `RAYNEN Technology` (drop Chinese in EN alt)
 - Footer: `股票代码` → `Stock code`; `关注我们：` → `Follow us:`; `官方微信` → `Official WeChat`; `官方视频号` → `Official Channels`; `版权所有` → `All rights reserved`; `网站地图` → `Sitemap`; `隐私声明` → `Privacy Policy`
 - Footer unit `元` → `Yuan`
 - Promo hardcoded `了解睿能最新展会信息` → `Learn about RAYNEN’s latest events` (only if hardcoded, not from CMS)
 - Hardcoded `解决方案` label if not from `$vo.title` → `Solutions`
 Do **not** change `{hcTaglib:nav}` titles.
 - [ ] **Step 2: Grep components for leftover visible Chinese**
 ```bash
 rg -n "[\p{Han}]" public/themes/website/1/en/demo/components --glob "*.html"
 ```
 Ignore: comments, SVG ids, PHP comments, CMS echoes.
 - [ ] **Step 3: Commit**
 ```bash
 git add public/themes/website/1/en/demo/components
 git commit -m "feat(i18n): English copy for EN demo header/footer/mask/empty"
 ```
 ---
 ### Task 5: Translate EN page templates + set `lang="en"`
 **Files:**
 - Modify all under `public/themes/website/1/en/demo/*.html` that still have `lang="zh-CN"` or hardcoded Chinese UI
 Pages: `single_index`, `contact`, `product`, `about`, `investment`, `solution`, `solution2`, `news`, `news-detail`, `search`, `single_search`, `download`, `faq`, `video`, `announce`, `category`
 - [ ] **Step 1: Batch fix `html` lang**
 Replace on every EN demo page:
 ```html
 <html lang="zh-CN">
 ```
 →
 ```html
 <html lang="en">
 ```
 - [ ] **Step 2: Translate page chrome (common patterns)**
 Apply across pages where hardcoded:
 | zh | en |
 |----|----|
 | 探索更多 | Explore more |
 | 立即下载 | Download |
 | 请输入您想了解的内容 | Search what you want to know |
 | 请输入您想下载的文件 | Search files to download |
 | 请输入您想搜索问题的关键词 | Search FAQ keywords |
 | 请输入您想搜索视频的关键词 | Search video keywords |
 | 暂无相关资料 / 问题 / 视频 | No matching resources / FAQs / videos |
 | 视频播放 | Video |
 | 了解产品 | Learn more |
 | 资料下载 | Downloads |
 | 股票信息 / 股票代码 | Stock information / Stock code |
 | 最高（元）等 metrics | High (Yuan), Low (Yuan), Volume (10k lots), Turnover (CNY 10k) — keep units clear |
 | 客服热线 | Hotline |
 | 下载中心 / 常见问题 / 视频教程 / 产品公告 | Download Center / FAQ / Video Tutorials / Product Notices |
 | Contact form labels/placeholders/options/submit | Natural EN (Name, Phone, Company, Email, Industry, Business type, …) |
 `contact.html` select **options**: translate both visible text and `value` to English in the EN template only (EN form posts English values).
 - [ ] **Step 3: Translate `contact.html` inline script strings via `window.t`**
 ```javascript
 if (!name) { alert(t("contact.name_required")); return; }
 if (!phone) { alert(t("contact.phone_required")); return; }
 if (!company) { alert(t("contact.company_required")); return; }
 if (!email) { alert(t("contact.email_required")); return; }
 // ...
 $submitBtn.prop("disabled", true).text(t("contact.submitting"));
 // success:
 showFormToast(t("contact.success"));
 // fail:
 alert(res.msg || t("contact.fail"));
 // network:
 alert(t("contact.network_error"));
 // complete:
 $submitBtn.prop("disabled", false).text(t("contact.submit"));
 ```
 Leave Chinese comments in that script untouched.
 - [ ] **Step 4: Grep EN demo pages**
 ```bash
 rg -n "[\p{Han}]" public/themes/website/1/en/demo --glob "*.html"
 ```
 Triage each hit: comment / SVG id / CMS / must-fix UI.
 - [ ] **Step 5: Smoke checklist**
 - `/en/contact.html`: form UI English; validation English.  
 - `/en/download.html`: placeholders + Download.  
 - `/en/` home: Explore more buttons English.  
 - `/en/investment.html`: stock section labels English; delay note English after refresh.  
 - zh contact still Chinese.
 - [ ] **Step 6: Commit**
 ```bash
 git add public/themes/website/1/en/demo
 git commit -m "feat(i18n): English UI copy for EN demo pages"
 ```
 ---
 ### Task 6: Final acceptance sweep
 **Files:** none new (verification only)
 - [ ] **Step 1: Shared JS user-string grep**
 ```bash
 rg -n "[\p{Han}]" public/themes/dist_static/static/js --glob "*.js"
 ```
 Allowed leftovers: comments only; earth `nameZh` fields; dictionary `zh` entries in `common.js`.
 - [ ] **Step 2: Confirm zh site not broken**
 Spot-check zh home, about expand, video modal, footer stock note → Chinese.
 - [ ] **Step 3: Confirm EN site**
 Spot-check EN home, contact, investment, about earth tooltips → English chrome.
 - [ ] **Step 4: Commit only if tiny fixes were needed; otherwise done**
 ```bash
 git status
 # if fixups:
 git add -u
 git commit -m "fix(i18n): leftover EN demo UI strings"
 ```
 ---
 ## Spec coverage check
 | Spec requirement | Task |
 |------------------|------|
 | EN demo hardcoded UI → English | 4, 5 |
 | Shared JS bilingual via dictionary | 1, 2 |
 | earth city names | 3 |
 | Comments not translated | Global + all tasks |
 | CMS fields untouched | Global |
 | `html lang=en` | 5 |
 | `getUiLang` / URL `en` prefix | 1 |
 | Stock delay note i18n | 1 |
 | Contact inline alerts | 5 |
 | Acceptance grep/smoke | 6 |
 ## Placeholder scan
 No TBD/TODO steps; commands and key tables are concrete.