perf(i18n): split en.json shell + lazy rest chunk (#3535)

[koala73]

Closes #3535.

Summary

• Splits the eagerly-imported src/locales/en.json (131KB raw / ~30-40KB gzipped) into a small shell subset that stays in the main JS chunk and a larger rest chunk that loads as a separate Vite chunk during initI18n().
• Source of truth stays at en.json — the two derived files are regenerated by scripts/build-i18n-shell.mjs (wired into every prebuild/build:variant script). A parity test in tests/i18n-shell-split.test.mts blocks drift if a contributor edits en.json without re-running the script.
• initI18n() boots i18next with the shell so chrome paints immediately, then awaits the rest before resolving so every t() call sees the full merged dictionary by the time any panel renders. No "raw t('key.path') flash" tradeoff to worry about.

Partition

Shell (eager, ~25KB raw / ~5KB gzipped):

• Top-level: app, auth, common, connectivity, contextMenu, header, panels, widgets, premium, preferences, alerts, commands
• Carve-out from components: panel (Panel.ts chrome), deckgl (region picker labels), map (header show/hide toggle)

Rest (lazy, ~84KB raw / ~30KB gzipped):

• Remaining components.* (per-panel content), plus popups, modals, signals, countryBrief, intel, mcp

Measured chunk sizes

VITE_VARIANT=full npm run build:

chunk	before	after
i18n-*.js (i18next core + en payload)	~183 KB raw	52 KB raw / 16.6 KB gzipped
locale-en-rest-*.js (new, lazy)	—	83 KB raw / 30 KB gzipped

The lazy chunk fetches in parallel with everything else after initI18n() triggers it; the main JS chunk drops by ~130KB raw, which is what #3535 was after.

Test plan

• npm run build:i18n-shell regenerates en.shell.json + en.rest.json from en.json deterministically.
• npx tsx --test tests/i18n-shell-split.test.mts — 7/7 pass (round-trip parity, partition disjointness, byte cap, leaf-key reachability).
• Full unit suite green: npx tsx --test tests/*.test.{mjs,mts} — 7836 tests pass.
• npx tsc --noEmit clean.
• VITE_VARIANT=full vite build succeeds and emits locale-en-rest-*.js as a distinct chunk that matches the existing SW /assets/locale-*.js/ CacheFirst rule.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
worldmonitor	Ready	Preview, Comment	May 3, 2026 4:03am

[greptile-apps]

Greptile Summary

Splits the 131 KB en.json into a ~25 KB eagerly-loaded shell (header, auth, panel chrome) and an ~84 KB lazy-loaded rest chunk, cutting the main JS bundle by ~130 KB raw. The partition script, Vite chunk rule, SW cache pattern, and parity test suite are all well-integrated.

• P1 – loadEnFull() shallow merge drops shell's components subkeys: { ...enShell, ...rest } is a shallow spread; rest.components overwrites enShell.components, silently removing the panel, deckgl, and map carve-outs from the cached promise. The current init path is rescued by i18next's addResourceBundle(..., deep=true) call, but the promise itself is semantically incorrect and unsafe for future use.
• P2 – build:desktop bypasses prebuild: it calls vite build directly, skipping build:i18n-shell; the script should chain npm run build:i18n-shell && explicitly like the other variant scripts do.

Confidence Score: 3/5

Hold for the shallow-merge fix in loadEnFull() — the current init path works by accident but the cached promise is semantically wrong.

One P1 bug (shallow merge in loadEnFull) that is mitigated at runtime by i18next's deep-merge behavior but leaves an incorrect cached promise that could silently break future callers or a re-init scenario. Score is below the P1 ceiling of 4 because the fix is a single line but the failure mode is subtle and not covered by the existing test suite.

src/services/i18n.ts lines 35-38 (loadEnFull merge logic); package.json build:desktop script.

Important Files Changed

Filename	Overview
src/services/i18n.ts	Boots i18next with the shell dict then lazy-loads the rest chunk; contains a P1 shallow-merge bug in loadEnFull() where rest.components overwrites enShell.components, dropping the panel/deckgl/map carve-outs from the cached promise.
scripts/build-i18n-shell.mjs	New build script that correctly partitions en.json into shell and rest subsets; partition logic is clean and exports are well-structured for test reuse.
package.json	Adds build:i18n-shell script and wires it into prebuild and all variant build scripts, but build:desktop still calls vite build directly and therefore skips the i18n-shell step.
vite.config.ts	Adds a manualChunks rule to emit locale-en-rest-*.js as its own chunk (matching the existing SW CacheFirst regex) and excludes en.shell.json from the lazy locale glob — correctly architected.
tests/i18n-shell-split.test.mts	Comprehensive parity, disjointness, byte-cap, and leaf-key tests; uses deepMerge to verify correctness but notably does not test loadEnFull() directly, leaving the shallow-merge bug undetected.

Sequence Diagram

sequenceDiagram
    participant App
    participant i18n as i18n.ts (initI18n)
    participant Shell as en.shell.json (eager, main chunk)
    participant Rest as en.rest.json (lazy chunk)
    participant i18next

    App->>i18n: initI18n()
    i18n->>Shell: static import (already in bundle)
    i18n->>i18next: init({ resources: { en: enShell } })
    Note over i18next: Chrome renders with shell keys
    i18n->>Rest: dynamic import('../locales/en.rest.json')
    Rest-->>i18n: rest dict
    i18n->>i18n: loadEnFull() → shallow { ...enShell, ...rest }<br/>⚠ drops components.panel/deckgl/map
    i18n->>i18next: addResourceBundle('en', fullEn, deep=true, overwrite=true)
    Note over i18next: deep=true rescues missing keys<br/>from prior shell registration
    i18n->>i18next: ensureLanguageLoaded(detectedLang)
    i18next-->>App: initI18n() resolves — full dict available

Loading

Comments Outside Diff (1)

1. package.json, line 14 (link)

   build:desktop bypasses prebuild and skips build:i18n-shell

   build:desktop calls vite build directly, not npm run build, so npm's prebuild lifecycle hook (which now includes build:i18n-shell) does not fire. A developer who edits en.json and then runs build:desktop will produce a desktop build with stale en.shell.json / en.rest.json — the parity test won't catch this at desktop-build time, only at npm test time.

_{Reviews (1): Last reviewed commit: "perf(i18n): split en.json into shell (ea..." | Re-trigger Greptile}

[greptile-apps]

Shallow spread drops components.panel/deckgl/map from loadEnFull()

{ ...enShell, ...rest } is a shallow merge. Because components is a top-level key in both en.shell.json (containing panel, deckgl, map) and en.rest.json (containing all other sub-panels), rest.components silently clobbers enShell.components, making loadEnFull() return a dict that is missing the three carved-out subkeys.

At initI18n() this is rescued by i18next's addResourceBundle(..., true, true) deep-merge path (the shell was already registered first), but the cached enFullPromise itself is incorrect. Any future caller that reads the resolved dict directly — or any re-init path that calls addResourceBundle with a fresh i18next instance — would lose components.panel.*, components.deckgl.*, and components.map.*.

Suggested change

	enFullPromise = import('../locales/en.rest.json').then((mod) => {
	const rest = (mod.default ?? mod) as TranslationDictionary;
	return { ...(enShell as TranslationDictionary), ...rest };
	});
	enFullPromise = import('../locales/en.rest.json').then((mod) => {
	const rest = (mod.default ?? mod) as TranslationDictionary;
	// Shallow spread is insufficient: `components` exists in both shell and
	// rest, so rest.components would clobber shell.components (panel/deckgl/map).
	// Merge the two components sub-objects explicitly.
	const shellDict = enShell as TranslationDictionary;
	const merged: TranslationDictionary = { ...shellDict, ...rest };
	if (shellDict.components && rest.components) {
	merged.components = {
	...(shellDict.components as Record<string, unknown>),
	...(rest.components as Record<string, unknown>),
	};
	}
	return merged;
	});

[koala73]

Fixed in f3d871d. Confirmed the bug is real — both files have a top-level components key (shell: panel/deckgl/map; rest: everything else), so shallow spread silently dropped the three shell carve-outs from the cached enFullPromise. Production was being rescued by i18next's deep-merge at init order (shell-then-rest), but the cached value itself was wrong — any fresh-i18next path or direct caller would lose the keys. Added explicit components-level merge + regression test in tests/i18n-shell-split.test.mts that asserts shallow spread WOULD drop the keys, so future "simplify" PRs fail loudly.

[koala73]

Fixed in 60f217e — thanks for catching this.

Root cause: chunk name locale-en-rest-*.js matched globIgnores: '**/locale-*.js', so VitePWA excluded it from the precache. But initI18n() awaits the rest chunk before any panel renders, so an offline-after-install boot would hang on the dynamic import. Pre-PR, those strings shipped inside the precached i18n-*.js chunk, so offline parity worked.

Fix: renamed the chunk to i18n-en-rest. That puts it inside the default **/*.js precache glob and outside the locale-only exclusion. The user-selected per-language chunks stay as locale-<lang> — those legitimately don't need precache and are runtime-cached by the existing /assets/locale-.*\.js/ CacheFirst rule.

Verified: dist/sw.js precache manifest now includes assets/i18n-en-rest-*.js (108 entries, up from 107). Per-language locale-* chunks remain runtime-only as before.

[koala73]

Both Greptile findings addressed:

• P1 — loadEnFull() shallow-merge bug → fixed in f3d871d. Explicit components-level merge + regression test in tests/i18n-shell-split.test.mts that asserts shallow spread WOULD drop components.panel/deckgl/map so future "simplify" PRs fail loudly.
• P2 — build:desktop bypasses prebuild → fixed in e381b48. Added npm run build:i18n-shell && to the front of build:desktop. Single chokepoint covers every Tauri target because src-tauri/tauri.conf.json:beforeBuildCommand invokes npm run build:desktop for all desktop entrypoints (desktop:build:full/tech/finance + tauri dev).