@fluenti/next

`withFluenti(config?)`

Wrap your Next.js config to add the Fluenti compiler plugin. Returns a function that accepts the Next.js config:

import { withFluenti } from '@fluenti/next'

export default withFluenti()({
  reactStrictMode: true,
})

Config

All options are optional. Defaults are read from fluenti.config.ts in the project root. Options passed here override the config file values.

Option	Type	Default	Description
`locales`	`string[]?`	from config file	Override locale list
`defaultLocale`	`string?`	from config file	Override default/fallback locale (maps to `sourceLocale` in config)
`compiledDir`	`string?`	from config file	Path to compiled message catalogs (maps to `compileOutDir` in config)
`resolveLocale`	`string?`	reads `locale` cookie	Path to a module that default-exports `() => string \| Promise<string>`. Used in Server Actions and other contexts where the layout doesn’t run
`serverModule`	`string?`	auto-generated	Path to a custom server module. When provided, skips auto-generation
`serverModuleOutDir`	`string?`	`node_modules/.fluenti`	Directory where generated server module files are written
`dateFormats`	`DateFormatOptions?`	—	Custom date format presets (passed to `createServerI18n`)
`numberFormats`	`NumberFormatOptions?`	—	Custom number format presets (passed to `createServerI18n`)
`fallbackChain`	`Record<string, string[]>?`	—	Locale fallback chains (e.g. `{ 'zh-TW': ['zh-CN', 'en'] }`)

What it does

Generates a server module at node_modules/.fluenti/server.js containing:
- A createServerI18n instance with setLocale(), getI18n(), and server components
- A FluentProvider async component for layouts
- A ClientI18nProvider with statically imported message catalogs
Registers a webpack loader that transforms t`...` and t() calls into __i18n.t() lookups
Adds a resolve alias mapping @fluenti/next/__generated to the generated module

Webpack loader

The loader auto-detects server vs client context:

Context	Detection	i18n source
Client	`'use client'` directive or `pages/` directory	`globalThis.__fluenti_i18n` (set by `I18nProvider`)
Server	`'use server'` directive or `app/` directory	`__getServerI18n()` via `React.cache()` store

The transform uses a Proxy to defer access until render time, so module-level t`` calls work correctly.

Generated Modules

withFluenti() generates modules at node_modules/.fluenti/ and aliases them as @fluenti/next/__generated.

`@fluenti/next/__generated`

// @ts-expect-error — generated at build time
import { FluentProvider } from '@fluenti/next/__generated'

Export	Type	Description
`FluentProvider`	async server component	Sets server locale + wraps children in `ClientI18nProvider`
`setLocale`	`(locale: string) => void`	Set locale for the current request (`React.cache()` scoped)
`getI18n`	`() => Promise<FluentInstance>`	Get the i18n instance for the current request
`Trans`	async server component	Rich text translation
`Plural`	async server component	Locale-aware pluralization
`DateTime`	async server component	Date formatting
`NumberFormat`	async server component	Number formatting

`FluentProvider`

Accepts locale and children. Internally calls setLocale(), initializes the server i18n instance, and renders a ClientI18nProvider with pre-imported message catalogs:

import { cookies } from 'next/headers'
// @ts-expect-error — generated at build time
import { FluentProvider } from '@fluenti/next/__generated'

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const locale = (await cookies()).get('locale')?.value ?? 'en'
  return (
    <html lang={locale}>
      <body>
        <FluentProvider locale={locale}>{children}</FluentProvider>
      </body>
    </html>
  )
}

`withLocale(locale, fn)`

Temporarily switch the request-scoped locale for a subtree render. Useful for rendering a component in a different locale within the same request:

import { withLocale } from '@fluenti/next/server'

export default async function Page() {
  const jaContent = await withLocale('ja', async () => {
    return <Trans>Hello</Trans>  // renders in Japanese
  })
  return <div>{jaContent}</div>
}

Usage

For setup and usage details, see the Next.js guide and Server Components.