feat: refine i18n loading guardrails

Author: limityan

AGENTS-CN.md

@@ -54,6 +54,8 @@ pnpm run fmt:rs                     # 只格式化已改动 / 已暂存的 Rust
 pnpm run lint:web
 pnpm run type-check:web
 pnpm --dir src/mobile-web run type-check
+pnpm run i18n:contract:test
+pnpm run i18n:audit
 pnpm run check:repo-hygiene
 pnpm run check:github-config
 cargo check --workspace
@@ -78,6 +80,18 @@ pnpm run installer:build:fast         # 安装器应用，快速模式
 
 ## 全局规则
 
+### 国际化
+
+- Locale id、alias、fallback 和各形态默认语言统一由
+  `src/shared/i18n/contract/locales.json` 管理；修改后运行
+  `pnpm run i18n:generate`。
+- 跨形态稳定标签放在
+  `src/shared/i18n/resources/shared/<locale>/terms.json`；流程文案留在所属
+  产品形态资源中。
+- 不要把 Web UI locale 资源导入 `src/mobile-web`、`BitFun-Installer` 等较小形态。
+- Web UI 只急切加载 bootstrap namespace；路由或功能文案使用
+  `useI18n(namespace)`，直接 `i18nService.t(...)` 只用于 bootstrap namespace。
+
 ### 日志
 
 日志必须只用英文，且不能使用 emoji。
@@ -171,14 +185,15 @@ SessionManager → Session → DialogTurn → ModelRound
 
 | 改动类型 | 最低验证要求 |
 |---|---|
-| 前端 UI、状态、适配层或多语言文案 | `pnpm run lint:web && pnpm run type-check:web && pnpm --dir src/web-ui run test:run` |
+| 前端 UI、状态、适配层或多语言文案 | `pnpm run i18n:contract:test && pnpm run i18n:audit && pnpm run lint:web && pnpm run type-check:web && pnpm --dir src/web-ui run test:run` |
 | Mobile web UI、状态、配对、断开或重连行为 | `pnpm --dir src/mobile-web run type-check && pnpm run build:mobile-web`；行为变化还需要在 PR 中说明手动配对 / 重连验证 |
 | Deep Review / 代码审核团队行为 | 运行上面的前端验证，再运行 `cargo test -p bitfun-core deep_review -- --nocapture`；如果触及后端或 Tauri API，还需要运行下方 Rust / 桌面端验证 |
 | `core`、`transport`、`api-layer` 或共享服务中的 Rust 逻辑 | `cargo check --workspace && cargo test --workspace` |
 | 桌面端集成、Tauri API、browser/computer-use 或桌面专属行为 | `cargo check -p bitfun-desktop && cargo test -p bitfun-desktop` |
 | 被桌面端 smoke/functional 流覆盖的行为 | `cargo build -p bitfun-desktop` 后运行最接近的 E2E spec，或 `pnpm run e2e:test:l0` |
 | `src/crates/ai-adapters` | 运行上面相关 Rust 检查，**并且**运行 `cargo test -p bitfun-agent-stream` 验证 stream contract |
-| 安装器应用 | `pnpm run installer:build` |
+| 安装器前端、多语言或 locale contract | `pnpm --dir BitFun-Installer run type-check && cargo check --manifest-path BitFun-Installer/src-tauri/Cargo.toml && pnpm --dir BitFun-Installer run build` |
+| 安装器打包、payload、安装/卸载流程或 native bundling | `pnpm run installer:build` |
 
 ## 先看哪里
 

AGENTS.md

@@ -54,6 +54,8 @@ pnpm run fmt:rs                     # format only changed / staged Rust files
 pnpm run lint:web
 pnpm run type-check:web
 pnpm --dir src/mobile-web run type-check
+pnpm run i18n:contract:test
+pnpm run i18n:audit
 pnpm run check:repo-hygiene
 pnpm run check:github-config
 cargo check --workspace
@@ -88,6 +90,9 @@ For the full script list, see [`package.json`](package.json).
   in the owning product surface.
 - Do not import Web UI locale resources into smaller product surfaces such as
   `src/mobile-web` or `BitFun-Installer`. See `docs/architecture/i18n.md`.
+- Web UI loads only bootstrap namespaces eagerly; use `useI18n(namespace)` for
+  route or feature copy and keep direct `i18nService.t(...)` calls in bootstrap
+  namespaces.
 
 ### Logging
 
@@ -186,7 +191,7 @@ Session data is stored under `.bitfun/sessions/{session_id}/`.
 
 | Change type | Minimum verification |
 |---|---|
-| Frontend UI, state, adapters, or locales | `pnpm run lint:web && pnpm run type-check:web && pnpm --dir src/web-ui run test:run` |
+| Frontend UI, state, adapters, or locales | `pnpm run i18n:contract:test && pnpm run i18n:audit && pnpm run lint:web && pnpm run type-check:web && pnpm --dir src/web-ui run test:run` |
 | Mobile web UI, state, pairing, disconnect, or reconnect behavior | `pnpm --dir src/mobile-web run type-check && pnpm run build:mobile-web`; include manual pairing / reconnect verification when behavior changes |
 | Deep Review / Code Review Team behavior | Web UI verification above, plus `cargo test -p bitfun-core deep_review -- --nocapture`; also run the Rust / desktop rows below when backend or Tauri APIs are touched |
 | Shared Rust logic in `core`, `transport`, `api-layer`, or services | `cargo check --workspace && cargo test --workspace` |

BitFun-Installer/AGENTS-CN.md

@@ -17,6 +17,8 @@
 - `src-tauri/src/installer/shortcut.rs`：快捷方式创建
 - `src-tauri/src/installer/extract.rs`：压缩包解压
 - `src/hooks/useInstaller.ts`：前端安装流程状态
+- `src/i18n/`：安装器专属文案；locale 元数据由
+  `src/shared/i18n/contract/locales.json` 生成
 
 安装流程：
 
@@ -36,6 +38,16 @@ pnpm --dir BitFun-Installer run installer:build
 
 ## 验证
 
+前端、国际化、语言契约或非打包安装器改动，优先运行轻量检查：
+
+```bash
+pnpm --dir BitFun-Installer run type-check
+cargo check --manifest-path BitFun-Installer/src-tauri/Cargo.toml
+pnpm --dir BitFun-Installer run build
+```
+
+只有修改打包、payload、native bundling、安装/卸载流程、注册表、快捷方式或解压逻辑时，才运行完整安装器构建：
+
 ```bash
 pnpm --dir BitFun-Installer run type-check && pnpm --dir BitFun-Installer run installer:build
 ```

CONTRIBUTING.md

@@ -78,6 +78,15 @@ Captured data is logged as structured JSON under the `bitfun::devtools` target.
 - Frontend: `createLogger('ModuleName')`
 - Backend: `log::{info, debug, warn, error}` macros
 
+### Internationalization
+
+- Locale metadata lives in `src/shared/i18n/contract/locales.json`; run
+  `pnpm run i18n:generate` after editing it.
+- Put stable cross-surface labels in `src/shared/i18n/resources/shared`; keep
+  workflow copy in the owning surface.
+- Web UI route or feature copy should use `useI18n(namespace)`. Do not import
+  Web UI locale catalogs into mobile-web, installer, backend, or static pages.
+
 ### Platform-agnostic core
 
 Do not use platform-specific dependencies in `core`:
@@ -175,6 +184,7 @@ For `/usage` UI copy changes, keep `en-US`, `zh-CN`, and `zh-TW` locale strings
 | Change type | Recommended verification |
 | --- | --- |
 | Repository metadata, PR/issue templates, or GitHub workflows | `pnpm run check:repo-hygiene && pnpm run check:github-config && git diff --check` |
+| Locale contract, shared terms, or i18n resources | `pnpm run i18n:contract:test && pnpm run i18n:audit`, plus the touched surface checks |
 | Web UI, state, adapters, or locale changes | `pnpm run lint:web && pnpm run type-check:web && pnpm --dir src/web-ui run test:run` |
 | Mobile web UI, pairing, reconnect, disconnect, or chat-flow changes | `pnpm --dir src/mobile-web run type-check && pnpm run build:mobile-web` |
 | Rust core, transport, API layer, services, or shared runtime logic | `cargo check --workspace && cargo test --workspace` |

CONTRIBUTING_CN.md

@@ -78,6 +78,13 @@ pnpm run e2e:test
 - 前端：`createLogger('ModuleName')`
 - 后端：`log::{info, debug, warn, error}` 宏
 
+### 国际化
+
+- Locale 元数据统一维护在 `src/shared/i18n/contract/locales.json`；修改后运行
+  `pnpm run i18n:generate`。
+- 跨形态稳定标签放在 `src/shared/i18n/resources/shared`；流程文案留在所属形态资源中。
+- Web UI 路由或功能文案使用 `useI18n(namespace)`。不要把 Web UI locale 资源导入 mobile-web、installer、backend 或静态页面。
+
 ### 平台无关核心
 
 `core` 中禁止引入平台相关依赖：
@@ -169,6 +176,7 @@ UI 改动请附前后对比截图或短录屏，方便快速评审。
 | 改动类型 | 推荐验证 |
 | --- | --- |
 | 仓库元信息、PR/Issue 模板或 GitHub workflow | `pnpm run check:repo-hygiene && pnpm run check:github-config && git diff --check` |
+| Locale contract、shared terms 或国际化资源 | `pnpm run i18n:contract:test && pnpm run i18n:audit`，再加上被触及形态的检查 |
 | Web UI、状态、适配层或多语言文案 | `pnpm run lint:web && pnpm run type-check:web && pnpm --dir src/web-ui run test:run` |
 | Mobile web UI、配对、重连、断开或聊天流程 | `pnpm --dir src/mobile-web run type-check && pnpm run build:mobile-web` |
 | Rust core、transport、API layer、services 或共享运行时逻辑 | `cargo check --workspace && cargo test --workspace` |

docs/architecture/i18n.md

@@ -54,6 +54,7 @@ Surface resources stay in their existing owners:
 - Mobile Web: `src/mobile-web/src/i18n/messages.ts`
 - Installer: `BitFun-Installer/src/i18n/locales/*.json`
 - Backend: `src/crates/core/locales/*.ftl`
+- Relay static homepage: `src/apps/relay-server/static/homepage`
 
 Shared contract does not mean shared bundle. Importing Web UI locales from
 `mobile-web`, installer, backend, or another app is not allowed.
@@ -62,18 +63,25 @@ Shared contract does not mean shared bundle. Importing Web UI locales from
 
 The locale contract is shared; translation resources are not. Each surface must
 load only its own resource owner. Smaller surfaces should keep runtime loading
-to their current locale data, while Web UI keeps its current eager behavior
-until the later namespace-splitting work lands.
+to their current locale data.
 
-- Web UI owns Web UI namespaces. The current PR preserves the existing eager
-  namespace loading; later runtime work should split route or feature namespaces
-  into independently loadable chunks.
+- Web UI owns Web UI namespaces. It eagerly bootstraps only
+  `WEB_UI_BOOTSTRAP_NAMESPACES`, the small namespace set needed by synchronous
+  `i18nService.t(...)` call sites during module initialization. Other Web UI
+  namespaces load lazily through the i18next backend when a component requests
+  them with `useI18n(namespace)` or `i18nService.loadNamespace(namespace)`.
 - Mobile Web owns mobile-only resources and must not import Web UI locale
   catalogs.
 - Installer owns installer-only resources and must not depend on app runtime
   locale catalogs.
 - Backend owns backend Fluent resources and uses generated contract helpers for
   locale parsing, canonicalization, fallback order, and shared terms.
+- Relay static homepage is a self-contained static surface. It is tracked in the
+  contract and audit baseline, but it does not import runtime locale catalogs.
+
+Direct Web UI `i18nService.t('namespace:key')` calls are allowed only for
+bootstrap namespaces. Route, scene, and feature UI should use `useI18n(namespace)`
+so the namespace can be loaded on demand.
 
 ## Backend And Frontend Language Contract
 
@@ -95,3 +103,5 @@ store canonical ids.
 4. Run `pnpm run i18n:generate`.
 5. Run `pnpm run i18n:audit`.
 6. Run the focused type checks/builds for the touched surfaces.
+7. If a surface intentionally stays self-contained or does not support the new
+   locale, document that surface decision in the contract and PR.

docs/development/i18n.md

@@ -14,6 +14,9 @@
 - Do not import `src/web-ui/src/locales` from `src/mobile-web`,
   `BitFun-Installer`, Rust crates, or server apps.
 - Persist and send canonical app locale ids, not aliases.
+- In Web UI, request route or feature namespaces through `useI18n(namespace)`.
+  Add a namespace to `WEB_UI_BOOTSTRAP_NAMESPACES` only when a synchronous
+  `i18nService.t('namespace:key')` call must run during module initialization.
 
 ## Commands
 
@@ -97,12 +100,20 @@ Do not rely on literal fallback strings in component code. Add the missing key
 to the relevant locale file instead. Literal fallback strings make audits and
 translation completeness harder to enforce.
 
+`pnpm run i18n:audit` fails on missing or extra keys in Web UI, mobile-web, and
+installer locale resources. It also fails if the checked-in CJK source candidate
+budgets grow. Existing budget warnings are grandfathered; new user-facing copy
+should be extracted instead of increasing the baseline.
+
 ## Loading Size
 
 Unifying the language contract must not unify all translation bundles. Each
 surface should ship only the resource set needed for that surface and the current
-locale path. Web UI still uses its existing eager namespace loading in PR1; do
-not use that as a precedent for smaller surfaces.
+locale path.
+
+Web UI eagerly loads only bootstrap namespaces and lazy-loads all other
+namespaces. Mobile Web, Installer, Backend, and static relay pages must not
+import Web UI locale catalogs to reuse copy.
 
 For bundle-sensitive changes, compare generated asset sizes before and after the
 change and include the result in the PR.
@@ -127,3 +138,4 @@ Every i18n PR should state:
 - Whether generated files were updated.
 - Which i18n verification commands passed.
 - Whether any surface intentionally does not support a new locale.
+- Whether a hardcoded-copy budget changed, and why that increase is acceptable.