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/global.d.ts

@@ -6,7 +6,6 @@ type RequestEventInternal =
 type AsyncStore = import('node:async_hooks').AsyncLocalStorage<RequestEventInternal>;
 type SerializationStrategy = import('@qwik.dev/core/internal').SerializationStrategy;
 
-declare var qcAsyncRequestStore: AsyncStore | undefined;
 declare var _qwikActionsMap: Map<string, ActionInternal> | undefined;
 
 /** @deprecated Will be removed in v3 */

packages/qwik-router/src/middleware/request-handler/async-request-store.ts

@@ -0,0 +1,11 @@
+import type { RequestEventInternal } from './request-event';
+import type { AsyncLocalStorage } from 'node:async_hooks';
+
+export type AsyncStore = AsyncLocalStorage<RequestEventInternal>;
+
+// Qwik Core will also be using the async store if this is present
+export let asyncRequestStore: AsyncStore | undefined;
+
+export const setAsyncRequestStore = (store: AsyncStore | undefined) => {
+  asyncRequestStore = store;
+};

packages/qwik-router/src/middleware/request-handler/request-event.ts

@@ -20,6 +20,7 @@ import {
   RewriteMessage,
 } from '@qwik.dev/router/middleware/request-handler';
 import { encoder, getRouteLoaderPromise } from './resolve-request-handlers';
+import { asyncRequestStore } from './async-request-store';
 import type {
   CacheControl,
   CacheControlTarget,
@@ -83,7 +84,7 @@ export function createRequestEvent(
 
     while (routeModuleIndex < requestHandlers.length) {
       const moduleRequestHandler = requestHandlers[routeModuleIndex];
-      const asyncStore = globalThis.qcAsyncRequestStore;
+      const asyncStore = asyncRequestStore;
       const result = asyncStore?.run
         ? asyncStore.run(requestEv, moduleRequestHandler, requestEv)
         : moduleRequestHandler(requestEv);

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

@@ -13,6 +13,9 @@ import {
 } from './request-event';
 import { encoder } from './resolve-request-handlers';
 import type { QwikSerializer, ServerRequestEvent, StatusCodes } from './types';
+import { withLocale } from '@qwik.dev/core';
+import { setAsyncRequestStore } from './async-request-store';
+import type { AsyncStore } from './async-request-store';
 // Import separately to avoid duplicate imports in the vite dev server
 import {
   AbortMessage,
@@ -32,7 +35,7 @@ import('node:async_hooks')
   .then((module) => {
     const AsyncLocalStorage = module.AsyncLocalStorage;
     asyncStore = new AsyncLocalStorage<RequestEventInternal>();
-    globalThis.qcAsyncRequestStore = asyncStore;
+    setAsyncRequestStore(asyncStore);
   })
   .catch((err) => {
     console.warn(
@@ -63,9 +66,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

@@ -13,6 +13,7 @@ import type {
   ActionInternal,
 } from './types';
 import { isPromise } from './utils';
+import { asyncRequestStore } from '../../middleware/request-handler/async-request-store';
 
 export const resolveHead = (
   endpoint: EndpointResponse | ClientPageData,
@@ -37,9 +38,11 @@ export const resolveHead = (
     }
     return data;
   }) as any as ResolveSyncValue;
+  // Qwik Core will also be using the async store if this is present
+  const hasAsyncStore = asyncRequestStore;
   const headProps: DocumentHeadProps = {
     head,
-    withLocale: (fn) => withLocale(locale, fn),
+    withLocale: hasAsyncStore ? (fn) => fn() : (fn) => withLocale(locale, fn),
     resolveValue: getData,
     ...routeLocation,
   };
@@ -50,7 +53,9 @@ export const resolveHead = (
       if (typeof contentModuleHead === 'function') {
         resolveDocumentHead(
           head,
-          withLocale(locale, () => contentModuleHead(headProps))
+          hasAsyncStore
+            ? contentModuleHead(headProps)
+            : withLocale(locale, () => contentModuleHead(headProps))
         );
       } else if (typeof contentModuleHead === 'object') {
         resolveDocumentHead(head, contentModuleHead);

packages/qwik-router/src/runtime/src/server-functions.ts

@@ -65,6 +65,7 @@ import { useAction, useLocation, useQwikRouterEnv } from './use-functions';
 
 import type { FormSubmitCompletedDetail } from './form-component';
 import { deepFreeze } from './utils';
+import { asyncRequestStore } from '../../middleware/request-handler/async-request-store';
 
 /** @internal */
 export const routeActionQrl = ((
@@ -420,7 +421,7 @@ export const serverQrl = <T extends ServerFunction>(
 
       if (isServer) {
         // Running during SSR, we can call the function directly
-        let requestEvent = globalThis.qcAsyncRequestStore?.getStore() as RequestEvent | undefined;
+        let requestEvent = asyncRequestStore?.getStore() as RequestEvent | undefined;
 
         if (!requestEvent) {
           const contexts = [useQwikRouterEnv()?.ev, this, _getContextEvent()] as RequestEvent[];

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

@@ -1,7 +1,24 @@
 import { tryGetInvokeContext } from './use-core';
+import { isServer } from '@qwik.dev/core/build';
+import type { AsyncLocalStorage } from 'node:async_hooks';
 
 let _locale: string | undefined = undefined;
 
+let localAsyncStore: AsyncLocalStorage<{ locale?: string }> | undefined;
+
+if (isServer) {
+  import('node:async_hooks')
+    .then((module) => {
+      const AsyncLocalStorage = module.AsyncLocalStorage as unknown as new () => AsyncLocalStorage<{
+        locale?: string;
+      }>;
+      localAsyncStore = new AsyncLocalStorage();
+    })
+    .catch(() => {
+      // ignore if AsyncLocalStorage is not available
+    });
+}
+
 /**
  * Retrieve the current locale.
  *
@@ -11,6 +28,14 @@ let _locale: string | undefined = undefined;
  * @public
  */
 export function getLocale(defaultLocale?: string): string {
+  // Prefer per-request locale from local AsyncLocalStorage if available (server-side)
+  if (localAsyncStore) {
+    const locale = localAsyncStore.getStore()?.locale;
+    if (locale) {
+      return locale;
+    }
+  }
+
   if (_locale === undefined) {
     const ctx = tryGetInvokeContext();
     if (ctx && ctx.$locale$) {
@@ -30,6 +55,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) {
+      return localAsyncStore.run({ locale }, fn);
+    }
+  } catch {
+    // ignore and fallback
+  }
+
   const previousLang = _locale;
   try {
     _locale = locale;
@@ -48,5 +82,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 {
+    if (localAsyncStore && localAsyncStore.getStore) {
+      const store = localAsyncStore.getStore();
+      store!.locale = locale;
+      return;
+    }
+  } catch {
+    // ignore and fallback
+  }
   _locale = locale;
 }