feat: enhance locale handling with AsyncLocalStorage support for server-side requests

.changeset/pretty-parents-draw.md

@@ -0,0 +1,6 @@
+---
+'@qwik.dev/router': patch
+'@qwik.dev/core': patch
+---
+
+enhance locale handling with AsyncLocalStorage support for server-side requests

packages/qwik-router/src/middleware/request-handler/user-response.ts

@@ -13,6 +13,7 @@ import {
 } from './request-event';
 import { encoder } from './resolve-request-handlers';
 import type { QwikSerializer, ServerRequestEvent, StatusCodes } from './types';
+import { withLocale } from '@qwik.dev/core';
 // Import separately to avoid duplicate imports in the vite dev server
 import {
   AbortMessage,
@@ -63,9 +64,12 @@ export function runQwikRouter<T>(
   return {
     response: responsePromise,
     requestEv,
-    completion: asyncStore
-      ? asyncStore.run(requestEv, runNext, requestEv, rebuildRouteInfo, resolve!)
-      : runNext(requestEv, rebuildRouteInfo, resolve!),
+    completion: withLocale(
+      requestEv.locale(),
+      asyncStore
+        ? () => asyncStore!.run(requestEv, runNext, requestEv, rebuildRouteInfo, resolve!)
+        : () => runNext(requestEv, rebuildRouteInfo, resolve!)
+    ),
   };
 }
 

packages/qwik-router/src/runtime/src/head.ts

@@ -37,9 +37,10 @@ export const resolveHead = (
     }
     return data;
   }) as any as ResolveSyncValue;
+  const storeEv = (globalThis as any).qcAsyncRequestStore;
   const headProps: DocumentHeadProps = {
     head,
-    withLocale: (fn) => withLocale(locale, fn),
+    withLocale: storeEv ? (fn) => fn() : (fn) => withLocale(locale, fn),
     resolveValue: getData,
     ...routeLocation,
   };
@@ -50,7 +51,9 @@ export const resolveHead = (
       if (typeof contentModuleHead === 'function') {
         resolveDocumentHead(
           head,
-          withLocale(locale, () => contentModuleHead(headProps))
+          storeEv
+            ? contentModuleHead(headProps)
+            : withLocale(locale, () => contentModuleHead(headProps))
         );
       } else if (typeof contentModuleHead === 'object') {
         resolveDocumentHead(head, contentModuleHead);

packages/qwik/src/core/use/use-locale.ts

@@ -1,7 +1,25 @@
 import { tryGetInvokeContext } from './use-core';
+import { isServer } from '@qwik.dev/core/build';
 
 let _locale: string | undefined = undefined;
 
+type LocaleStore = { locale: string | undefined };
+
+type LocaleAsyncStore = import('node:async_hooks').AsyncLocalStorage<LocaleStore>;
+
+let localAsyncStore: LocaleAsyncStore | undefined;
+
+if (isServer) {
+  import('node:async_hooks')
+    .then((module) => {
+      const AsyncLocalStorage = module.AsyncLocalStorage as unknown as new () => LocaleAsyncStore;
+      localAsyncStore = new AsyncLocalStorage();
+    })
+    .catch(() => {
+      // ignore if AsyncLocalStorage is not available
+    });
+}
+
 /**
  * Retrieve the current locale.
  *
@@ -11,6 +29,16 @@ let _locale: string | undefined = undefined;
  * @public
  */
 export function getLocale(defaultLocale?: string): string {
+  // Prefer per-request locale from local AsyncLocalStorage if available (server-side)
+  try {
+    const locale = localAsyncStore?.getStore?.()?.locale;
+    if (locale) {
+      return locale;
+    }
+  } catch {
+    // ignore and fallback
+  }
+
   if (_locale === undefined) {
     const ctx = tryGetInvokeContext();
     if (ctx && ctx.$locale$) {
@@ -30,6 +58,15 @@ export function getLocale(defaultLocale?: string): string {
  * @public
  */
 export function withLocale<T>(locale: string, fn: () => T): T {
+  // If running on the server with AsyncLocalStorage, set locale for this async context
+  try {
+    if (localAsyncStore?.run) {
+      return localAsyncStore.run({ locale }, fn);
+    }
+  } catch {
+    // ignore and fallback
+  }
+
   const previousLang = _locale;
   try {
     _locale = locale;
@@ -48,5 +85,15 @@ export function withLocale<T>(locale: string, fn: () => T): T {
  * @public
  */
 export function setLocale(locale: string): void {
+  // On the server, prefer setting the locale on the local per-request store
+  try {
+    const store = localAsyncStore?.getStore?.();
+    if (store) {
+      store.locale = locale;
+      return;
+    }
+  } catch {
+    // ignore and fallback
+  }
   _locale = locale;
 }