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

Add a small dictionary in common.js (zh + en) for shared keys.
Replace hardcoded user-visible Chinese with t('key').
Module scripts that load after common.js (via existing import "./common.js") use t from the shared helper (export or window.t).
earth.js: keep coordinates; localize only name (and any other visible labels) via per-city zh/en fields or t keys.
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

Open representative /en/... pages: home, contact, download, search, investment, about (earth), video — UI chrome is English.
Open same flows under default zh path — UI chrome remains Chinese.
Contact form validation/toast strings follow language.
Stock footer/investment delay sentence follows language; chart refresh still works.
Earth city tooltips/labels English on /en/, Chinese on zh.
Grep EN demo HTML for leftover user-visible Chinese in hardcoded spots (allow CMS echoes / comments).
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)

Add getUiLang + t + base dictionary in common.js
Wire shared JS call sites + earth city names
Translate EN demo HTML page-by-page (components first: header/footer/mask/empty)
Fix inline scripts + lang attributes
Acceptance grep + smoke check

Approval

Approach 1 approved by user ("方案 1直接开始"). This document captures the agreed design for the subsequent implementation plan.

5.4 KiB Raw Blame History