SSR & Hydration

Key Rules

No shared global state — Every SSR request gets its own Fluenti instance
Hydration consistency — Client always reads the server-determined locale from payload
Path-first detection — In SSG/ISR, the URL path is the only reliable locale source

Detection Priority

Use detectLocale from core with a clear priority chain:

cookie → query → path → Accept-Language → fallback

import { detectLocale } from '@fluenti/core'

const locale = detectLocale({
  cookie: req.headers.cookie,
  query: url.searchParams.get('lang'),
  path: url.pathname,
  headers: req.headers,
  available: ['en', 'ja', 'zh-CN'],
  fallback: 'en',
})

Always set `<html lang>` and `<html dir>`

import { getDirection } from '@fluenti/core'

const dir = getDirection(locale) // 'ltr' or 'rtl'
// <html lang="${locale}" dir="${dir}">

After the user explicitly switches locale, store the preference in a cookie so detectLocale picks it up on the next server request.

Hydration Script

For manual SSR (without Nuxt or Next.js), use getSSRLocaleScript to inject the server-detected locale into the HTML:

import { getSSRLocaleScript, getHydratedLocale } from '@fluenti/core'

// Server: inject into HTML <head>
const script = getSSRLocaleScript(locale)
// → <script>window.__FLUENTI_LOCALE__="ja"</script>

// Client: read it back
const locale = getHydratedLocale('en')

Framework-Specific SSR

Uses withFluenti() and FluentProvider. Cookie-based locale detection via cookies() from next/headers. RSC support via createServerI18n.

See Next.js guide and Server Components.

Zero-config — the @fluenti/nuxt module handles locale detection, cookie persistence, <html lang>, SSR hydration, SSG, and ISR automatically.

See Nuxt SSR.

// server
import { detectLocale, getSSRLocaleScript } from '@fluenti/core'
import { createFluentVue } from '@fluenti/vue'

const locale = detectLocale({
  cookie: getCookie(event, 'lang'),
  headers: event?.headers,
  available: ['en', 'zh-CN', 'ja'],
  fallback: 'en',
})
const i18n = createFluentVue({ locale, messages: allMessages })
app.use(i18n)

const script = getSSRLocaleScript(locale)

// client
import { getHydratedLocale } from '@fluenti/core'

const locale = getHydratedLocale('en')
const i18n = createFluentVue({ locale, messages: allMessages })
app.use(i18n)

See Vue Manual SSR.

Uses getSSRLocaleScript + getHydratedLocale with isServer guard for mismatch-free hydration.

See SolidStart guide.

SolidJS is naturally SSR-safe — each renderToString() creates a new component tree with isolated signals.

See SolidJS Manual SSR.

Utilities

Utility	Description
`detectLocale(options)`	Detect locale from cookie, query, path, or Accept-Language header
`getSSRLocaleScript(locale)`	Generate a `<script>` tag to inject locale into HTML (XSS-safe)
`getHydratedLocale(fallback)`	Read the injected locale on the client
`getDirection(locale)`	Return `'rtl'` or `'ltr'`
`isRTL(locale)`	Check if a locale is right-to-left