feat: refine i18n loading guardrails

AGENTS-CN.md

@@ -37,7 +37,10 @@ BitFun 是一个由 Rust workspace 与 React 前端组成的项目。
 | 安装器 | `BitFun-Installer` | [AGENTS.md](BitFun-Installer/AGENTS.md) |
 | E2E 测试 | `tests/e2e` | [AGENTS.md](tests/e2e/AGENTS.md) |
 
-## 最常用命令
+## 常用命令
+
+这些是命令参考，不是 PR 前置检查清单。预检请按下方“验证”表选择最小本地检查；
+大范围测试和构建主要用于复现 CI 或验证构建相关改动。
 
 ```bash
 # 安装
@@ -54,30 +57,43 @@ 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          # 仅 i18n contract / resources
+pnpm run i18n:audit                  # 仅 i18n contract / resources
 pnpm run check:repo-hygiene
 pnpm run check:github-config
 cargo check --workspace
 
-# 测试
-pnpm --dir src/web-ui run test:run
-cargo test --workspace
+# 测试（本地优先用精确测试路径；大范围测试由 CI 兜底）
+pnpm --dir src/web-ui run test:run      # 大范围测试；本地优先用精确测试路径
+cargo test --workspace                  # 大范围测试；CI 兜底
 
-# 构建
-cargo build -p bitfun-desktop
-pnpm run build:web
-pnpm run build:mobile-web
+# 构建（仅构建相关改动或复现 CI 时运行）
+cargo build -p bitfun-desktop           # 构建相关改动 / 复现 CI
+pnpm run build:web                      # 构建相关改动 / 复现 CI
+pnpm run build:mobile-web               # 构建相关改动 / 复现 CI
 
-# 快速构建（开发 / CI 提速）
+# 快速构建（手动构建 / 调试流程）
 pnpm run desktop:build:fast           # debug 构建，不打包
 pnpm run desktop:build:release-fast   # release 但降低 LTO
 pnpm run desktop:build:nsis:fast      # Windows 安装器，release-fast profile
-pnpm run installer:build:fast         # 安装器应用，快速模式
 ```
 
 完整脚本列表见 [`package.json`](package.json)。
 
 ## 全局规则
 
+### 国际化
+
+- 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。
@@ -169,16 +185,24 @@ SessionManager → Session → DialogTurn → ModelRound
 
 ## 验证
 
+按触及文件选择最小本地预检。完整构建和大范围测试默认由 CI 保护；只有改动直接影响构建、
+打包，或 CI 无法覆盖对应路径时，才在本地运行更重的命令。
+
 | 改动类型 | 最低验证要求 |
 |---|---|
-| 前端 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`；行为变化还需要在 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` |
+| 不涉及 i18n 资源/契约的前端 UI、状态或适配层 | `pnpm run type-check:web`；行为变化时再加最近的 focused test |
+| 仅 locale 资源改动 | `pnpm run i18n:audit` |
+| Locale contract 或 shared terms | `pnpm run i18n:generate && pnpm run i18n:contract:test && pnpm run i18n:audit` |
+| Web UI i18n runtime、namespace loading 或直接 `i18nService.t(...)` 调用 | `pnpm run i18n:contract:test && pnpm run type-check:web && pnpm --dir src/web-ui run test:run src/infrastructure/i18n/core/I18nService.test.ts` |
+| Mobile web UI、状态、配对、断开或重连行为 | `pnpm --dir src/mobile-web run type-check`；行为变化还需要在 PR 中说明手动配对 / 重连验证 |
+| Deep Review / 代码审核团队行为 | 运行最近的 Web UI 检查，再运行 `cargo test -p bitfun-core deep_review -- --nocapture`；如果触及后端或 Tauri API，还需要运行对应 Rust / 桌面端检查 |
+| `core`、`transport`、`api-layer` 或共享服务中的 Rust 逻辑 | `cargo check --workspace`；行为变化时再加最近的 focused `cargo test` |
+| 桌面端集成、Tauri API、browser/computer-use 或桌面专属行为 | `cargo check -p bitfun-desktop`；行为变化时再加 focused desktop tests |
+| 被桌面端 smoke/functional 流覆盖的行为 | 优先运行最近的 focused E2E/smoke check；除非改动影响构建，否则 broad build/test 交给 CI |
+| `src/crates/ai-adapters` | 运行上面相关 Rust 检查；只有 stream contract 改动时再加 `cargo test -p bitfun-agent-stream` |
+| 不涉及打包的安装器前端或 i18n runtime | `pnpm --dir BitFun-Installer run type-check` |
+| 安装器 Tauri/Rust 改动 | `cargo check --manifest-path BitFun-Installer/src-tauri/Cargo.toml` |
+| 安装器打包、payload、安装/卸载流程或 native bundling | `pnpm run installer:build` |
 
 ## 先看哪里
 

AGENTS.md

@@ -37,7 +37,11 @@ Repository rule: **keep product logic platform-agnostic, then expose it through
 | Installer | `BitFun-Installer` | [AGENTS.md](BitFun-Installer/AGENTS.md) |
 | E2E tests | `tests/e2e` | [AGENTS.md](tests/e2e/AGENTS.md) |
 
-## Most-used commands
+## Common commands
+
+These are command references, not a pre-PR checklist. Use the Verification table
+to choose the smallest local precheck; broad suites and builds are mainly for CI
+reproduction or build-impacting changes.
 
 ```bash
 # Install
@@ -54,24 +58,25 @@ 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          # i18n contract / resources only
+pnpm run i18n:audit                  # i18n contract / resources only
 pnpm run check:repo-hygiene
 pnpm run check:github-config
 cargo check --workspace
 
-# Test
-pnpm --dir src/web-ui run test:run
-cargo test --workspace
+# Test (prefer focused paths locally; broad suites are CI-backed)
+pnpm --dir src/web-ui run test:run      # broad suite; prefer focused paths locally
+cargo test --workspace                  # broad suite; CI-backed
 
-# Build
-cargo build -p bitfun-desktop
-pnpm run build:web
-pnpm run build:mobile-web
+# Build (only for build-impacting changes or CI reproduction)
+cargo build -p bitfun-desktop           # build-impacting changes / CI reproduction
+pnpm run build:web                      # build-impacting changes / CI reproduction
+pnpm run build:mobile-web               # build-impacting changes / CI reproduction
 
-# Fast builds (for development / CI speed)
+# Fast builds (manual build/debug flows)
 pnpm run desktop:build:fast           # debug build, no bundling
 pnpm run desktop:build:release-fast   # release with reduced LTO
 pnpm run desktop:build:nsis:fast      # Windows installer, release-fast profile
-pnpm run installer:build:fast         # installer app, fast mode
 ```
 
 For the full script list, see [`package.json`](package.json).
@@ -88,6 +93,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
 
@@ -184,16 +192,24 @@ Session data is stored under `.bitfun/sessions/{session_id}/`.
 
 ## Verification
 
+Run the smallest local precheck that matches the touched files. CI is expected to
+cover full builds and broad test suites; run heavier local commands only when the
+change directly affects build, packaging, or CI cannot protect the path.
+
 | 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` |
-| 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` |
-| Desktop integration, Tauri APIs, browser/computer-use, or desktop-only behavior | `cargo check -p bitfun-desktop && cargo test -p bitfun-desktop` |
-| Behavior covered by desktop smoke/functional flows | `cargo build -p bitfun-desktop` then the nearest E2E spec or `pnpm run e2e:test:l0` |
-| `src/crates/ai-adapters` | Relevant Rust checks above **and** `cargo test -p bitfun-agent-stream` for stream contracts |
-| Installer frontend, i18n, or 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` |
+| Frontend UI, state, or adapters without i18n resource/contract changes | `pnpm run type-check:web`, plus the nearest focused test when behavior changed |
+| Locale resource-only changes | `pnpm run i18n:audit` |
+| Locale contract or shared terms | `pnpm run i18n:generate && pnpm run i18n:contract:test && pnpm run i18n:audit` |
+| Web UI i18n runtime, namespace loading, or direct `i18nService.t(...)` usage | `pnpm run i18n:contract:test && pnpm run type-check:web && pnpm --dir src/web-ui run test:run src/infrastructure/i18n/core/I18nService.test.ts` |
+| Mobile web UI, state, pairing, disconnect, or reconnect behavior | `pnpm --dir src/mobile-web run type-check`; include manual pairing / reconnect notes when behavior changes |
+| Deep Review / Code Review Team behavior | Nearest Web UI check above, plus `cargo test -p bitfun-core deep_review -- --nocapture`; also run Rust / desktop checks when backend or Tauri APIs are touched |
+| Shared Rust logic in `core`, `transport`, `api-layer`, or services | `cargo check --workspace`, plus the nearest focused `cargo test` when behavior changed |
+| Desktop integration, Tauri APIs, browser/computer-use, or desktop-only behavior | `cargo check -p bitfun-desktop`, plus focused desktop tests when behavior changed |
+| Behavior covered by desktop smoke/functional flows | Prefer the nearest focused E2E/smoke check; rely on CI for broad build/test coverage unless build behavior changed |
+| `src/crates/ai-adapters` | Relevant Rust checks above; add `cargo test -p bitfun-agent-stream` only when stream contracts changed |
+| Installer frontend or i18n runtime without packaging changes | `pnpm --dir BitFun-Installer run type-check` |
+| Installer Tauri/Rust changes | `cargo check --manifest-path BitFun-Installer/src-tauri/Cargo.toml` |
 | Installer packaging, payload, install/uninstall flow, or native bundling | `pnpm run installer:build` |
 
 ## Where to look first

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` 生成
 
 安装流程：
 
@@ -26,16 +28,29 @@ Language Select → Options → Progress → Model Setup → Theme Setup
 
 ## 命令
 
+这些是命令参考，不是默认预检清单。PR 范围请以下方 Verification 为准。
+
 ```bash
 pnpm --dir BitFun-Installer run installer:dev
 pnpm --dir BitFun-Installer run tauri:dev
 pnpm --dir BitFun-Installer run type-check
-pnpm --dir BitFun-Installer run build
-pnpm --dir BitFun-Installer run installer:build
+pnpm --dir BitFun-Installer run build            # React build / 复现 CI
+pnpm --dir BitFun-Installer run installer:build  # 仅打包场景
 ```
 
 ## 验证
 
+按触及范围选择最小检查：
+
+```bash
+pnpm run i18n:audit                                                   # 仅资源类 i18n
+pnpm run i18n:generate && pnpm run i18n:contract:test && pnpm run i18n:audit
+pnpm --dir BitFun-Installer run type-check                            # 前端 i18n/runtime
+cargo check --manifest-path BitFun-Installer/src-tauri/Cargo.toml      # Tauri/Rust 改动
+```
+
+只有修改打包、payload、native bundling、安装/卸载流程、注册表、快捷方式或解压逻辑时，才运行完整安装器构建：
+
 ```bash
 pnpm --dir BitFun-Installer run type-check && pnpm --dir BitFun-Installer run installer:build
 ```

BitFun-Installer/AGENTS.md

@@ -28,23 +28,26 @@ Language Select → Options → Progress → Model Setup → Theme Setup
 
 ## Commands
 
+These are command references, not the default precheck list. Use Verification
+below for PR scope.
+
 ```bash
 pnpm --dir BitFun-Installer run installer:dev
 pnpm --dir BitFun-Installer run tauri:dev
 pnpm --dir BitFun-Installer run type-check
-pnpm --dir BitFun-Installer run build
-pnpm --dir BitFun-Installer run installer:build
+pnpm --dir BitFun-Installer run build            # React build / CI reproduction
+pnpm --dir BitFun-Installer run installer:build  # packaging only
 ```
 
 ## Verification
 
-For frontend, i18n, language-contract, or non-packaging installer changes, prefer
-the lighter focused checks:
+Use the smallest matching check:
 
 ```bash
-pnpm --dir BitFun-Installer run type-check
-cargo check --manifest-path BitFun-Installer/src-tauri/Cargo.toml
-pnpm --dir BitFun-Installer run build
+pnpm run i18n:audit                                                   # resource-only i18n
+pnpm run i18n:generate && pnpm run i18n:contract:test && pnpm run i18n:audit
+pnpm --dir BitFun-Installer run type-check                            # frontend i18n/runtime
+cargo check --manifest-path BitFun-Installer/src-tauri/Cargo.toml      # Tauri/Rust changes
 ```
 
 Run the full installer build only for packaging, payload, native bundling,

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`:
@@ -170,16 +179,23 @@ Keep PRs small and focused. Avoid bundling unrelated changes.
 
 Run relevant tests for your change. You do not need to run every row below; choose the smallest set that matches the files and behavior you touched:
 
+CI covers full builds and broad test suites. Local prechecks should stay focused
+unless the change directly touches build, packaging, or a path not covered by CI.
+
 For `/usage` UI copy changes, keep `en-US`, `zh-CN`, and `zh-TW` locale strings in sync.
 
 | 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` |
-| 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` |
-| Desktop integration, Tauri APIs, or desktop-only behavior | `cargo check -p bitfun-desktop && cargo test -p bitfun-desktop` |
-| E2E-covered behavior | Build the nearest app target, then run the closest E2E spec or `pnpm run e2e:test:l0` |
+| Locale resource-only changes | `pnpm run i18n:audit` |
+| Locale contract or shared terms | `pnpm run i18n:generate && pnpm run i18n:contract:test && pnpm run i18n:audit` |
+| Web UI state, adapters, or runtime code | `pnpm run type-check:web`, plus the nearest focused test when behavior changed |
+| Web UI i18n runtime or namespace-loading changes | `pnpm run i18n:contract:test && pnpm run type-check:web && pnpm --dir src/web-ui run test:run src/infrastructure/i18n/core/I18nService.test.ts` |
+| Mobile web UI, pairing, reconnect, disconnect, or chat-flow changes | `pnpm --dir src/mobile-web run type-check` |
+| Installer frontend or i18n runtime without packaging changes | `pnpm --dir BitFun-Installer run type-check` |
+| Rust core, transport, API layer, services, or shared runtime logic | `cargo check --workspace`, plus the nearest focused `cargo test` when behavior changed |
+| Desktop integration, Tauri APIs, or desktop-only behavior | `cargo check -p bitfun-desktop`, plus focused desktop tests when behavior changed |
+| E2E-covered behavior | Run the closest focused E2E/smoke check; rely on CI for broad build/test coverage unless build behavior changed |
 
 For mobile-web pairing, reconnect, disconnect, or chat-flow changes, include manual verification steps and screenshots or a short recording when the UI changes.