Skip to content

feat: refine i18n loading guardrails#950

Merged
limityan merged 1 commit into
GCWing:mainfrom
limityan:yanzhn/i18n-loading-pr2
May 29, 2026
Merged

feat: refine i18n loading guardrails#950
limityan merged 1 commit into
GCWing:mainfrom
limityan:yanzhn/i18n-loading-pr2

Conversation

@limityan
Copy link
Copy Markdown
Collaborator

@limityan limityan commented May 29, 2026

Summary

  • Split Web UI i18n loading into a small eager bootstrap set plus lazy namespace loading for all other Web UI locale JSON files.
  • Added guardrails for Web UI bootstrap coverage, mobile-web/installer key parity, hardcoded CJK copy budgets, and the self-contained relay static homepage surface.
  • Updated the i18n architecture/development docs plus concise AGENTS/CONTRIBUTING guidance; no process or execution-plan docs are included.
  • Scoped AGENTS/CONTRIBUTING verification guidance to the smallest local prechecks, relying on CI for broad builds/full suites unless build or packaging behavior is touched.
  • Fixed the existing mobile-web parity gap by adding en-US.sessions.launch.

Behavior and Contract Changes

  • Web UI now eagerly bundles only WEB_UI_BOOTSTRAP_NAMESPACES; route and feature namespaces should be requested through useI18n(namespace) or i18nService.loadNamespace(namespace).
  • Direct synchronous i18nService.t('namespace:key') and i18nService.getT() namespace usage must stay within bootstrap namespaces; pnpm run i18n:contract:test enforces this.
  • pnpm run i18n:audit now treats Web UI, mobile-web, and installer key mismatches as errors, and fails if hardcoded CJK source candidate budgets increase.
  • The relay static homepage is explicitly tracked as a self-contained static i18n surface; it is audited for hardcoded-copy budget growth but does not import runtime locale catalogs.
  • Verification docs now distinguish resource-only locale changes, contract/shared-term changes, i18n runtime changes, mobile/installer frontend changes, Rust/desktop changes, and packaging changes.

Risk Notes

  • Main runtime risk is missing namespace requests after Web UI lazy loading. This is mitigated by preserving bootstrap coverage for synchronous call sites and adding runtime tests for bootstrap and lazy namespace loading.
  • Existing CJK hardcoded-copy warnings remain as grandfathered debt. New CJK source lines should be extracted instead of raising the baseline.
  • Existing Vite chunk-size/dynamic-import warnings still appear in Web UI and mobile-web builds; this PR does not attempt unrelated bundle splitting.
  • The docs intentionally reduce local prechecks for many changes; this shifts broad build/style regressions to CI, while keeping focused local checks for the touched runtime or resource layer.

Adversarial Review

  • Rechecked startup translation availability after introducing the i18next backend; added initImmediate: false and a synchronous bootstrap translation test.
  • Rechecked bootstrap ordering/coverage; added a contract test that scans synchronous i18nService.t(...) and getT() namespace usage against WEB_UI_BOOTSTRAP_NAMESPACES.
  • Rechecked cross-surface key parity; audit exposed sessions.launch missing from mobile-web en-US, which is fixed in this PR.
  • Rechecked generated/build side effects; Tauri schema and installer sync outputs were not committed.
  • Rechecked verification guidance after follow-up feedback; removed web/mobile/installer builds from default local precheck rows and marked remaining broad build/test commands as references for CI reproduction or build-impacting changes only.

Verification

Runtime and cross-surface validation run earlier in this PR:

  • pnpm run i18n:contract:test
  • pnpm run i18n:audit (passes with 3 grandfathered CJK budget warnings)
  • pnpm run lint:web
  • pnpm run type-check:web
  • pnpm --dir src/web-ui run test:run (146 files, 772 tests)
  • pnpm run build:web
  • pnpm --dir src/mobile-web run type-check
  • pnpm run build:mobile-web
  • pnpm --dir BitFun-Installer run type-check
  • pnpm --dir BitFun-Installer run build
  • cargo check --manifest-path BitFun-Installer/src-tauri/Cargo.toml
  • cargo test -p bitfun-core i18n -- --nocapture (8 passed)

Latest docs-only follow-up validation:

  • pnpm run check:repo-hygiene
  • git diff --check
  • git diff --cached --check
  • Legacy heavy-precheck grep returned no matches for the old combined local verification commands.

@limityan limityan force-pushed the yanzhn/i18n-loading-pr2 branch from ca6dca3 to 23a73fb Compare May 29, 2026 10:45
@limityan limityan force-pushed the yanzhn/i18n-loading-pr2 branch from 23a73fb to da05a50 Compare May 29, 2026 10:52
@limityan limityan merged commit 94ff17e into GCWing:main May 29, 2026
4 checks passed
@limityan
Copy link
Copy Markdown
Collaborator Author

Related tracking issue: #959. This link is for i18n/l10n module context only and should not close the issue when this PR is merged or closed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant