How to use next-18next with cache components enabled (Next.js 16.4)?

[rkrisztian]

I would love to see an example project where next-18next is used with cacheComponents: true set in next.config.ts, or at least some more explanation. I tried to understand the README using next-i18next@16.3.2, but it's still not clear to me:

• If I previously set localeInPath: false in i18n.config.ts, because I don't need the SEO, and therefore I don't want language codes in URLs, is really localeInPath: 'internal' my only valid option? (It seems yes.)
• I can't get around the issue that even with the setting above, Next.js asks me to cache the await getT() call in RootLayout (note: I'm testing it with next dev not next build). The README tells me to "pass { lng } explicitly there", but that made no difference to me. I probably have misunderstood this part, because this instruction came with no example code.
• Will the localeInPath: 'internal' setting in i18n.config.ts break the i18nextOptions: { preload: [] } setting in i18n.config.ts?

Thanks in advance.

[adrai]

Hi @rkrisztian, thanks for the detailed questions. I reproduced your setup with Next.js 16.4.3, cacheComponents: true and localeInPath: 'internal'.

1. Is 'internal' the only option?

For clean URLs plus prerendered routes, yes. With localeInPath: false, getT() can only take the language from headers()/cookies(), and under Cache Components that makes every route dynamic. 'internal' keeps the app/[lng]/ segment, but only in the internal rewrite: the public URL stays /about and getT() reads the language from the root param.

2. The error on await getT() in the root layout

I see two possible causes:

• The root layout is not inside [lng]. Coming from localeInPath: false, your routes probably live directly under app/. With 'internal' they have to move back under app/[lng]/, and app/[lng]/layout.tsx must be the root layout (no app/layout.tsx above it). Only then is lng a root param. Otherwise getT() falls back to headers/cookies.

• Translations loading during a render in next dev. The dev check counts translation files loaded during the render as uncached data and points at the await getT() that triggered it. In my repro:

  • with reloadOnPrerender: true it happens on every request (it re-reads the files on each render by design, so turn it off when you use cacheComponents),
  • with an fs.readFile based resourceLoader it happens on the first request per language,
  • with an import() based resourceLoader it happens once, on the first request after next dev starts.

  next build passes in all three cases and prerenders every locale as static (○ /en, ○ /de, ...), so next build is the check to trust here.

The "pass { lng } explicitly" note is only meant for Route Handlers and Server Actions, which have no root params. In a layout it changes nothing, which matches what you saw. This root layout builds and prerenders fine:

// app/[lng]/layout.tsx is the root layout (no app/layout.tsx above it)
import { initServerI18next, getT, getResources, generateI18nStaticParams } from 'next-i18next/server'
import { I18nProvider } from 'next-i18next/client'
import i18nConfig from '../../i18n.config'

initServerI18next(i18nConfig)

export function generateStaticParams() {
  return generateI18nStaticParams()
}

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const { i18n, lng } = await getT()
  // with preload: [] only ship the current and the fallback language
  const resources = getResources(i18n, undefined, [lng, 'en'])

  return (
    <html lang={lng}>
      <body>
        <I18nProvider language={lng} resources={resources}>
          {children}
        </I18nProvider>
      </body>
    </html>
  )
}

3. 'internal' together with preload: []

They work together. The layout above ran with both. next build prerenders every locale, and at runtime each language loads on its first request. Because the store then only holds the languages loaded so far, pass [lng, fallbackLng] to getResources as in the snippet.

If the error is still there after moving the layout and turning off reloadOnPrerender, please share your app/[lng]/layout.tsx and i18n.config.ts.

[rkrisztian]

Thank you very much for the detailed answer.

• I did already move the the layout and all the other routes under app/[lng], but did not help.
• I also tried turning off reloadOnPrerender, which didn't help.
• I do use an import()-based resourceLoader.

So I guess, the error is simply inevitable during next dev with this approach. Not the most ideal experience, but at least I know it only happens once. Hopefully it's really ignorable, and doesn't break the testability of caching in the development web server, but I didn't have time to check this yet.

Regardless, please give me some time to prepare a minimalist project to show.

[adrai]

Thanks for checking. It turns out the error is not inevitable. The one-time report comes from i18next itself: without inline resources, init() starts loading in a setTimeout(load, 0), and Next counts that timer in the first render as uncached work. Setting initAsync: false makes i18next start loading right away:

const i18nConfig: I18nConfig = {
  // ...
  localeInPath: 'internal',
  i18nextOptions: { preload: [], initAsync: false },
}

With that, my repro (Next.js 16.4.3, cacheComponents: true, import()-based resourceLoader) shows no error in next dev anymore, also not on the first request after the dev server starts, both with preload: [] and with the default preload.

I'll make initAsync: false the default for the server instance in next-i18next, so you won't need the option for long. A minimal project is still welcome if you run into anything else.

[adrai]

The fix is on master now (228eed2): the server instance inits with initAsync: false by default, so the option is no longer needed.

Do you need a release right away, or is it fine for you if I wait a couple of days and bundle it with other changes? Until then, i18nextOptions: { initAsync: false } in your config does the same.

[rkrisztian]

Not urgent at all, take your time, and thanks!

[adrai]

thx, included in v16.4.5