OpenFlare/docs/superpowers/specs/2026-07-24-frontend-i18n-design.md

# Frontend i18n Design

Date: 2026-07-24  
Status: Implemented in OpenFlare (ported from Wavelet 1625cfb, extended to product console)  
Scope: Frontend UI only

## 1. Goals

Add bilingual UI support for Wavelet frontend:

- Languages: `zh-CN` and `en`
- Default locale: `zh-CN`
- Locale resolution: explicit user choice → browser language → default
- Phase 1: infrastructure + core paths only (layout / auth / settings)
- Must remain compatible with `NEXT_STANDALONE_EXPORT` static export

### Non-goals (Phase 1)

- Backend API error / message localization
- Email / push notification localization
- URL locale prefixes (`/en/...`, `/zh-CN/...`) and SEO hreflang
- Full translation of all admin business pages

## 2. Context

Current state:

- Root layout hardcodes `lang='zh-CN'`
- UI copy is mostly Chinese string literals across many TSX files
- Date formatting often hardcodes `zh-CN` / `date-fns/locale` `zhCN`
- No i18n library is installed
- Frontend supports both normal Next rewrites mode and static export embed mode

## 3. Approach

Use **next-intl in non-routing / provider mode**.

Why this approach:

- Mature App Router integration and clear `useTranslations` API
- ICU message format ready when needed
- Avoids locale-prefixed routing, which conflicts with static-export simplicity and current route structure
- Cookie + browser detection matches product preference without SEO path requirements

Rejected alternatives:

- Fully custom Context + JSON: lower dependency cost, but reimplements interpolation/plurals/type safety poorly
- `i18next` + `react-i18next`: powerful, but heavier and less natural for this Next App Router setup

## 4. Architecture

```
RootLayout
  html lang={locale}
  ThemeProvider
    CustomThemeProvider
      AppQueryProvider
        NextIntlClientProvider(locale, messages)
          existing User / Notification / Bell providers
            pages + components
```

### Key files

| Path | Responsibility |
| --- | --- |
| `frontend/i18n/config.ts` | Supported locales, default locale, cookie name, normalize helpers |
| `frontend/i18n/request.ts` | `getRequestConfig` for server-side locale/messages resolution when not in export mode |
| `frontend/i18n/client.ts` | Client helpers to read/write locale preference |
| `frontend/messages/zh-CN.json` | Chinese messages |
| `frontend/messages/en.json` | English messages |
| `frontend/components/common/language-switcher.tsx` (or under `layout/`) | Language switch UI |
| `frontend/lib/i18n-format.ts` (optional location under `i18n/`) | Locale-aware date/number formatting helpers |

### Runtime flow

1. Resolve locale: cookie `NEXT_LOCALE` → browser languages → `zh-CN`
2. Load `messages/{locale}.json`
3. Provide locale + messages through `NextIntlClientProvider`
4. Components call `useTranslations('<namespace>')`
5. Language switcher writes cookie and refreshes locale/messages
6. Update `document.documentElement.lang`

## 5. Locale Resolution

Supported locales: `zh-CN`, `en`

Normalization:

- `zh`, `zh-CN`, `zh-Hans*` → `zh-CN`
- `en`, `en-US`, `en-GB`, other `en-*` → `en`
- anything else → `zh-CN`

Priority:

1. User explicit choice stored in cookie `NEXT_LOCALE`
2. Browser language (`Accept-Language` on server, `navigator.languages` on client)
3. Default `zh-CN`

Invalid cookie values are normalized to a supported locale and may be rewritten to a valid value.

## 6. Static Export Compatibility

Constraints:

- No locale-segment routes
- No middleware-based locale rewriting required for correctness
- `build:embed` (`NEXT_STANDALONE_EXPORT=true`) must continue to work

Behavior:

- **Normal SSR/dev**: resolve locale on server when possible to reduce first-paint language flash
- **Static export**: ship both message catalogs; resolve on client from cookie/browser; accept a brief default-language flash similar to theme hydration, using existing `suppressHydrationWarning` patterns where needed

## 7. Message Organization

Single catalog files with nested namespaces:

```json
{
  "common": {
    "save": "保存",
    "cancel": "取消",
    "loading": "加载中..."
  },
  "layout": {
    "nav": {
      "home": "首页",
      "myFiles": "我的文件"
    },
    "userMenu": {
      "settings": "设置",
      "logout": "退出登录"
    }
  },
  "auth": {
    "login": {
      "title": "登录",
      "submit": "登录"
    }
  },
  "settings": {
    "appearance": {
      "language": "语言",
      "languageDesc": "选择界面显示语言"
    }
  }
}
```

Conventions:

- Keys use camelCase and hierarchical grouping
- Prefer complete phrases as values; avoid assembling sentences in components
- Use ICU only when needed (`{name}`, plural forms)
- Backend `error_msg` values are shown as-is in Phase 1
- Frontend-owned toast / validation copy is translated

Both locale files must keep the same key tree. A key-alignment check script is recommended.

## 8. Language Switcher UX

Placement:

- Header toolbar near theme controls
- Appearance settings page as an explicit preference row

UI labels for language options use native names and do not themselves translate:

- `中文`
- `English`

On change:

1. Persist `NEXT_LOCALE`
2. Apply new locale/messages (via refresh or controlled provider update)
3. Sync `document.documentElement.lang`
4. Preserve unrelated UI state where practical (theme, auth session, sidebar collapse)

## 9. Phase 1 Migration Scope

### In scope

- Install and wire `next-intl`
- Message catalogs for core namespaces
- Locale resolution + persistence
- `LanguageSwitcher`
- Translate:
  - layout shell: sidebar nav/user menu, header accessible labels / titles
  - auth: login / register / OTP labels, buttons, validation messages
  - settings: appearance (including language preference), profile, security, notifications, access-token visible copy
- Replace date/number hardcoding only where touched by the above paths
- Ensure `html lang` reflects active locale

### Out of scope

- Remaining admin pages and deep business modules
- Backend localization
- Route prefixing / SEO alternate links

Unmigrated pages may remain Chinese hard-coded; mixed-language UI is acceptable during incremental rollout.

## 10. Formatting Helpers

Introduce locale-aware helpers for dates/numbers used by migrated surfaces, e.g.:

- `formatDateTime(value, locale)`
- `formatNumber(value, locale)`

`date-fns` locale objects should follow active locale (`zhCN` / `enUS`) when a migrated component uses them.

## 11. Error Handling & Fallbacks

| Case | Behavior |
| --- | --- |
| Missing message key | Dev warning; do not crash; show key or fallback language value |
| Unsupported cookie locale | Normalize to supported locale / default |
| Partial migration | Keep hard-coded Chinese on unmigrated screens |
| Backend error strings | Display raw `error_msg` |

## 12. Testing & Acceptance

Manual:

1. No cookie + browser Chinese → Chinese UI
2. No cookie + browser English → English UI
3. Manual switch to English survives refresh
4. Manual switch back to Chinese survives refresh
5. Core paths (layout/auth/settings) have no major residual hard-coded Chinese UI copy
6. `pnpm build` and `pnpm build:embed` both succeed
7. Language switch does not break theme, session, or sidebar state

Automated (recommended):

- Unit tests for `normalizeLocale` / resolution priority
- Script or test asserting `zh-CN.json` and `en.json` key parity

## 13. Rollout Plan (high level)

1. Add i18n infrastructure and empty/core message files
2. Mount provider and language switcher
3. Migrate layout shell copy
4. Migrate auth copy
5. Migrate settings copy + appearance language control
6. Verify SSR and static-export builds
7. Document how later pages should adopt `useTranslations`

## 14. Open Implementation Notes

- Prefer cookie name `NEXT_LOCALE` unless an existing project cookie convention conflicts during implementation
- Prefer minimal surface-area integration with next-intl; avoid introducing locale-based routing APIs that break static export
- Keep `internal/util` and backend packages untouched
- After implementation, follow repo frontend conventions and existing provider composition style