Pre-render with i18n: how to activate locale with dynamic message catalogs?

[MrNaif2018]

Hi! Thank you so much for vike, it's amazing!
I am trying to setup i18n with lingui and vike, and to achieve code splitting, we use this: https://lingui.dev/guides/dynamic-loading-catalogs
Which basically means importing the needed .po file, and activating messages from it
The recommended approach to do so is in a useEffect in root layout.
I copy pasted the onBeforeRoute and onPrerenderStart hooks from https://vike.dev/i18n and it works well
But the only issue is, I think during pre-render useEffect (or even useLayoutEffect isn't called), which makes my html either not render (because I have a useState variable which is set to initialized after locale is initialized) or even if to remove initialized variable, it just renders the fallback messages
I created a workaround, to load locale messages in onPrerenderStart like so:

const localeModule =
  await AVAILABLE_LOCALE_MODULES[`./_generated/locales/${localeId}.po`]()

const { messages: localeMessages } = localeModule as {
  messages: Record<string, string>
}

pageContexts.push({
  ...localizedPageContext,
  localeId,
  messages: localeMessages,
})

and inside my root layout, I had to use this:

const { localeId: pageLocaleId, messages } = usePageContext()

const isPrerenderedLocale = useMemo(
  () => typeof messages === "object",
  [messages],
)

const [isInitialized, setIsInitialized] = useState(isPrerenderedLocale)

if (isPrerenderedLocale) {
  activateLocaleMessages(pageLocaleId, messages)
}

useEffect(() => {
  activateLocale(pageLocaleId, onActivationSuccess)
}, [onActivationSuccess, pageLocaleId])

Technically this shouldn't be correct, because this is a conditional without useEffect, but I didn't get any warnings because I passed messages only during pre-render

But when I decided to localize head for SEO (e.g. og:description), I had to activate locale even earlier
So what I ended up doing is, make onBeforeRoute and onPrerenderStart exactly like from vike i18n docs, and add a new onBeforeRender hook:

export const onBeforeRender = async (pageContext: PageContextServer) => {
  const { localeId } = pageContext

  const localeModule =
    await AVAILABLE_LOCALE_MODULES[`./_generated/locales/${localeId}.po`]()

  const { messages: localeMessages } = localeModule as {
    messages: Record<string, string>
  }

  activateLocaleMessages(localeId, localeMessages)

  const metadata = getLayoutMetadata({
    ...
  })

  return {
    pageContext: {
      metadata,
      messages: localeMessages,
    },
  }
}

Which made it possible to localize head, but now that messages are passed not only in pre-render, in development mode I get this warning:

Cannot update a component (I18nProvider) while rendering a different component (Layout). To locate the bad setState() call inside Layout, follow the stack trace as described in https://react.dev/link/setstate-in-render
And it complains exactly about those 2 lines:

if (isPrerenderedLocale) {
    activateLocaleMessages(pageLocaleId, messages)
  }

Which are used to make localized pages properly load in pre-render, because useEffect doesn't get called in pre-render, and this warning recommends using useEffect

But in production, it doesn't log anything for some reason. So I wonder if it appears if passing messages only during prerender, or in all cases.

Sorry for the long write-up, I would like to find a proper way to make i18n work during pre-render basically and want to see if my workaround is viable or there is a better way (:
Thank you!

[brillout]

I ain't familiar with Lingui so I can't say much about its error message.

Is there something about Vike you think is missing that would help you resolve your issue?

[brillout]

If you activate it in +onBeforeRender then you activate it before starting the React rendering, so I wouldn't why streaming can make a difference. Could be something about i18n.loadAndActivate() that I don't know.

[MrNaif2018]

This happens if you run the demo reproducer I sent, where it activates locales in onBeforeRender only
If you activate it right in the component, then it gets fixed up to the correct locale

[MrNaif2018]

I got this resolved, mostly!
So the main issues were: prerendering was running multiple tasks in parallel, and i18n is a global object, which caused it to be rendering in an incorrect locale due to concurrency issues

prerender: {
    enable: true,
    parallel: false,
  },

It might be worth to mention this in docs, and the usage of onBeforeRender if you want to e.g. localize head

I got it working fully properly using the guide https://lingui.dev/tutorials/react-rsc, because not sure if we use react server components, but indeed guide for SSR was required

Also onBeforeRender executes on first load only on server, so what happens if you don't have all catalogs already loaded is:
On server, i18n object gets locales successfully loaded
On client, because i18n object is not serialised to client, it doesn't find any locales, so I get hydration error back to English
I currently use onBeforeRender.shared.ts, if I were to split onBeforeRender.server.ts and .client.ts, would it run on first client render as well? Or that's the recommended hook to call it in then?

[MrNaif2018]

Okay, so for anyone who needs this: because we are in SSR, we need to render localized messages somehow both on server and client
On server, we load locale chunks and just translate (this is what gets pre-rendered)
On client, because i18n object can't be serialized to client directly, we pass locale messages via pageContext, and activate them on client. During client-side navigation, onBeforeRender is called, fetches only the new language's chunk, and it is being applied.

The main thing: as i18n object is global, you must disable parallel pre-rendering!

prerender: {
    enable: true,
    parallel: false,
  },

The alternative solution to this is to get a new i18n instance each time, but this is overcomplicated and not worth it unless your project is very big. And disabling parallel mode actually made things faster for me (I have a page which uses vike-react-query which issues external api calls)

So, to set it up:
configure onBeforeRoute exactly like in vike i18n docs
configure onPrerenderStart exactly like in vike i18n docs
create a file +onBeforeRender.shared.ts (runs on both client and server)

and do:

import type { PageContext } from "vike/types"

import { loadCatalog } from "@/core/i18n"
import { activateLocaleMessages } from "@/core/i18n/effects"

export const onBeforeRender = async (pageContext: PageContext) => {
  const { localeId } = pageContext
  const messages = await loadCatalog(localeId)
  activateLocaleMessages(localeId, messages)

  // here you can e.g. translate head metadata

  return {
    pageContext: {
      messages,
    },
  }
}

In your root layout, do:

useAppLocale()

And the hook code is simple:

export const useAppLocale = () => {
  const { localeId, messages } = usePageContext()
  activateLocaleMessages(localeId, messages)
}

And that's it!

For reference, the activateLocaleMessages and loadCatalog functions:

export async function loadCatalog(locale: SupportedLocaleId) {
  const { messages } = (await AVAILABLE_LOCALE_MODULES[
    `./_generated/locales/${locale}.po`
  ]()) as {
    messages: Record<string, string>
  }

  return messages
}

export const activateLocaleMessages = (
  localeId: SupportedLocaleId,
  messages: Record<string, string>,
) => {
  if (i18n.locale !== localeId) {
    i18n.loadAndActivate({
      locale: localeId,
      messages,
    })
  }
}

P.S. @brillout let me know how could I add it somewhere to the docs, as a example repository with lingui or something else, I can contribute

[brillout]

Publishing an example of using Vike with Lingui would be nice indeed! I can take care of the docs part.

Once we have a Vike + Lingui example and vike.dev/Lingui (I'll create it), maybe we can mention how to use Lingui with Vike somewhere at lingui.dev? That would be great!

[MrNaif2018]

So I create a github repo with the ready example and send here, right?

[brillout]

Yes, perfect.

[brillout]

I can take care of the docs part.

Done:

• 2c645ac
• https://vike.dev/lingui
• 528c763
• https://vike.dev/i18n#split-locale-data

If more tools need +prerender.parallel: false then I'll add a note about it at vike.dev/i18n.

[Ercilan]

I tried using onBeforeRender() to dynamically load the locale messages, but I found that on the client it seems to only trigger after the first render (i.e. when I navigate to another page). On the very first load, it doesn’t run, so there’s no locale messages available. During hydration, the text gets replaced with the keys instead:

@brillout Is this the expected behavior of onBeforeRender()? I didn’t find this detail in the documentation, but when I checked the code in the F12 dev tools, it does seem to work this way.
By the way, i am using vue + vue-i18n

---

I went back and reread the thread, and I noticed that MrNaif2018 actually mentioned this situation there, but it’s not very clear in the Vike documentation.

we pass locale messages via pageContext, and activate them on client

Are you using passToClient to send the locale messages to the client? If so, that means the HTML will contain both the translation JSON and the rendered text? which feels a bit redundant. I tried this approach, but since my project only has two language files (zh-CN.json and en.json), it makes each HTML file more heavier. Also, if you do it that way, it seems like there’s no need to load the locale messages again through onBeforeRender() afterward?

ps: My project is an SPA, where I only lazy-loaded the specific locale file needed by the user. I’m now trying out Vike, and later I’d also like to minify html, so I’m being stricter about this.

If that’s the case, I’d rather avoid this approach. It would be ideal if onBeforeRender() could run on the client before every render.

[MrNaif2018]

I activate locales in onBeforeRender and it's needed for pre-render (especially in streaming components, otherwise you have to call this hook again)
and also it's because I localize head metadata (stored in pageContext)
so the generated pre-rendered htmls are almost nice
they contain the already translated texts in it, and a vike_pageContext thing with all messages only for current locale, and if you switch locale, it fetches only the needed locale chunk (which looks like t=JSON.parse(...)), then on client-side navigation vike's onBeforeRender runs, which makes it activate the new locale, translate metadata, and then it's called in the hook as well (no-op as locale is already activated)

[brillout]

@brillout Is this the expected behavior of onBeforeRender()? I didn’t find this detail in the documentation, but when I checked the code in the F12 dev tools, it does seem to work this way.

1fa6a63

@Ercilan Users usually want (and I presume you as well) to have the translated text be rendered to HTML. That's why I believe https://vike.dev/i18n#split-locale-data is the right standard recommendation.

@MrNaif2018 An example would be great btw! And the Vike team can then easily create a vike-lingui extension!

[Ercilan]

@brillout What confuses me is that onBeforeRender() doesn’t run the first time, and the documentation doesn’t make this clear.

Currently, I’m using the onCreateApp() hook from vike-vue to dynamically import language packs, which works for both client and server. It also matches how I used to handle things before switching to Vike.
This way, I can avoid increasing the HTML size by passing data through pageContext, and I can better leverage browser caching for language file responses. If the language data is passed through pageContext, each first new tab will redownload the language data embedded in the HTML.
And if it’s SSG, then the additional language data size will roughly be: number of supported languages × data size × number of HTML files.
That might be fine for small translation datasets or simple apps, but in my case—where the translation data is already fairly large and will likely continue to grow—it may have some impact.