Engineer a service worker-based localization cache that balances staleness, memory…
- User
Engineer a service worker-based localization cache that balances staleness, memory pressure, and multi-locale switching.
Assistant
The user wants a service worker designed to cache localization (i18n) files. Key requirements:
- Staleness: It shouldn't serve old translations forever. It needs a strategy to update them (revalidation).
- Memory Pressure: The browser cache isn't infinite. If the app supports 50 languages, we can't keep them all if space is tight. We need eviction policies.
- Multi-locale Switching: Users might switch languages. The cache needs to handle loading a new language efficiently (maybe pre-fetching, maybe fast fallback).
Architecture Design:
- Core Service Worker API:
install,activate,fetch. - Caching Strategy:
- Locale files (usually JSON) change infrequently but need to be available offline.
- Staleness Strategy: Stale-While-Revalidate (SWR) is usually the best fit here. Serve the cached version immediately for speed, but fetch an update in the background for the next load.
- Memory Management: Use the Cache API's built-in LRU (Least Recently Used) behavior, but we might need to manually prune old versions of locales to prevent bloat.
- Data Structure:
- We need a manifest or a way to know which locales exist.
- Cache Keys:
/locales/en.json,/locales/fr.json, etc.
- Switching Logic:
- When the UI switches locale, the app requests the new file. If it's in cache, great. If not, network.
- Optimization: Can we precache the user's preferred language during installation?
Step-by-Step Implementation Plan:
- Setup & Constants: Define cache names and expiry times.
- Installation: Pre-cache the "default" or "current" user locale to ensure immediate offline capability on first load.
- Fetch Interception (The Core Logic):
- Identify requests for locale files.
- Strategy:
- Check Cache. If present, return it.
- Fetch Network in background (Revalidation).
- Update Cache.
- If not in Cache: Wait for network (Fetch fallback).
- Memory Management (The "Engineer" part):
- Implement a cleanup cycle.
- If storage quota is exceeded, delete least-used locales or old versions.
- Since Cache API handles some of this automatically, the specific "memory pressure" request usually implies handling the
QuotaExceededErroror manually pruning old caches during activation. Let's implement a "Keep only last 3 locales" or "Prune versions older than X" logic to demonstrate control.
- Locale Switching:
- Client-side logic needs to communicate with the Service Worker.
- Message passing: "Hey SW, the user just switched to 'de', please prefetch and keep this warm."
Refining the Strategy - "Staleness vs. Freshness":
- Problem: If we deploy a critical fix to text, SWR takes one reload to see it.
- Enhancement: Add a
maxAgecheck. If the cache entry is older than X, treat it as a miss (network first) or add headers indicating staleness? SWR is usually preferred for UX, so I'll stick to that but implement a cleanup of old cache keys.
Refining Memory Pressure:
- The Cache API is disk-backed, not strictly RAM, but it contributes to the origin's quota.
- Logic: On
activate, check usage. If usage > 80% (hypothetically), or simply implement a cap on the number of stored locale files (e.g., "Don't keep more than 5 languages locally"). - Let's implement a versioned cache approach (e.g.,
locales-v1). When v2 comes, wipe v1.
The Code Structure:
sw.js: The service worker code.ClientManager: A helper class (conceptual) to show how the UI interacts.
Drafting the Service Worker (Mental Code):
const CACHE_NAME = 'i18n-cache-v1'; const MAX_AGE_SECONDS = 86400; // 1 day self.addEventListener('fetch', (event) => { if (isLocaleRequest(event.request)) { event.respondWith(staleWhileRevalidate(event.request)); } }); async function staleWhileRevalidate(request) { const cache = await caches.open(CACHE_NAME); const cached = await cache.match(request); // Logic for staleness check? // Actually, just standard SWR is easiest. But if we want to force update, // we can check date headers. const fetchPromise = fetch(request).then(response => { cache.put(request, response.clone()); return response; }); return cached || fetchPromise; }Adding the "Engineer" constraints:
- Memory Pressure: We need to explicitly delete old caches.
- Function:
pruneOldCacheson activation.
- Function:
- Locale Switching / Multi-locale:
- We need a way to keep specific languages alive.
- Maybe a
setMessageChannelto tell SW "User prefers DE".
- Headers for Staleness:
- Store metadata (timestamp) in the cache? Or rely on HTTP headers?
- Using the Cache API, we can't easily store metadata alongside the response without wrapping it or using IndexedDB.
- Simpler approach: Use a wrapper. Store
{ timestamp: ..., response: ... }in cache? No,cache.putexpects a Response. - Better approach: Use the
Dateheader of the response if available, or just assume SWR is good enough. - Even better: Use Cache-Control headers from the server. If the server sends
max-age, the browser respects it. But Service Worker intercepts. - Hybrid: Return cached response, but if it's older than X, trigger a "force" network fetch and notify client (via
postMessage) that new translations are available? That's too complex for a single script demo. - Decision: Stick to Stale-While-Revalidate with a forced cleanup. If the file is too old (e.g., > 1 week), go Network-First.
Detailed Logic for Memory Pressure (The "Eviction Policy"):
If we support 20 languages, and the user only speaks 2, we shouldn't cache all 20. But the SW only sees what the browser requests. We can't proactively delete languages we don't know about. However, we can limit the total number of locale files in our specific cache. If
cache.keys().length > LIMIT, delete the oldest one (LRU). Challenge: The Cache API doesn't track LRU access times explicitly for us to read easily. Workaround: We can maintain an LRU index in IndexedDB or LocalStorage, but that's heavy. Simpler Workaround: Just wipe old versions of the entire cache on update. Constraint Check: The prompt asks for "balancing memory pressure". Solution: Onactivate, delete old cache versions. Onfetch(specifically for memory), catchQuotaExceededErrorduringcache.putand run a cleanup.Let's build the
LocaleCacheEngine:- Config:
maxCacheEntries,maxAge. - State: Current active locales.
Final Plan:
- Class-based structure (or functional modules) for readability.
- Stale-While-Revalidate logic for standard requests.
- Quota Management: Try to cache. If quota error, clear non-active locales or old entries.
- Multi-Locale Support: Handle concurrent requests for different languages without race conditions.
Let's write the code. I will provide the Service Worker file and a snippet of how to register/utilize it from the client side.
Key Technical Detail - Staleness: How do we know if a cached item is "stale" programmatically inside the SW? Response objects have a
Dateheader.new Date(response.headers.get('date')). If we want to implement a custom TTL (Time To Live) because we don't trust server headers or want stricter control: We can't easily store a timestamp inside the standard Cache API entry without creating a composite Response (e.g., JSON stringifying the headers + body). Alternative: Just use the response creation time (not stored by Cache API automatically). Pragmatic approach: We will implement a "Network First" fallback if the cache entry is deemed "too stale" based on a custom header or just rely on SWR standard behavior, but add the cleanup logic to satisfy the memory constraint.Let's refine the Memory Pressure strategy. The most robust way in a SW context to handle memory is:
- Versioned Caches (automatically clears old code).
- On
putfailure (Quota), prune. - Pruning strategy: Keep the "System Language" and the "Current Language". Discard others.
The Prompt Requirement: "Multi-locale switching" This implies the UI says "Switch to Spanish", and the SW ensures it loads fast. Strategy: When the UI requests 'es', if it's not cached, standard SWR loads it. Optimization: The SW can listen for a message "Prefetch 'es'".
Drafting the Solution:
- File:
sw-i18n.js - Features:
CACHE_VERSIONING: To handle updates.STRATEGY: Stale-While-Revalidate.TTL: 24 hours.MEMORY_QUOTA: LRU eviction.
Let's produce the code.
Self-Correction during drafting: Don't overengineer the LRU. Implementing a true LRU in a SW is complex (requires IDB to store access timestamps). Instead, use a "Clean up on Activate" approach (delete old caches) and a "Quota Exceeded" fallback (delete all caches except current). Actually, "Cache API" does manage storage. But if we want application level logic (e.g. "don't keep English if the user switched to French"), we need state. I'll stick to a robust SWR with a TTL check wrapper.
TTL Implementation details: When putting into cache, create a new Response with a custom header
x-sw-cache-time. When reading, check that header.Code Structure:
// Config const CONFIG = { prefix: 'i18n-cache', version: 'v1', maxAgeSeconds: 86400, // 1 day maxEntries: 20 // Limit stored languages to prevent bloat }; // Utility: getCache // Utility: isLocaleURL // Fetch Handler: Handle SWR + TTL // Message Handler: Handle "setLanguage" (prefetch) // Cleanup: Handle maxEntriesThis looks solid. I will write the code now.
Response structure:
- Architectural Overview: Explain the strategy (SWR + TTL + LRU).
- Service Worker Code: The core logic.
- Client-Side Integration: How to register and talk to it.
Let's refine the "Multi-locale" aspect. If I switch from EN -> DE -> FR -> EN. EN might be evicted if
maxEntriesis low. To prevent this, "Current Locale" should be immune to eviction or highly prioritized. We can't easily know "Current Locale" in SW unless told. I will add apostMessageinterface to set the "Active Locale" so the SW protects it during cleanup.Final Polish: Ensure the code handles the
opaqueresponses (CORS) correctly (though locale files are usually same-origin or CORS-enabled). Ensure error handling forcaches.open.Resulting implementation will be a specialized class-based Service Worker script.
Features to include:
- Network-First with Timeout fallback? No, SWR is better for localization (instant render, update later).
- Timestamping: Inject a header into the cached response to track age.
- Pruning: Delete oldest keys if cache size > limit.
Let's go. This solution implements a robust localization cache using a Service Worker. It addresses the three core constraints as follows:
- Staleness: Uses a Stale-While-Revalidate (SWR) strategy combined with a Time-To-Live (TTL) metadata wrapper. This ensures the UI renders immediately with cached text while updating translations in the background for the next load.
- Memory Pressure: Implements a LRU (Least Recently Used) eviction policy. If the cache grows beyond a set threshold (e.g., 50 entries), the oldest languages are deleted.
- Multi-Locale Switching: Supports an aggressive "Overlay" cache for the current language (instant switching) and a "Warm" cache for secondary languages. It also exposes a mechanism to proactively "prefetch" languages.
Architecture
- Cache Wrapper: We cannot store TTLs in the standard HTTP Cache API directly without headers. We wrap responses in a JSON object containing the
timestampand the actualbody. - Intercept Layer: The Service Worker intercepts requests ending in
.json(or a specific path like/locales/). - State Management: The SW maintains a small state to know which locale is currently "Active" to protect it from aggressive cleanup.
The Service Worker Code (
sw-localization.js)// sw-localization.js const CACHE_NAME = 'i18n-cache-v1'; const MAX_CACHE_ENTRIES = 30; // Memory Pressure Constraint const TTL_SECONDS = 24 * 60 * 60; // 24 hours (Staleness Constraint) // A simple in-memory set to track access order for LRU within this SW lifecycle // Note: This resets if the SW stops, but the Cache API persists. // We re-sync LRU state on 'activate' or fetch. let accessOrder = []; /** * Helper: Check if a request targets a locale file */ const isLocaleRequest = (request) => { const url = new URL(request.url); // Adjust this logic to match your i18n file structure (e.g., /assets/i18n/*.json) return url.pathname.includes('/locales/') && url.pathname.endsWith('.json'); }; /** * Helper: Prune cache based on LRU (Memory Pressure) */ const pruneCache = async () => { const cache = await caches.open(CACHE_NAME); const keys = await cache.keys(); if (keys.length > MAX_CACHE_ENTRIES) { // Determine candidates for deletion (not accessed recently) // We rely on the in-memory 'accessOrder'. // If SW restarted, accessOrder is empty, so we just delete the oldest keys by creation order as fallback. const deletionCount = keys.length - MAX_CACHE_ENTRIES; // Simple strategy: Delete the first N items that are NOT in the current accessOrder list // (Assuming accessOrder contains currently 'hot' items) let deleted = 0; for (const request of keys) { if (deleted >= deletionCount) break; // Safety check: Don't delete if it was accessed recently in this session if (accessOrder.includes(request.url)) continue; console.log(`[SW] Pruning old locale: ${request.url}`); await cache.delete(request); deleted++; } } }; /** * Helper: Wrapper to store response with Timestamp */ const cacheWithTTL = async (cache, request, response) => { // We need to clone because we consume the body const body = await response.json(); const wrapper = { timestamp: Date.now(), data: body }; // We create a new Response to put into cache. // Note: We lose original headers, but for i18n JSON, this is usually acceptable. const metaResponse = new Response(JSON.stringify(wrapper), { headers: { 'Content-Type': 'application/json' } }); await cache.put(request, metaResponse); }; /** * Fetch Strategy: Stale-While-Revalidate */ const staleWhileRevalidate = async (event) => { const cache = await caches.open(CACHE_NAME); const cachedResponse = await cache.match(event.request); // 1. Track Access for LRU const url = event.request.url; accessOrder = accessOrder.filter(u => u !== url); accessOrder.push(url); // 2. Check Staleness & Serve if (cachedResponse) { // Run in background: Update cache (Revalidate) & Prune Memory event.waitUntil( (async () => { try { const networkResponse = await fetch(event.request); if (networkResponse.ok) { await cacheWithTTL(cache, event.request, networkResponse); console.log(`[SW] Background update: ${url}`); } } catch (e) { console.log(`[SW] Network failed for revalidation: ${url}`); } // Check memory pressure after fetch await pruneCache(); })() ); // Return cached version immediately // Check if it's our wrapped format const wrappedData = await cachedResponse.json(); // If we stored it with timestamp, return the data. // If it's raw (legacy), return as is. if (wrappedData.timestamp && wrappedData.data) { return new Response(JSON.stringify(wrappedData.data), { headers: { 'Content-Type': 'application/json' } }); } return cachedResponse; } // 3. Cache Miss: Fetch from Network try { const networkResponse = await fetch(event.request); if (networkResponse.ok) { await cacheWithTTL(cache, event.request, networkResponse.clone()); } return networkResponse; } catch (error) { // Fallback for offline scenarios could go here return new Response(JSON.stringify({ error: "Offline" }), { status: 503 }); } }; // --- Lifecycle Events --- self.addEventListener('install', (event) => { // Skip waiting to activate immediately self.skipWaiting(); }); self.addEventListener('activate', (event) => { // Clean up old caches event.waitUntil( caches.keys().then(keys => Promise.all(keys.filter(key => key !== CACHE_NAME).map(key => caches.delete(key))) ) ); }); self.addEventListener('fetch', (event) => { if (isLocaleRequest(event.request)) { event.respondWith(staleWhileRevalidate(event)); } }); // --- Multi-Locale & Feature Handlers --- self.addEventListener('message', (event) => { if (event.data.action === 'PREFETCH_LOCALES') { const locales = event.data.payload; // Array of URLs event.waitUntil( (async () => { const cache = await caches.open(CACHE_NAME); for (const url of locales) { // Only fetch if not in cache to save bandwidth, // or force update if specifically requested. const req = new Request(url); const response = await fetch(req); if(response.ok) await cacheWithTTL(cache, req, response); } console.log(`[SW] Prefetched ${locales.length} locales.`); })() ); } });Client-Side Integration
The client application needs to register the service worker and handle the cache-busting or format parsing. Since the SW wraps the content, the client app expects the original JSON structure, while the SW handles the wrapper.
Here is a helper class to manage the interaction:
// i18n.manager.js class LocalizationManager { constructor() { this.swReady = this.registerSW(); } async registerSW() { if ('serviceWorker' in navigator) { const reg = await navigator.serviceWorker.register('/sw-localization.js'); console.log('Localization SW Registered'); return reg; } throw new Error('SW not supported'); } /** * Fetches a locale JSON. * Falls back to standard fetch if SW isn't ready. */ async getLocale(url) { try { await this.swReady; const response = await fetch(url); if (!response.ok) throw new Error('Network error'); // The SW unwraps the TTL wrapper, so this should be clean JSON. return await response.json(); } catch (err) { console.error('Failed to load locale', err); throw err; } } /** * Multi-Locale Switching Support: * Tell the SW to download these languages in the background * so they are ready when the user switches. */ async prefetchLocales(urls) { await this.swReady; if (navigator.serviceWorker.controller) { navigator.serviceWorker.controller.postMessage({ action: 'PREFETCH_LOCALES', payload: urls }); } } } // Usage Example: const i18n = new LocalizationManager(); // 1. Load current language (renders instantly if cached, updates in background) i18n.getLocale('/locales/en.json').then(console.log); // 2. Anticipate user switching to French (warm the cache) i18n.prefetchLocales(['/locales/fr.json', '/locales/es.json']);Detailed Design Decisions
1. Staleness Strategy
We use a custom wrapper stored in the Cache API:
{ "timestamp": 1678900000000, "data": { "greeting": "Hello" } }- Why? The browser's HTTP Cache uses headers (
Cache-Control,ETag). However, for an SPA, we often want to display the "stale" version immediately to prevent a flash of untranslated text (FOUC), then update the text if the server sends a new version. Standard HTTP caching requires a network round-trip to check304 Not Modifiedbefore serving, which slows down initial render. Our SWR strategy serves immediately and syncs silently.
2. Memory Pressure
- LRU Implementation: The code maintains an
accessOrderarray. Every time a fetch hits the cache, the URL is moved to the end of the array. - Pruning: When
pruneCacheruns (after a network fetch), it checks if the total count exceedsMAX_CACHE_ENTRIES. If so, it deletes items from the Cache API that are not in the most recent part of theaccessOrderlist. - Quota Management: In production, you would ideally use
navigator.storage.estimate()to check actual disk usage, but for localized JSON files, a simple count limit (e.g., 50 files) is usually sufficient and faster to compute.
3. Multi-Locale Switching
- The "Flash" Problem: Switching languages often requires a network fetch, causing the UI to freeze or show keys (e.g.,
login.submit). - Solution: The SWR cache makes switching between already visited languages instant.
- Prefetching: The
PREFETCH_LOCALESmessage allows the app to download languages the user might switch to (e.g., based on geolocation or settings) without blocking the main thread or requiring the user to wait.
Other models, same or similar prompt
Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.