refactor: harden i18n audit coverage

.github/workflows/ci.yml

@@ -123,6 +123,12 @@ jobs:
       - name: Validate GitHub config
         run: pnpm run check:github-config
 
+      - name: Validate i18n contract
+        run: pnpm run i18n:contract:test
+
+      - name: Audit i18n resources
+        run: pnpm run i18n:audit
+
       - name: Lint web UI
         run: pnpm run lint:web
 

AGENTS-CN.md

@@ -93,6 +93,8 @@ pnpm run desktop:build:nsis:fast      # Windows 安装器，release-fast profile
 - 不要把 Web UI locale 资源导入 `src/mobile-web`、`BitFun-Installer` 等较小形态。
 - Web UI 只急切加载 bootstrap namespace；路由或功能文案使用
   `useI18n(namespace)`，直接 `i18nService.t(...)` 只用于 bootstrap namespace。
+- `pnpm run i18n:audit` 会检查 key / 占位符一致性、直接静态 key 是否存在，以及
+  source 中不再新增硬编码 CJK 文案。
 
 ### 日志
 

AGENTS.md

@@ -96,6 +96,8 @@ For the full script list, see [`package.json`](package.json).
 - Web UI loads only bootstrap namespaces eagerly; use `useI18n(namespace)` for
   route or feature copy and keep direct `i18nService.t(...)` calls in bootstrap
   namespaces.
+- `pnpm run i18n:audit` enforces key/placeholder parity, direct static key
+  existence, and the no-hardcoded-CJK source budget.
 
 ### Logging
 

CONTRIBUTING.md

@@ -86,6 +86,8 @@ Captured data is logged as structured JSON under the `bitfun::devtools` target.
   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.
+- `pnpm run i18n:audit` enforces key/placeholder parity, direct static key
+  existence, and the no-hardcoded-CJK source budget.
 
 ### Platform-agnostic core
 

CONTRIBUTING_CN.md

@@ -84,6 +84,8 @@ pnpm run e2e:test
   `pnpm run i18n:generate`。
 - 跨形态稳定标签放在 `src/shared/i18n/resources/shared`；流程文案留在所属形态资源中。
 - Web UI 路由或功能文案使用 `useI18n(namespace)`。不要把 Web UI locale 资源导入 mobile-web、installer、backend 或静态页面。
+- `pnpm run i18n:audit` 会检查 key / 占位符一致性、直接静态 key 是否存在，以及
+  source 中不再新增硬编码 CJK 文案。
 
 ### 平台无关核心
 

docs/architecture/i18n.md

@@ -78,11 +78,18 @@ to their current locale data.
   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.
+  Keep its static copy in its own resource file, such as
+  `src/apps/relay-server/static/homepage/i18n.json`, with English HTML fallback
+  text for first paint and fetch-failure resilience.
 
 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.
 
+Large or rarely used Web UI copy should live in a feature namespace outside
+`WEB_UI_BOOTSTRAP_NAMESPACES`; components load it with `useI18n(namespace)` or
+`useTranslation(namespace)` at the point of use.
+
 ## Backend And Frontend Language Contract
 
 All surfaces must exchange canonical app locale ids:

docs/development/i18n.md

@@ -104,9 +104,11 @@ 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.
+installer locale resources. It also fails on placeholder mismatches, unknown
+static Web UI `i18nService.t('namespace:key')` literals, direct `t(key,
+"literal fallback")` arguments, and CJK source candidates outside approved
+resource owners. Keep user-facing copy in locale/resource files rather than
+raising the hardcoded-copy baseline.
 
 ## Loading Size
 
@@ -118,6 +120,10 @@ 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 large feature copy, create a dedicated lazy Web UI namespace instead of
+putting it in a bootstrap namespace. Static self-contained pages should keep
+their own small resource files and retain English fallback HTML.
+
 For bundle-sensitive changes, compare generated asset sizes before and after the
 change and include the result in the PR.