How to async-load locale and inject it into <html lang>? #2166

YanAnghelp · 2026-06-25T14:20:52Z

YanAnghelp
Jun 25, 2026

Context

I need the lang attribute on <html> to reflect the authenticated user's locale preference (stored in Redis/DB), resolved per-request during SSR. This is extremely important to me.

What I've considered

1. Middleware

createMiddleware runs for every request — including API routes and potentially static assets depending on the deployment target. Running a Redis/DB lookup unconditionally on non-page requests is not acceptable.

Path-based filtering (skip /api/*, skip paths with file extensions) works but relies on conventions that feel fragile rather than architecturally guaranteed.

2. Cookie (current approach)

Reading a locale cookie synchronously in the document function works and has zero overhead. The limitation: cookies can be stale across devices. If the user changes their locale on Device A, Device B's cookie won't update until the next login or an explicit refresh.

For <html lang> this may be acceptable — but I'd like to understand if there's a better option.

3. `createAsync` inside the `document` function

The document prop in <StartServer> is a SolidJS component rendered during SSR, so it should be able to use createAsync / cache:

export default createHandler(() => (
  <StartServer
    document={({ assets, children, scripts }) => {
      const lang = createAsync(() => getUserLocale())
      return <html lang={lang() ?? 'en'}>...</html>
    }}
  />
))

Questions:

Does createAsync inside document suspend correctly and resolve before the HTML stream begins?
The element is the outermost node — is wrapping it in safe, or does it break streaming semantics?

What I'm looking for

Is there an officially supported pattern for resolving async server data in entry-server.tsx's document shell, with the guarantee that it only runs for HTML page renders (not API routes, not static assets)?

Or is the intended pattern to pre-populate event.locals from the route load function and read it synchronously in document?

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

How to async-load locale and inject it into <html lang>? #2166

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

Uh oh!

How to async-load locale and inject it into <html lang>? #2166

Uh oh!

Uh oh!

YanAnghelp Jun 25, 2026

Context

What I've considered

1. Middleware

2. Cookie (current approach)

3. createAsync inside the document function

Replies: 0 comments

YanAnghelp
Jun 25, 2026

3. `createAsync` inside the `document` function