@fluenti/react 0.3.4 → 0.4.0-rc.0

package/dist/provider.d.ts

@@ -1,3 +1,44 @@
 import { FluentiProviderProps } from './types';
+/**
+ * Provides the Fluenti i18n context to the React component tree.
+ *
+ * Accepts either a `locale` + `messages` pair for inline configuration,
+ * or a pre-created `instance` from `createFluenti()`.
+ *
+ * @example
+ * ```tsx
+ * import { I18nProvider, useI18n } from '@fluenti/react'
+ * import messages from './locales/compiled/en.js'
+ *
+ * function App() {
+ *   return (
+ *     <I18nProvider locale="en" messages={{ en: messages }}>
+ *       <Content />
+ *     </I18nProvider>
+ *   )
+ * }
+ *
+ * function Content() {
+ *   const { t } = useI18n()
+ *   return <h1>{t`Welcome to our app`}</h1>
+ * }
+ * ```
+ *
+ * @example Using a pre-created instance
+ * ```tsx
+ * import { I18nProvider, createFluenti } from '@fluenti/react'
+ * import messages from './locales/compiled/en.js'
+ *
+ * const i18n = createFluenti({ locale: 'en', messages: { en: messages } })
+ *
+ * function App() {
+ *   return (
+ *     <I18nProvider instance={i18n}>
+ *       <Content />
+ *     </I18nProvider>
+ *   )
+ * }
+ * ```
+ */
 export declare function I18nProvider(props: FluentiProviderProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,oBAAoB,EAAkB,MAAM,SAAS,CAAA;AAwDnE,wBAAgB,YAAY,CAAC,KAAK,EAAE,oBAAoB,2CAMvD"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAkB,MAAM,SAAS,CAAA;AAiCnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,oBAAoB,2CAMvD"}

package/dist/server.cjs

@@ -1,2 +1,2 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require(`./icu-rich-DQtv128R.cjs`);let t=require(`react`),n=require(`@fluenti/core`),r=require(`@fluenti/core/internal`);function i(i){let a=(0,t.cache)(()=>({locale:null,instance:null})),o=(0,t.cache)(()=>new Map),s=null,c=0,l=0;function u(e){a().locale=e,c++,s=null}async function d(e){let t=o(),n=t.get(e);if(n)return n;let r=await i.loadMessages(e),a=typeof r==`object`&&r&&`default`in r?r.default:r;return t.set(e,a),a}async function f(){let e=a();!e.locale&&i.resolveLocale&&(e.locale=await i.resolveLocale());let t=e.locale;if(!t)throw Error(`[fluenti] No locale set. Call setLocale(locale) in your layout before using getI18n(), or provide a resolveLocale function in createServerI18n config to auto-detect locale in Server Actions and other contexts where the layout does not run.`);if(e.instance&&e.instance.locale===t)return e.instance;let r={};r[t]=await d(t),i.fallbackLocale&&i.fallbackLocale!==t&&(r[i.fallbackLocale]=await d(i.fallbackLocale));let o={locale:t,messages:r};return i.fallbackLocale!==void 0&&(o.fallbackLocale=i.fallbackLocale),i.fallbackChain!==void 0&&(o.fallbackChain=i.fallbackChain),i.dateFormats!==void 0&&(o.dateFormats=i.dateFormats),i.numberFormats!==void 0&&(o.numberFormats=i.numberFormats),i.missing!==void 0&&(o.missing=i.missing),e.instance=(0,n.createFluentiCore)(o),s=e.instance,l=c,e.instance}async function p({children:n,id:i,context:a,comment:o,render:s}){let c=await f(),{message:l,components:u}=e.r(n),d=i??(0,r.hashMessage)(l,a),p=e.i(c.t({id:d,message:l,...a===void 0?{}:{context:a},...o===void 0?{}:{comment:o}}),u);return(0,t.createElement)(t.Fragment,null,s?s(p):p)}async function m({value:n,id:i,context:a,comment:o,zero:s,one:c,two:l,few:u,many:d,other:p,offset:m}){let h=await f(),{messages:g,components:_}=e.n(r.PLURAL_CATEGORIES,{zero:s,one:c,two:l,few:u,many:d,other:p}),v=(0,r.buildICUPluralMessage)({...g.zero!==void 0&&{zero:g.zero},...g.one!==void 0&&{one:g.one},...g.two!==void 0&&{two:g.two},...g.few!==void 0&&{few:g.few},...g.many!==void 0&&{many:g.many},other:g.other??``},m);return(0,t.createElement)(t.Fragment,null,e.t({id:i??(a===void 0?v:(0,r.hashMessage)(v,a)),message:v,...a===void 0?{}:{context:a},...o===void 0?{}:{comment:o}},{count:n},(e,t)=>h.t(e,t),_))}async function h({value:n,id:i,context:a,comment:o,other:s,options:c,...l}){let u=await f(),d=c===void 0?{...Object.fromEntries(Object.entries(l).filter(([e])=>![`value`,`id`,`context`,`comment`,`options`,`other`].includes(e))),other:s}:{...c,other:s},p=[...Object.keys(d).filter(e=>e!==`other`),`other`],{messages:m,components:h}=e.n(p,d),g=(0,r.normalizeSelectForms)(Object.fromEntries([...p].map(e=>[e,m[e]??``]))),_=(0,r.buildICUSelectMessage)(g.forms);return(0,t.createElement)(t.Fragment,null,e.t({id:i??(a===void 0?_:(0,r.hashMessage)(_,a)),message:_,...a===void 0?{}:{context:a},...o===void 0?{}:{comment:o}},{value:g.valueMap[n]??`other`},(e,t)=>u.t(e,t),h))}async function g({value:e,format:n}){return(0,t.createElement)(t.Fragment,null,(await f()).d(e,n))}async function _({value:e,format:n}){return(0,t.createElement)(t.Fragment,null,(await f()).n(e,n))}function v(){let e=a();if(e.instance)return e.instance;if(s&&l===c)return s;let t=e.locale??i.fallbackLocale??`en`,r=o(),u={},d=r.get(t);if(d&&(u[t]=d),i.fallbackLocale&&i.fallbackLocale!==t){let e=r.get(i.fallbackLocale);e&&(u[i.fallbackLocale]=e)}let f={locale:t,messages:u};return i.fallbackLocale!==void 0&&(f.fallbackLocale=i.fallbackLocale),i.fallbackChain!==void 0&&(f.fallbackChain=i.fallbackChain),i.dateFormats!==void 0&&(f.dateFormats=i.dateFormats),i.numberFormats!==void 0&&(f.numberFormats=i.numberFormats),i.missing!==void 0&&(f.missing=i.missing),e.instance=(0,n.createFluentiCore)(f),e.instance}async function y(e,t){let n=await f();return(await d(t??n.locale))[e]!==void 0}async function b(e,t){let n=await f();return(await d(t??n.locale))[e]}return{setLocale:u,getI18n:f,__getSyncInstance:v,te:y,tm:b,Trans:p,Plural:m,Select:h,DateTime:g,NumberFormat:_}}exports.createServerI18n=i,Object.defineProperty(exports,`detectLocale`,{enumerable:!0,get:function(){return n.detectLocale}}),Object.defineProperty(exports,`getDirection`,{enumerable:!0,get:function(){return n.getDirection}}),Object.defineProperty(exports,`getHydratedLocale`,{enumerable:!0,get:function(){return n.getHydratedLocale}}),Object.defineProperty(exports,`getSSRLocaleScript`,{enumerable:!0,get:function(){return n.getSSRLocaleScript}}),Object.defineProperty(exports,`isRTL`,{enumerable:!0,get:function(){return n.isRTL}});
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require(`./icu-rich-CotMVC_x.cjs`);let t=require(`react`),n=require(`@fluenti/core`),r=require(`@fluenti/core/internal`),i=require(`@fluenti/core/ssr`);function a(i){let a=(0,t.cache)(()=>({locale:null,instance:null})),o=(0,t.cache)(()=>new Map),s=null,c=0,l=0;function u(e){a().locale=e,c++,s=null}async function d(e){let t=o(),n=t.get(e);if(n)return n;let r=await i.loadMessages(e),a=typeof r==`object`&&r&&`default`in r?r.default:r;return t.set(e,a),a}async function f(){let e=a();!e.locale&&i.resolveLocale&&(e.locale=await i.resolveLocale());let t=e.locale;if(!t)throw Error(`[fluenti] No locale set. Call setLocale(locale) in your layout before using getI18n(), or provide a resolveLocale function in createServerI18n config to auto-detect locale in Server Actions and other contexts where the layout does not run.`);if(e.instance&&e.instance.locale===t)return e.instance;let r={};r[t]=await d(t),i.fallbackLocale&&i.fallbackLocale!==t&&(r[i.fallbackLocale]=await d(i.fallbackLocale));let o={locale:t,messages:r};return i.fallbackLocale!==void 0&&(o.fallbackLocale=i.fallbackLocale),i.fallbackChain!==void 0&&(o.fallbackChain=i.fallbackChain),i.dateFormats!==void 0&&(o.dateFormats=i.dateFormats),i.numberFormats!==void 0&&(o.numberFormats=i.numberFormats),i.missing!==void 0&&(o.missing=i.missing),i.interpolate!==void 0&&(o.interpolate=i.interpolate),e.instance=(0,n.createFluentiCore)(o),s=e.instance,l=c,e.instance}async function p({children:n,id:i,context:a,comment:o,render:s}){let c=await f(),{message:l,components:u}=e.r(n),d=i??(0,r.hashMessage)(l,a),p=e.i(c.t({id:d,message:l,...a===void 0?{}:{context:a},...o===void 0?{}:{comment:o}}),u);return(0,t.createElement)(t.Fragment,null,s?s(p):p)}async function m({value:n,id:i,context:a,comment:o,zero:s,one:c,two:l,few:u,many:d,other:p,offset:m}){let h=await f(),{messages:g,components:_}=e.n(r.PLURAL_CATEGORIES,{zero:s,one:c,two:l,few:u,many:d,other:p}),v=(0,r.buildICUPluralMessage)({...g.zero!==void 0&&{zero:g.zero},...g.one!==void 0&&{one:g.one},...g.two!==void 0&&{two:g.two},...g.few!==void 0&&{few:g.few},...g.many!==void 0&&{many:g.many},other:g.other??``},m);return(0,t.createElement)(t.Fragment,null,e.t({id:i??(a===void 0?v:(0,r.hashMessage)(v,a)),message:v,...a===void 0?{}:{context:a},...o===void 0?{}:{comment:o}},{count:n},(e,t)=>h.t(e,t),_))}async function h({value:n,id:i,context:a,comment:o,other:s,options:c,...l}){let u=await f(),d=c===void 0?{...Object.fromEntries(Object.entries(l).filter(([e])=>![`value`,`id`,`context`,`comment`,`options`,`other`].includes(e))),other:s}:{...c,other:s},p=[...Object.keys(d).filter(e=>e!==`other`),`other`],{messages:m,components:h}=e.n(p,d),g=(0,r.normalizeSelectForms)(Object.fromEntries([...p].map(e=>[e,m[e]??``]))),_=(0,r.buildICUSelectMessage)(g.forms);return(0,t.createElement)(t.Fragment,null,e.t({id:i??(a===void 0?_:(0,r.hashMessage)(_,a)),message:_,...a===void 0?{}:{context:a},...o===void 0?{}:{comment:o}},{value:g.valueMap[n]??`other`},(e,t)=>u.t(e,t),h))}async function g({value:e,format:n}){return(0,t.createElement)(t.Fragment,null,(await f()).d(e,n))}async function _({value:e,format:n}){return(0,t.createElement)(t.Fragment,null,(await f()).n(e,n))}function v(){let e=a();if(e.instance)return e.instance;if(s&&l===c)return s;let t=e.locale??i.fallbackLocale??`en`,r=o(),u={},d=r.get(t);if(d&&(u[t]=d),i.fallbackLocale&&i.fallbackLocale!==t){let e=r.get(i.fallbackLocale);e&&(u[i.fallbackLocale]=e)}let f={locale:t,messages:u};return i.fallbackLocale!==void 0&&(f.fallbackLocale=i.fallbackLocale),i.fallbackChain!==void 0&&(f.fallbackChain=i.fallbackChain),i.dateFormats!==void 0&&(f.dateFormats=i.dateFormats),i.numberFormats!==void 0&&(f.numberFormats=i.numberFormats),i.missing!==void 0&&(f.missing=i.missing),i.interpolate!==void 0&&(f.interpolate=i.interpolate),e.instance=(0,n.createFluentiCore)(f),e.instance}async function y(e,t){let n=await f();return(await d(t??n.locale))[e]!==void 0}async function b(e,t){let n=await f();return(await d(t??n.locale))[e]}return{setLocale:u,getI18n:f,__getSyncInstance:v,te:y,tm:b,Trans:p,Plural:m,Select:h,DateTime:g,NumberFormat:_}}exports.createServerI18n=a,Object.defineProperty(exports,`detectLocale`,{enumerable:!0,get:function(){return i.detectLocale}}),Object.defineProperty(exports,`getDirection`,{enumerable:!0,get:function(){return n.getDirection}}),Object.defineProperty(exports,`getHydratedLocale`,{enumerable:!0,get:function(){return i.getHydratedLocale}}),Object.defineProperty(exports,`getSSRLocaleScript`,{enumerable:!0,get:function(){return i.getSSRLocaleScript}}),Object.defineProperty(exports,`isRTL`,{enumerable:!0,get:function(){return n.isRTL}});
 //# sourceMappingURL=server.cjs.map

package/dist/server.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"server.cjs","names":[],"sources":["../src/server.ts"],"sourcesContent":["import { cache } from 'react'\nimport { createFluentiCore } from '@fluenti/core'\nimport type {\n  FluentiCoreInstanceFull,\n  FluentiCoreConfigFull,\n  Locale,\n  Messages,\n  DateFormatOptions,\n  NumberFormatOptions,\n} from '@fluenti/core'\nimport { hashMessage as hashSyntheticMessage } from '@fluenti/core/internal'\nimport { createElement, Fragment, type ReactNode, type ReactElement } from 'react'\nimport { hashMessage, extractMessage, reconstruct } from './components/trans-core'\nimport { PLURAL_CATEGORIES, type PluralCategory } from './components/plural-core'\nimport { buildICUPluralMessage, buildICUSelectMessage, normalizeSelectForms, renderRichTranslation, serializeRichForms } from './components/icu-rich'\n\n// Re-export SSR utilities from core for convenience\nexport { detectLocale, getSSRLocaleScript, getHydratedLocale, isRTL, getDirection } from '@fluenti/core'\nexport type { DetectLocaleOptions } from '@fluenti/core'\n\n/**\n * Configuration for `createServerI18n`.\n */\nexport interface ServerI18nConfig {\n  /** Load messages for a given locale. Called once per locale per request. */\n  loadMessages: (locale: string) => Promise<Messages | { default: Messages }>\n  /** Fallback locale when a translation is missing */\n  fallbackLocale?: string\n  /**\n   * Auto-resolve locale when `setLocale()` was not called.\n   *\n   * This is the fallback for contexts where the layout doesn't run — most\n   * notably **Server Actions** (`'use server'`), which are independent\n   * requests that skip the layout tree entirely.\n   *\n   * Common patterns:\n   * - Read from a cookie (Next.js: `cookies().get('locale')`)\n   * - Read from a request header set by middleware\n   * - Query the database for the authenticated user's preference\n   *\n   * If omitted and `setLocale()` was not called, `getI18n()` will throw.\n   *\n   * @example\n   * ```ts\n   * resolveLocale: async () => {\n   *   const { cookies } = await import('next/headers')\n   *   return (await cookies()).get('locale')?.value ?? 'en'\n   * }\n   * ```\n   */\n  resolveLocale?: () => string | Promise<string>\n  /** Custom fallback chains per locale */\n  fallbackChain?: Record<string, Locale[]>\n  /** Custom date format styles */\n  dateFormats?: DateFormatOptions\n  /** Custom number format styles */\n  numberFormats?: NumberFormatOptions\n  /** Handler for missing translation keys */\n  missing?: (locale: Locale, id: string) => string | undefined\n}\n\n// ─── Server Component Props ──────────────────────────────────────────────────\n\nexport interface ServerTransProps {\n  /** Source text with embedded components */\n  children: ReactNode\n  /** Override auto-generated hash ID */\n  id?: string\n  /** Message context used for identity and translator disambiguation */\n  context?: string\n  /** Context comment for translators */\n  comment?: string\n  /** Custom render wrapper */\n  render?: (translation: ReactNode) => ReactNode\n}\n\nexport interface ServerPluralProps {\n  /** The count value */\n  value: number\n  /** Override the auto-generated synthetic ICU message id */\n  id?: string\n  /** Message context used for identity and translator disambiguation */\n  context?: string\n  /** Translator-facing note preserved in extraction catalogs */\n  comment?: string\n  /** Text for zero (if language supports) */\n  zero?: ReactNode\n  /** Singular form. `#` replaced with value */\n  one?: ReactNode\n  /** Dual form (Arabic, etc.) */\n  two?: ReactNode\n  /** Few form (Slavic languages, etc.) */\n  few?: ReactNode\n  /** Many form */\n  many?: ReactNode\n  /** Default plural form */\n  other: ReactNode\n  /** Offset from value before selecting form */\n  offset?: number\n}\n\nexport interface ServerSelectProps {\n  /** The selector value */\n  value: string\n  /** Override the auto-generated synthetic ICU message id */\n  id?: string\n  /** Message context used for identity and translator disambiguation */\n  context?: string\n  /** Translator-facing note preserved in extraction catalogs */\n  comment?: string\n  /** Default case */\n  other: ReactNode\n  /** Type-safe named options. Takes precedence over direct case props. */\n  options?: Record<string, ReactNode>\n  /** Named cases — any string key maps to a ReactNode */\n  [key: string]: ReactNode | Record<string, ReactNode> | string | undefined\n}\n\nexport interface ServerDateTimeProps {\n  /** Date value to format */\n  value: Date | number\n  /** Named format key defined in dateFormats config */\n  format?: string\n}\n\nexport interface ServerNumberProps {\n  /** Number value to format */\n  value: number\n  /** Named format key defined in numberFormats config */\n  format?: string\n}\n\n// ─── Server Component Types ──────────────────────────────────────────────────\n\ntype ServerTransComponent = (props: ServerTransProps) => Promise<ReactElement>\ntype ServerPluralComponent = (props: ServerPluralProps) => Promise<ReactElement>\ntype ServerSelectComponent = (props: ServerSelectProps) => Promise<ReactElement>\ntype ServerDateTimeComponent = (props: ServerDateTimeProps) => Promise<ReactElement>\ntype ServerNumberComponent = (props: ServerNumberProps) => Promise<ReactElement>\n\n/**\n * The object returned by `createServerI18n`.\n */\nexport interface ServerI18n {\n  /**\n   * Set the locale for the current server request.\n   * Call this once in your root layout or page before any `getI18n()` calls.\n   *\n   * Uses `React.cache()` — scoped to the current request automatically.\n   */\n  setLocale: (locale: string) => void\n\n  /**\n   * Get a fully configured i18n instance for the current request.\n   * Messages are loaded lazily and cached per-request.\n   *\n   * @example\n   * ```tsx\n   * // In any Server Component\n   * const { t, d, n, locale } = await getI18n()\n   * return <h1>{t('welcome')}</h1>\n   * ```\n   */\n  getI18n: () => Promise<FluentiCoreInstanceFull & { locale: string }>\n\n  /**\n   * `<Trans>` for React Server Components.\n   * Async component — automatically resolves the i18n instance.\n   *\n   * @example\n   * ```tsx\n   * <Trans>Read the <a href=\"/docs\">documentation</a>.</Trans>\n   * ```\n   */\n  Trans: ServerTransComponent\n\n  /**\n   * `<Plural>` for React Server Components.\n   *\n   * @example\n   * ```tsx\n   * <Plural value={count} one=\"# item\" other=\"# items\" />\n   * ```\n   */\n  Plural: ServerPluralComponent\n\n  /**\n   * `<Select>` for React Server Components.\n   *\n   * @example\n   * ```tsx\n   * <Select value={gender} male=\"He liked this\" other=\"They liked this\" />\n   * ```\n   */\n  Select: ServerSelectComponent\n\n  /**\n   * `<DateTime>` for React Server Components.\n   *\n   * @example\n   * ```tsx\n   * <DateTime value={new Date()} format=\"long\" />\n   * ```\n   */\n  DateTime: ServerDateTimeComponent\n\n  /**\n   * `<NumberFormat>` for React Server Components.\n   *\n   * @example\n   * ```tsx\n   * <NumberFormat value={1234.56} format=\"currency\" />\n   * ```\n   */\n  NumberFormat: ServerNumberComponent\n\n  /**\n   * Check if a translation key exists in the catalog.\n   * Optionally check a specific locale instead of the current one.\n   */\n  te: (key: string, locale?: string) => Promise<boolean>\n\n  /**\n   * Get the raw compiled message without interpolation.\n   * Optionally look up in a specific locale instead of the current one.\n   */\n  tm: (key: string, locale?: string) => Promise<Messages[string] | undefined>\n\n  /**\n   * Synchronous accessor for the cached i18n instance.\n   * Used internally by @fluenti/next webpack loader.\n   * @internal\n   */\n  __getSyncInstance: () => FluentiCoreInstanceFull & { locale: string }\n}\n\n/**\n * Create server-side i18n utilities for React Server Components.\n *\n * Uses `React.cache()` to share state within a single server request\n * without React Context (which is unavailable in Server Components).\n *\n * @example\n * ```ts\n * // lib/i18n.server.ts — define once\n * import { createServerI18n } from '@fluenti/react/server'\n *\n * export const { setLocale, getI18n, Trans, Plural, Select, DateTime, NumberFormat } = createServerI18n({\n *   loadMessages: (locale) => import(`../messages/${locale}.json`),\n *   fallbackLocale: 'en',\n * })\n * ```\n *\n * ```tsx\n * // app/[locale]/layout.tsx — set locale once\n * import { setLocale } from '@/lib/i18n.server'\n *\n * export default async function Layout({ params, children }) {\n *   const { locale } = await params\n *   setLocale(locale)\n *   return <html lang={locale}><body>{children}</body></html>\n * }\n * ```\n *\n * ```tsx\n * // app/[locale]/page.tsx — use Trans, Plural, etc. directly\n * import { Trans, Plural, Select } from '@/lib/i18n.server'\n *\n * export default async function Page() {\n *   return (\n *     <div>\n *       <Trans>Read the <a href=\"/docs\">documentation</a>.</Trans>\n *       <Plural value={5} one=\"# item\" other=\"# items\" />\n *       <Select value=\"male\" male=\"He liked this\" other=\"They liked this\" />\n *     </div>\n *   )\n * }\n * ```\n */\nexport function createServerI18n(config: ServerI18nConfig): ServerI18n {\n  // Request-scoped store using React.cache()\n  // Each server request gets its own isolated state\n  const getRequestStore = cache((): {\n    locale: string | null\n    instance: (FluentiCoreInstanceFull & { locale: string }) | null\n  } => ({\n    locale: null,\n    instance: null,\n  }))\n\n  // Cache loaded messages per-request to avoid redundant imports\n  const getMessageCache = cache((): Map<string, Messages> => new Map())\n\n  // Module-level fallback for server actions where React.cache()\n  // may not share state with the page render.\n  let _lastInstance: (FluentiCoreInstanceFull & { locale: string }) | null = null\n  let _requestId = 0\n  let _lastRequestId = 0\n\n  function setLocale(locale: string): void {\n    getRequestStore().locale = locale\n    _requestId++\n    _lastInstance = null\n  }\n\n  async function loadLocaleMessages(locale: string): Promise<Messages> {\n    const messageCache = getMessageCache()\n    const cached = messageCache.get(locale)\n    if (cached) return cached\n\n    const raw = await config.loadMessages(locale)\n    const messages: Messages =\n      typeof raw === 'object' && raw !== null && 'default' in raw\n        ? (raw as { default: Messages }).default\n        : (raw as Messages)\n\n    messageCache.set(locale, messages)\n    return messages\n  }\n\n  async function getI18n(): Promise<FluentiCoreInstanceFull & { locale: string }> {\n    const store = getRequestStore()\n\n    // If setLocale() was never called (e.g. Server Action — independent request\n    // that skips the layout), try the resolveLocale fallback.\n    if (!store.locale && config.resolveLocale) {\n      store.locale = await config.resolveLocale()\n    }\n\n    const locale = store.locale\n\n    if (!locale) {\n      throw new Error(\n        '[fluenti] No locale set. Call setLocale(locale) in your layout before using getI18n(), ' +\n          'or provide a resolveLocale function in createServerI18n config to auto-detect locale ' +\n          'in Server Actions and other contexts where the layout does not run.',\n      )\n    }\n\n    // Return cached instance if locale hasn't changed\n    if (store.instance && store.instance.locale === locale) {\n      return store.instance\n    }\n\n    // Load messages for current locale (and fallback if configured)\n    const allMessages: Record<string, Messages> = {}\n    allMessages[locale] = await loadLocaleMessages(locale)\n\n    if (config.fallbackLocale && config.fallbackLocale !== locale) {\n      allMessages[config.fallbackLocale] = await loadLocaleMessages(config.fallbackLocale)\n    }\n\n    const fluentConfig: FluentiCoreConfigFull = {\n      locale,\n      messages: allMessages,\n    }\n    if (config.fallbackLocale !== undefined) fluentConfig.fallbackLocale = config.fallbackLocale\n    if (config.fallbackChain !== undefined) fluentConfig.fallbackChain = config.fallbackChain\n    if (config.dateFormats !== undefined) fluentConfig.dateFormats = config.dateFormats\n    if (config.numberFormats !== undefined) fluentConfig.numberFormats = config.numberFormats\n    if (config.missing !== undefined) fluentConfig.missing = config.missing\n\n    store.instance = createFluentiCore(fluentConfig)\n    _lastInstance = store.instance\n    _lastRequestId = _requestId\n    return store.instance\n  }\n\n  // ─── Async Server Components ─────────────────────────────────────────────\n\n  async function Trans({ children, id, context, comment, render }: ServerTransProps): Promise<ReactElement> {\n    const i18n = await getI18n()\n    const { message, components } = extractMessage(children)\n    const messageId = id ?? hashMessage(message, context)\n    const translated = i18n.t({\n      id: messageId,\n      message,\n      ...(context !== undefined ? { context } : {}),\n      ...(comment !== undefined ? { comment } : {}),\n    })\n    const result = reconstruct(translated, components)\n    return createElement(Fragment, null, render ? render(result) : result)\n  }\n\n  async function Plural({\n    value,\n    id,\n    context,\n    comment,\n    zero,\n    one,\n    two,\n    few,\n    many,\n    other,\n    offset,\n  }: ServerPluralProps): Promise<ReactElement> {\n    const i18n = await getI18n()\n    const forms: Record<PluralCategory, ReactNode | undefined> = {\n      zero,\n      one,\n      two,\n      few,\n      many,\n      other,\n    }\n    const { messages, components } = serializeRichForms(PLURAL_CATEGORIES, forms)\n    const icuMessage = buildICUPluralMessage(\n      {\n        ...(messages.zero !== undefined && { zero: messages.zero }),\n        ...(messages.one !== undefined && { one: messages.one }),\n        ...(messages.two !== undefined && { two: messages.two }),\n        ...(messages.few !== undefined && { few: messages.few }),\n        ...(messages.many !== undefined && { many: messages.many }),\n        other: messages.other ?? '',\n      },\n      offset,\n    )\n\n    const result = renderRichTranslation(\n      {\n        id: id ?? (context === undefined ? icuMessage : hashSyntheticMessage(icuMessage, context)),\n        message: icuMessage,\n        ...(context !== undefined ? { context } : {}),\n        ...(comment !== undefined ? { comment } : {}),\n      },\n      { count: value },\n      (descriptor, values) => i18n.t(descriptor, values),\n      components,\n    )\n\n    return createElement(Fragment, null, result)\n  }\n\n  async function Select({\n    value,\n    id,\n    context,\n    comment,\n    other,\n    options,\n    ...cases\n  }: ServerSelectProps): Promise<ReactElement> {\n    const i18n = await getI18n()\n    const forms: Record<string, ReactNode | undefined> = options === undefined\n      ? {\n        ...Object.fromEntries(\n          Object.entries(cases).filter(([key]) => !['value', 'id', 'context', 'comment', 'options', 'other'].includes(key)),\n        ),\n        other,\n      }\n      : {\n        ...options,\n        other,\n      }\n\n    const orderedKeys = [...Object.keys(forms).filter(key => key !== 'other'), 'other'] as const\n    const { messages, components } = serializeRichForms(orderedKeys, forms)\n    const normalized = normalizeSelectForms(\n      Object.fromEntries(\n        [...orderedKeys].map((key) => [key, messages[key] ?? '']),\n      ),\n    )\n    const icuMessage = buildICUSelectMessage(normalized.forms)\n\n    const result = renderRichTranslation(\n      {\n        id: id ?? (context === undefined ? icuMessage : hashSyntheticMessage(icuMessage, context)),\n        message: icuMessage,\n        ...(context !== undefined ? { context } : {}),\n        ...(comment !== undefined ? { comment } : {}),\n      },\n      { value: normalized.valueMap[value] ?? 'other' },\n      (descriptor, values) => i18n.t(descriptor, values),\n      components,\n    )\n\n    return createElement(Fragment, null, result)\n  }\n\n  async function DateTime({ value, format }: ServerDateTimeProps): Promise<ReactElement> {\n    const i18n = await getI18n()\n    return createElement(Fragment, null, i18n.d(value, format))\n  }\n\n  async function NumberFormat({ value, format }: ServerNumberProps): Promise<ReactElement> {\n    const i18n = await getI18n()\n    return createElement(Fragment, null, i18n.n(value, format))\n  }\n\n  /**\n   * Synchronous accessor for the cached i18n instance.\n   * Used by @fluenti/next webpack loader for t`` in RSC.\n   *\n   * Falls back to creating a minimal instance from the message cache when the\n   * React.cache() request store hasn't been populated yet — this handles\n   * Suspense boundaries and streamed components where React.cache() state\n   * may not propagate from the layout render into streamed children.\n   * @internal\n   */\n  function __getSyncInstance(): FluentiCoreInstanceFull & { locale: string } {\n    const store = getRequestStore()\n    if (store.instance) {\n      return store.instance\n    }\n\n    // Module-level fallback for server actions where React.cache()\n    // may not share state across different call contexts.\n    // Only use within the same request (tracked by _requestId).\n    if (_lastInstance && _lastRequestId === _requestId) {\n      return _lastInstance\n    }\n\n    // Final fallback: create instance synchronously with the default locale.\n    // This handles Suspense boundaries and streamed components where\n    // the React.cache store may not have been populated yet.\n    const locale = store.locale ?? config.fallbackLocale ?? 'en'\n    const messageCache = getMessageCache()\n    const messages: Record<string, Messages> = {}\n    const cached = messageCache.get(locale)\n    if (cached) messages[locale] = cached\n    if (config.fallbackLocale && config.fallbackLocale !== locale) {\n      const fallback = messageCache.get(config.fallbackLocale)\n      if (fallback) messages[config.fallbackLocale] = fallback\n    }\n\n    const fluentConfig: FluentiCoreConfigFull = { locale, messages }\n    if (config.fallbackLocale !== undefined) fluentConfig.fallbackLocale = config.fallbackLocale\n    if (config.fallbackChain !== undefined) fluentConfig.fallbackChain = config.fallbackChain\n    if (config.dateFormats !== undefined) fluentConfig.dateFormats = config.dateFormats\n    if (config.numberFormats !== undefined) fluentConfig.numberFormats = config.numberFormats\n    if (config.missing !== undefined) fluentConfig.missing = config.missing\n\n    store.instance = createFluentiCore(fluentConfig)\n    return store.instance\n  }\n\n  /**\n   * Check if a translation key exists in the catalog for the given (or current) locale.\n   * Async because it needs to ensure messages are loaded via getI18n().\n   */\n  async function te(key: string, locale?: string): Promise<boolean> {\n    const i18n = await getI18n()\n    const targetLocale = locale ?? i18n.locale\n    const msgs = await loadLocaleMessages(targetLocale)\n    return msgs[key] !== undefined\n  }\n\n  /**\n   * Get the raw compiled message for the given key without interpolation.\n   * Async because it needs to ensure messages are loaded via getI18n().\n   */\n  async function tm(key: string, locale?: string): Promise<Messages[string] | undefined> {\n    const i18n = await getI18n()\n    const targetLocale = locale ?? i18n.locale\n    const msgs = await loadLocaleMessages(targetLocale)\n    return msgs[key]\n  }\n\n  return { setLocale, getI18n, __getSyncInstance, te, tm, Trans, Plural, Select, DateTime, NumberFormat }\n}\n"],"mappings":"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"}
+{"version":3,"file":"server.cjs","names":[],"sources":["../src/server.ts"],"sourcesContent":["import { cache } from 'react'\nimport { createFluentiCore } from '@fluenti/core'\nimport type {\n  FluentiCoreInstanceFull,\n  FluentiCoreConfigFull,\n  Locale,\n  Messages,\n  DateFormatOptions,\n  NumberFormatOptions,\n} from '@fluenti/core'\nimport { hashMessage as hashSyntheticMessage } from '@fluenti/core/internal'\nimport { createElement, Fragment, type ReactNode, type ReactElement } from 'react'\nimport { hashMessage, extractMessage, reconstruct } from './components/trans-core'\nimport { PLURAL_CATEGORIES, type PluralCategory } from './components/plural-core'\nimport { buildICUPluralMessage, buildICUSelectMessage, normalizeSelectForms, renderRichTranslation, serializeRichForms } from './components/icu-rich'\n\n// Re-export SSR utilities from core for convenience\nexport { detectLocale, getSSRLocaleScript, getHydratedLocale } from '@fluenti/core/ssr'\nexport type { DetectLocaleOptions } from '@fluenti/core/ssr'\nexport { isRTL, getDirection } from '@fluenti/core'\n\n/**\n * Configuration for `createServerI18n`.\n */\nexport interface ServerI18nConfig {\n  /** Load messages for a given locale. Called once per locale per request. */\n  loadMessages: (locale: string) => Promise<Messages | { default: Messages }>\n  /** Fallback locale when a translation is missing */\n  fallbackLocale?: string\n  /**\n   * Auto-resolve locale when `setLocale()` was not called.\n   *\n   * This is the fallback for contexts where the layout doesn't run — most\n   * notably **Server Actions** (`'use server'`), which are independent\n   * requests that skip the layout tree entirely.\n   *\n   * Common patterns:\n   * - Read from a cookie (Next.js: `cookies().get('locale')`)\n   * - Read from a request header set by middleware\n   * - Query the database for the authenticated user's preference\n   *\n   * If omitted and `setLocale()` was not called, `getI18n()` will throw.\n   *\n   * @example\n   * ```ts\n   * resolveLocale: async () => {\n   *   const { cookies } = await import('next/headers')\n   *   return (await cookies()).get('locale')?.value ?? 'en'\n   * }\n   * ```\n   */\n  resolveLocale?: () => string | Promise<string>\n  /** Custom fallback chains per locale */\n  fallbackChain?: Record<string, Locale[]>\n  /** Custom date format styles */\n  dateFormats?: DateFormatOptions\n  /** Custom number format styles */\n  numberFormats?: NumberFormatOptions\n  /** Handler for missing translation keys */\n  missing?: (locale: Locale, id: string) => string | undefined\n  /**\n   * Custom interpolation function for ICU MessageFormat parsing.\n   *\n   * By default, the runtime uses a lightweight `{key}` replacer.\n   * Pass the full `interpolate` from `@fluenti/core` for runtime\n   * ICU MessageFormat parsing (plurals, selects, nested arguments).\n   *\n   * @example\n   * ```ts\n   * import { interpolate } from '@fluenti/core'\n   * createServerI18n({ interpolate, ... })\n   * ```\n   */\n  interpolate?: FluentiCoreConfigFull['interpolate']\n}\n\n// ─── Server Component Props ──────────────────────────────────────────────────\n\nexport interface ServerTransProps {\n  /** Source text with embedded components */\n  children: ReactNode\n  /** Override auto-generated hash ID */\n  id?: string\n  /** Message context used for identity and translator disambiguation */\n  context?: string\n  /** Context comment for translators */\n  comment?: string\n  /** Custom render wrapper */\n  render?: (translation: ReactNode) => ReactNode\n}\n\nexport interface ServerPluralProps {\n  /** The count value */\n  value: number\n  /** Override the auto-generated synthetic ICU message id */\n  id?: string\n  /** Message context used for identity and translator disambiguation */\n  context?: string\n  /** Translator-facing note preserved in extraction catalogs */\n  comment?: string\n  /** Text for zero (if language supports) */\n  zero?: ReactNode\n  /** Singular form. `#` replaced with value */\n  one?: ReactNode\n  /** Dual form (Arabic, etc.) */\n  two?: ReactNode\n  /** Few form (Slavic languages, etc.) */\n  few?: ReactNode\n  /** Many form */\n  many?: ReactNode\n  /** Default plural form */\n  other: ReactNode\n  /** Offset from value before selecting form */\n  offset?: number\n}\n\nexport interface ServerSelectProps {\n  /** The selector value */\n  value: string\n  /** Override the auto-generated synthetic ICU message id */\n  id?: string\n  /** Message context used for identity and translator disambiguation */\n  context?: string\n  /** Translator-facing note preserved in extraction catalogs */\n  comment?: string\n  /** Default case */\n  other: ReactNode\n  /** Type-safe named options. Takes precedence over direct case props. */\n  options?: Record<string, ReactNode>\n  /** Named cases — any string key maps to a ReactNode */\n  [key: string]: ReactNode | Record<string, ReactNode> | string | undefined\n}\n\nexport interface ServerDateTimeProps {\n  /** Date value to format */\n  value: Date | number\n  /** Named format key defined in dateFormats config */\n  format?: string\n}\n\nexport interface ServerNumberProps {\n  /** Number value to format */\n  value: number\n  /** Named format key defined in numberFormats config */\n  format?: string\n}\n\n// ─── Server Component Types ──────────────────────────────────────────────────\n\ntype ServerTransComponent = (props: ServerTransProps) => Promise<ReactElement>\ntype ServerPluralComponent = (props: ServerPluralProps) => Promise<ReactElement>\ntype ServerSelectComponent = (props: ServerSelectProps) => Promise<ReactElement>\ntype ServerDateTimeComponent = (props: ServerDateTimeProps) => Promise<ReactElement>\ntype ServerNumberComponent = (props: ServerNumberProps) => Promise<ReactElement>\n\n/**\n * The object returned by `createServerI18n`.\n */\nexport interface ServerI18n {\n  /**\n   * Set the locale for the current server request.\n   * Call this once in your root layout or page before any `getI18n()` calls.\n   *\n   * Uses `React.cache()` — scoped to the current request automatically.\n   */\n  setLocale: (locale: string) => void\n\n  /**\n   * Get a fully configured i18n instance for the current request.\n   * Messages are loaded lazily and cached per-request.\n   *\n   * @example\n   * ```tsx\n   * // In any Server Component\n   * const { t, d, n, locale } = await getI18n()\n   * return <h1>{t('welcome')}</h1>\n   * ```\n   */\n  getI18n: () => Promise<FluentiCoreInstanceFull & { locale: string }>\n\n  /**\n   * `<Trans>` for React Server Components.\n   * Async component — automatically resolves the i18n instance.\n   *\n   * @example\n   * ```tsx\n   * <Trans>Read the <a href=\"/docs\">documentation</a>.</Trans>\n   * ```\n   */\n  Trans: ServerTransComponent\n\n  /**\n   * `<Plural>` for React Server Components.\n   *\n   * @example\n   * ```tsx\n   * <Plural value={count} one=\"# item\" other=\"# items\" />\n   * ```\n   */\n  Plural: ServerPluralComponent\n\n  /**\n   * `<Select>` for React Server Components.\n   *\n   * @example\n   * ```tsx\n   * <Select value={gender} male=\"He liked this\" other=\"They liked this\" />\n   * ```\n   */\n  Select: ServerSelectComponent\n\n  /**\n   * `<DateTime>` for React Server Components.\n   *\n   * @example\n   * ```tsx\n   * <DateTime value={new Date()} format=\"long\" />\n   * ```\n   */\n  DateTime: ServerDateTimeComponent\n\n  /**\n   * `<NumberFormat>` for React Server Components.\n   *\n   * @example\n   * ```tsx\n   * <NumberFormat value={1234.56} format=\"currency\" />\n   * ```\n   */\n  NumberFormat: ServerNumberComponent\n\n  /**\n   * Check if a translation key exists in the catalog.\n   * Optionally check a specific locale instead of the current one.\n   */\n  te: (key: string, locale?: string) => Promise<boolean>\n\n  /**\n   * Get the raw compiled message without interpolation.\n   * Optionally look up in a specific locale instead of the current one.\n   */\n  tm: (key: string, locale?: string) => Promise<Messages[string] | undefined>\n\n  /**\n   * Synchronous accessor for the cached i18n instance.\n   * Used internally by @fluenti/next webpack loader.\n   * @internal\n   */\n  __getSyncInstance: () => FluentiCoreInstanceFull & { locale: string }\n}\n\n/**\n * Create server-side i18n utilities for React Server Components.\n *\n * Uses `React.cache()` to share state within a single server request\n * without React Context (which is unavailable in Server Components).\n *\n * @example\n * ```ts\n * // lib/i18n.server.ts — define once\n * import { createServerI18n } from '@fluenti/react/server'\n *\n * export const { setLocale, getI18n, Trans, Plural, Select, DateTime, NumberFormat } = createServerI18n({\n *   loadMessages: (locale) => import(`../messages/${locale}.json`),\n *   fallbackLocale: 'en',\n * })\n * ```\n *\n * ```tsx\n * // app/[locale]/layout.tsx — set locale once\n * import { setLocale } from '@/lib/i18n.server'\n *\n * export default async function Layout({ params, children }) {\n *   const { locale } = await params\n *   setLocale(locale)\n *   return <html lang={locale}><body>{children}</body></html>\n * }\n * ```\n *\n * ```tsx\n * // app/[locale]/page.tsx — use Trans, Plural, etc. directly\n * import { Trans, Plural, Select } from '@/lib/i18n.server'\n *\n * export default async function Page() {\n *   return (\n *     <div>\n *       <Trans>Read the <a href=\"/docs\">documentation</a>.</Trans>\n *       <Plural value={5} one=\"# item\" other=\"# items\" />\n *       <Select value=\"male\" male=\"He liked this\" other=\"They liked this\" />\n *     </div>\n *   )\n * }\n * ```\n */\nexport function createServerI18n(config: ServerI18nConfig): ServerI18n {\n  // Request-scoped store using React.cache()\n  // Each server request gets its own isolated state\n  const getRequestStore = cache((): {\n    locale: string | null\n    instance: (FluentiCoreInstanceFull & { locale: string }) | null\n  } => ({\n    locale: null,\n    instance: null,\n  }))\n\n  // Cache loaded messages per-request to avoid redundant imports\n  const getMessageCache = cache((): Map<string, Messages> => new Map())\n\n  // Module-level fallback for server actions where React.cache()\n  // may not share state with the page render.\n  let _lastInstance: (FluentiCoreInstanceFull & { locale: string }) | null = null\n  let _requestId = 0\n  let _lastRequestId = 0\n\n  function setLocale(locale: string): void {\n    getRequestStore().locale = locale\n    _requestId++\n    _lastInstance = null\n  }\n\n  async function loadLocaleMessages(locale: string): Promise<Messages> {\n    const messageCache = getMessageCache()\n    const cached = messageCache.get(locale)\n    if (cached) return cached\n\n    const raw = await config.loadMessages(locale)\n    const messages: Messages =\n      typeof raw === 'object' && raw !== null && 'default' in raw\n        ? (raw as { default: Messages }).default\n        : (raw as Messages)\n\n    messageCache.set(locale, messages)\n    return messages\n  }\n\n  async function getI18n(): Promise<FluentiCoreInstanceFull & { locale: string }> {\n    const store = getRequestStore()\n\n    // If setLocale() was never called (e.g. Server Action — independent request\n    // that skips the layout), try the resolveLocale fallback.\n    if (!store.locale && config.resolveLocale) {\n      store.locale = await config.resolveLocale()\n    }\n\n    const locale = store.locale\n\n    if (!locale) {\n      throw new Error(\n        '[fluenti] No locale set. Call setLocale(locale) in your layout before using getI18n(), ' +\n          'or provide a resolveLocale function in createServerI18n config to auto-detect locale ' +\n          'in Server Actions and other contexts where the layout does not run.',\n      )\n    }\n\n    // Return cached instance if locale hasn't changed\n    if (store.instance && store.instance.locale === locale) {\n      return store.instance\n    }\n\n    // Load messages for current locale (and fallback if configured)\n    const allMessages: Record<string, Messages> = {}\n    allMessages[locale] = await loadLocaleMessages(locale)\n\n    if (config.fallbackLocale && config.fallbackLocale !== locale) {\n      allMessages[config.fallbackLocale] = await loadLocaleMessages(config.fallbackLocale)\n    }\n\n    const fluentConfig: FluentiCoreConfigFull = {\n      locale,\n      messages: allMessages,\n    }\n    if (config.fallbackLocale !== undefined) fluentConfig.fallbackLocale = config.fallbackLocale\n    if (config.fallbackChain !== undefined) fluentConfig.fallbackChain = config.fallbackChain\n    if (config.dateFormats !== undefined) fluentConfig.dateFormats = config.dateFormats\n    if (config.numberFormats !== undefined) fluentConfig.numberFormats = config.numberFormats\n    if (config.missing !== undefined) fluentConfig.missing = config.missing\n    if (config.interpolate !== undefined) fluentConfig.interpolate = config.interpolate\n\n    store.instance = createFluentiCore(fluentConfig)\n    _lastInstance = store.instance\n    _lastRequestId = _requestId\n    return store.instance\n  }\n\n  // ─── Async Server Components ─────────────────────────────────────────────\n\n  async function Trans({ children, id, context, comment, render }: ServerTransProps): Promise<ReactElement> {\n    const i18n = await getI18n()\n    const { message, components } = extractMessage(children)\n    const messageId = id ?? hashMessage(message, context)\n    const translated = i18n.t({\n      id: messageId,\n      message,\n      ...(context !== undefined ? { context } : {}),\n      ...(comment !== undefined ? { comment } : {}),\n    })\n    const result = reconstruct(translated, components)\n    return createElement(Fragment, null, render ? render(result) : result)\n  }\n\n  async function Plural({\n    value,\n    id,\n    context,\n    comment,\n    zero,\n    one,\n    two,\n    few,\n    many,\n    other,\n    offset,\n  }: ServerPluralProps): Promise<ReactElement> {\n    const i18n = await getI18n()\n    const forms: Record<PluralCategory, ReactNode | undefined> = {\n      zero,\n      one,\n      two,\n      few,\n      many,\n      other,\n    }\n    const { messages, components } = serializeRichForms(PLURAL_CATEGORIES, forms)\n    const icuMessage = buildICUPluralMessage(\n      {\n        ...(messages.zero !== undefined && { zero: messages.zero }),\n        ...(messages.one !== undefined && { one: messages.one }),\n        ...(messages.two !== undefined && { two: messages.two }),\n        ...(messages.few !== undefined && { few: messages.few }),\n        ...(messages.many !== undefined && { many: messages.many }),\n        other: messages.other ?? '',\n      },\n      offset,\n    )\n\n    const result = renderRichTranslation(\n      {\n        id: id ?? (context === undefined ? icuMessage : hashSyntheticMessage(icuMessage, context)),\n        message: icuMessage,\n        ...(context !== undefined ? { context } : {}),\n        ...(comment !== undefined ? { comment } : {}),\n      },\n      { count: value },\n      (descriptor, values) => i18n.t(descriptor, values),\n      components,\n    )\n\n    return createElement(Fragment, null, result)\n  }\n\n  async function Select({\n    value,\n    id,\n    context,\n    comment,\n    other,\n    options,\n    ...cases\n  }: ServerSelectProps): Promise<ReactElement> {\n    const i18n = await getI18n()\n    const forms: Record<string, ReactNode | undefined> = options === undefined\n      ? {\n        ...Object.fromEntries(\n          Object.entries(cases).filter(([key]) => !['value', 'id', 'context', 'comment', 'options', 'other'].includes(key)),\n        ),\n        other,\n      }\n      : {\n        ...options,\n        other,\n      }\n\n    const orderedKeys = [...Object.keys(forms).filter(key => key !== 'other'), 'other'] as const\n    const { messages, components } = serializeRichForms(orderedKeys, forms)\n    const normalized = normalizeSelectForms(\n      Object.fromEntries(\n        [...orderedKeys].map((key) => [key, messages[key] ?? '']),\n      ),\n    )\n    const icuMessage = buildICUSelectMessage(normalized.forms)\n\n    const result = renderRichTranslation(\n      {\n        id: id ?? (context === undefined ? icuMessage : hashSyntheticMessage(icuMessage, context)),\n        message: icuMessage,\n        ...(context !== undefined ? { context } : {}),\n        ...(comment !== undefined ? { comment } : {}),\n      },\n      { value: normalized.valueMap[value] ?? 'other' },\n      (descriptor, values) => i18n.t(descriptor, values),\n      components,\n    )\n\n    return createElement(Fragment, null, result)\n  }\n\n  async function DateTime({ value, format }: ServerDateTimeProps): Promise<ReactElement> {\n    const i18n = await getI18n()\n    return createElement(Fragment, null, i18n.d(value, format))\n  }\n\n  async function NumberFormat({ value, format }: ServerNumberProps): Promise<ReactElement> {\n    const i18n = await getI18n()\n    return createElement(Fragment, null, i18n.n(value, format))\n  }\n\n  /**\n   * Synchronous accessor for the cached i18n instance.\n   * Used by @fluenti/next webpack loader for t`` in RSC.\n   *\n   * Falls back to creating a minimal instance from the message cache when the\n   * React.cache() request store hasn't been populated yet — this handles\n   * Suspense boundaries and streamed components where React.cache() state\n   * may not propagate from the layout render into streamed children.\n   * @internal\n   */\n  function __getSyncInstance(): FluentiCoreInstanceFull & { locale: string } {\n    const store = getRequestStore()\n    if (store.instance) {\n      return store.instance\n    }\n\n    // Module-level fallback for server actions where React.cache()\n    // may not share state across different call contexts.\n    // Only use within the same request (tracked by _requestId).\n    if (_lastInstance && _lastRequestId === _requestId) {\n      return _lastInstance\n    }\n\n    // Final fallback: create instance synchronously with the default locale.\n    // This handles Suspense boundaries and streamed components where\n    // the React.cache store may not have been populated yet.\n    const locale = store.locale ?? config.fallbackLocale ?? 'en'\n    const messageCache = getMessageCache()\n    const messages: Record<string, Messages> = {}\n    const cached = messageCache.get(locale)\n    if (cached) messages[locale] = cached\n    if (config.fallbackLocale && config.fallbackLocale !== locale) {\n      const fallback = messageCache.get(config.fallbackLocale)\n      if (fallback) messages[config.fallbackLocale] = fallback\n    }\n\n    const fluentConfig: FluentiCoreConfigFull = { locale, messages }\n    if (config.fallbackLocale !== undefined) fluentConfig.fallbackLocale = config.fallbackLocale\n    if (config.fallbackChain !== undefined) fluentConfig.fallbackChain = config.fallbackChain\n    if (config.dateFormats !== undefined) fluentConfig.dateFormats = config.dateFormats\n    if (config.numberFormats !== undefined) fluentConfig.numberFormats = config.numberFormats\n    if (config.missing !== undefined) fluentConfig.missing = config.missing\n    if (config.interpolate !== undefined) fluentConfig.interpolate = config.interpolate\n\n    store.instance = createFluentiCore(fluentConfig)\n    return store.instance\n  }\n\n  /**\n   * Check if a translation key exists in the catalog for the given (or current) locale.\n   * Async because it needs to ensure messages are loaded via getI18n().\n   */\n  async function te(key: string, locale?: string): Promise<boolean> {\n    const i18n = await getI18n()\n    const targetLocale = locale ?? i18n.locale\n    const msgs = await loadLocaleMessages(targetLocale)\n    return msgs[key] !== undefined\n  }\n\n  /**\n   * Get the raw compiled message for the given key without interpolation.\n   * Async because it needs to ensure messages are loaded via getI18n().\n   */\n  async function tm(key: string, locale?: string): Promise<Messages[string] | undefined> {\n    const i18n = await getI18n()\n    const targetLocale = locale ?? i18n.locale\n    const msgs = await loadLocaleMessages(targetLocale)\n    return msgs[key]\n  }\n\n  return { setLocale, getI18n, __getSyncInstance, te, tm, Trans, Plural, Select, DateTime, NumberFormat }\n}\n"],"mappings":"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"}

package/dist/server.d.ts

@@ -1,7 +1,8 @@
-import { FluentiCoreInstanceFull, Locale, Messages, DateFormatOptions, NumberFormatOptions } from '@fluenti/core';
+import { FluentiCoreInstanceFull, FluentiCoreConfigFull, Locale, Messages, DateFormatOptions, NumberFormatOptions } from '@fluenti/core';
 import { ReactNode, ReactElement } from 'react';
-export { detectLocale, getSSRLocaleScript, getHydratedLocale, isRTL, getDirection } from '@fluenti/core';
-export type { DetectLocaleOptions } from '@fluenti/core';
+export { detectLocale, getSSRLocaleScript, getHydratedLocale } from '@fluenti/core/ssr';
+export type { DetectLocaleOptions } from '@fluenti/core/ssr';
+export { isRTL, getDirection } from '@fluenti/core';
 /**
  * Configuration for `createServerI18n`.
  */
@@ -43,6 +44,20 @@ export interface ServerI18nConfig {
     numberFormats?: NumberFormatOptions;
     /** Handler for missing translation keys */
     missing?: (locale: Locale, id: string) => string | undefined;
+    /**
+     * Custom interpolation function for ICU MessageFormat parsing.
+     *
+     * By default, the runtime uses a lightweight `{key}` replacer.
+     * Pass the full `interpolate` from `@fluenti/core` for runtime
+     * ICU MessageFormat parsing (plurals, selects, nested arguments).
+     *
+     * @example
+     * ```ts
+     * import { interpolate } from '@fluenti/core'
+     * createServerI18n({ interpolate, ... })
+     * ```
+     */
+    interpolate?: FluentiCoreConfigFull['interpolate'];
 }
 export interface ServerTransProps {
     /** Source text with embedded components */

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/server.js

@@ -1,18 +1,19 @@
-import { a as e, c as t, i as n, l as r, n as i, o as a, r as o, s, t as c } from "./icu-rich-C9wQm3XF.js";
+import { a as e, c as t, i as n, l as r, n as i, o as a, r as o, s, t as c } from "./icu-rich-ChVWsA7C.js";
 import { Fragment as l, cache as u, createElement as d } from "react";
-import { createFluentiCore as f, detectLocale as p, getDirection as m, getHydratedLocale as h, getSSRLocaleScript as g, isRTL as _ } from "@fluenti/core";
-import { hashMessage as v } from "@fluenti/core/internal";
+import { createFluentiCore as f, getDirection as p, isRTL as m } from "@fluenti/core";
+import { hashMessage as h } from "@fluenti/core/internal";
+import { detectLocale as g, getHydratedLocale as _, getSSRLocaleScript as v } from "@fluenti/core/ssr";
 //#region src/server.ts
 function y(p) {
 	let m = u(() => ({
 		locale: null,
 		instance: null
-	})), h = u(() => /* @__PURE__ */ new Map()), g = null, _ = 0, y = 0;
+	})), g = u(() => /* @__PURE__ */ new Map()), _ = null, v = 0, y = 0;
 	function b(e) {
-		m().locale = e, _++, g = null;
+		m().locale = e, v++, _ = null;
 	}
 	async function x(e) {
-		let t = h(), n = t.get(e);
+		let t = g(), n = t.get(e);
 		if (n) return n;
 		let r = await p.loadMessages(e), i = typeof r == "object" && r && "default" in r ? r.default : r;
 		return t.set(e, i), i;
@@ -29,7 +30,7 @@ function y(p) {
 			locale: t,
 			messages: n
 		};
-		return p.fallbackLocale !== void 0 && (r.fallbackLocale = p.fallbackLocale), p.fallbackChain !== void 0 && (r.fallbackChain = p.fallbackChain), p.dateFormats !== void 0 && (r.dateFormats = p.dateFormats), p.numberFormats !== void 0 && (r.numberFormats = p.numberFormats), p.missing !== void 0 && (r.missing = p.missing), e.instance = f(r), g = e.instance, y = _, e.instance;
+		return p.fallbackLocale !== void 0 && (r.fallbackLocale = p.fallbackLocale), p.fallbackChain !== void 0 && (r.fallbackChain = p.fallbackChain), p.dateFormats !== void 0 && (r.dateFormats = p.dateFormats), p.numberFormats !== void 0 && (r.numberFormats = p.numberFormats), p.missing !== void 0 && (r.missing = p.missing), p.interpolate !== void 0 && (r.interpolate = p.interpolate), e.instance = f(r), _ = e.instance, y = v, e.instance;
 	}
 	async function C({ children: e, id: n, context: i, comment: a, render: o }) {
 		let c = await S(), { message: u, components: f } = s(e), p = n ?? t(u, i), m = r(c.t({
@@ -40,14 +41,14 @@ function y(p) {
 		}), f);
 		return d(l, null, o ? o(m) : m);
 	}
-	async function w({ value: t, id: r, context: i, comment: o, zero: s, one: u, two: f, few: p, many: m, other: h, offset: g }) {
-		let _ = await S(), { messages: y, components: b } = e(a, {
+	async function w({ value: t, id: r, context: i, comment: o, zero: s, one: u, two: f, few: p, many: m, other: g, offset: _ }) {
+		let v = await S(), { messages: y, components: b } = e(a, {
 			zero: s,
 			one: u,
 			two: f,
 			few: p,
 			many: m,
-			other: h
+			other: g
 		}), x = c({
 			...y.zero !== void 0 && { zero: y.zero },
 			...y.one !== void 0 && { one: y.one },
@@ -55,13 +56,13 @@ function y(p) {
 			...y.few !== void 0 && { few: y.few },
 			...y.many !== void 0 && { many: y.many },
 			other: y.other ?? ""
-		}, g);
+		}, _);
 		return d(l, null, n({
-			id: r ?? (i === void 0 ? x : v(x, i)),
+			id: r ?? (i === void 0 ? x : h(x, i)),
 			message: x,
 			...i === void 0 ? {} : { context: i },
 			...o === void 0 ? {} : { comment: o }
-		}, { count: t }, (e, t) => _.t(e, t), b));
+		}, { count: t }, (e, t) => v.t(e, t), b));
 	}
 	async function T({ value: t, id: r, context: a, comment: s, other: c, options: u, ...f }) {
 		let p = await S(), m = u === void 0 ? {
@@ -77,13 +78,13 @@ function y(p) {
 		} : {
 			...u,
 			other: c
-		}, h = [...Object.keys(m).filter((e) => e !== "other"), "other"], { messages: g, components: _ } = e(h, m), y = o(Object.fromEntries([...h].map((e) => [e, g[e] ?? ""]))), b = i(y.forms);
+		}, g = [...Object.keys(m).filter((e) => e !== "other"), "other"], { messages: _, components: v } = e(g, m), y = o(Object.fromEntries([...g].map((e) => [e, _[e] ?? ""]))), b = i(y.forms);
 		return d(l, null, n({
-			id: r ?? (a === void 0 ? b : v(b, a)),
+			id: r ?? (a === void 0 ? b : h(b, a)),
 			message: b,
 			...a === void 0 ? {} : { context: a },
 			...s === void 0 ? {} : { comment: s }
-		}, { value: y.valueMap[t] ?? "other" }, (e, t) => p.t(e, t), _));
+		}, { value: y.valueMap[t] ?? "other" }, (e, t) => p.t(e, t), v));
 	}
 	async function E({ value: e, format: t }) {
 		return d(l, null, (await S()).d(e, t));
@@ -94,8 +95,8 @@ function y(p) {
 	function O() {
 		let e = m();
 		if (e.instance) return e.instance;
-		if (g && y === _) return g;
-		let t = e.locale ?? p.fallbackLocale ?? "en", n = h(), r = {}, i = n.get(t);
+		if (_ && y === v) return _;
+		let t = e.locale ?? p.fallbackLocale ?? "en", n = g(), r = {}, i = n.get(t);
 		if (i && (r[t] = i), p.fallbackLocale && p.fallbackLocale !== t) {
 			let e = n.get(p.fallbackLocale);
 			e && (r[p.fallbackLocale] = e);
@@ -104,7 +105,7 @@ function y(p) {
 			locale: t,
 			messages: r
 		};
-		return p.fallbackLocale !== void 0 && (a.fallbackLocale = p.fallbackLocale), p.fallbackChain !== void 0 && (a.fallbackChain = p.fallbackChain), p.dateFormats !== void 0 && (a.dateFormats = p.dateFormats), p.numberFormats !== void 0 && (a.numberFormats = p.numberFormats), p.missing !== void 0 && (a.missing = p.missing), e.instance = f(a), e.instance;
+		return p.fallbackLocale !== void 0 && (a.fallbackLocale = p.fallbackLocale), p.fallbackChain !== void 0 && (a.fallbackChain = p.fallbackChain), p.dateFormats !== void 0 && (a.dateFormats = p.dateFormats), p.numberFormats !== void 0 && (a.numberFormats = p.numberFormats), p.missing !== void 0 && (a.missing = p.missing), p.interpolate !== void 0 && (a.interpolate = p.interpolate), e.instance = f(a), e.instance;
 	}
 	async function k(e, t) {
 		let n = await S();
@@ -128,6 +129,6 @@ function y(p) {
 	};
 }
 //#endregion
-export { y as createServerI18n, p as detectLocale, m as getDirection, h as getHydratedLocale, g as getSSRLocaleScript, _ as isRTL };
+export { y as createServerI18n, g as detectLocale, p as getDirection, _ as getHydratedLocale, v as getSSRLocaleScript, m as isRTL };
 
 //# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","names":[],"sources":["../src/server.ts"],"sourcesContent":["import { cache } from 'react'\nimport { createFluentiCore } from '@fluenti/core'\nimport type {\n  FluentiCoreInstanceFull,\n  FluentiCoreConfigFull,\n  Locale,\n  Messages,\n  DateFormatOptions,\n  NumberFormatOptions,\n} from '@fluenti/core'\nimport { hashMessage as hashSyntheticMessage } from '@fluenti/core/internal'\nimport { createElement, Fragment, type ReactNode, type ReactElement } from 'react'\nimport { hashMessage, extractMessage, reconstruct } from './components/trans-core'\nimport { PLURAL_CATEGORIES, type PluralCategory } from './components/plural-core'\nimport { buildICUPluralMessage, buildICUSelectMessage, normalizeSelectForms, renderRichTranslation, serializeRichForms } from './components/icu-rich'\n\n// Re-export SSR utilities from core for convenience\nexport { detectLocale, getSSRLocaleScript, getHydratedLocale, isRTL, getDirection } from '@fluenti/core'\nexport type { DetectLocaleOptions } from '@fluenti/core'\n\n/**\n * Configuration for `createServerI18n`.\n */\nexport interface ServerI18nConfig {\n  /** Load messages for a given locale. Called once per locale per request. */\n  loadMessages: (locale: string) => Promise<Messages | { default: Messages }>\n  /** Fallback locale when a translation is missing */\n  fallbackLocale?: string\n  /**\n   * Auto-resolve locale when `setLocale()` was not called.\n   *\n   * This is the fallback for contexts where the layout doesn't run — most\n   * notably **Server Actions** (`'use server'`), which are independent\n   * requests that skip the layout tree entirely.\n   *\n   * Common patterns:\n   * - Read from a cookie (Next.js: `cookies().get('locale')`)\n   * - Read from a request header set by middleware\n   * - Query the database for the authenticated user's preference\n   *\n   * If omitted and `setLocale()` was not called, `getI18n()` will throw.\n   *\n   * @example\n   * ```ts\n   * resolveLocale: async () => {\n   *   const { cookies } = await import('next/headers')\n   *   return (await cookies()).get('locale')?.value ?? 'en'\n   * }\n   * ```\n   */\n  resolveLocale?: () => string | Promise<string>\n  /** Custom fallback chains per locale */\n  fallbackChain?: Record<string, Locale[]>\n  /** Custom date format styles */\n  dateFormats?: DateFormatOptions\n  /** Custom number format styles */\n  numberFormats?: NumberFormatOptions\n  /** Handler for missing translation keys */\n  missing?: (locale: Locale, id: string) => string | undefined\n}\n\n// ─── Server Component Props ──────────────────────────────────────────────────\n\nexport interface ServerTransProps {\n  /** Source text with embedded components */\n  children: ReactNode\n  /** Override auto-generated hash ID */\n  id?: string\n  /** Message context used for identity and translator disambiguation */\n  context?: string\n  /** Context comment for translators */\n  comment?: string\n  /** Custom render wrapper */\n  render?: (translation: ReactNode) => ReactNode\n}\n\nexport interface ServerPluralProps {\n  /** The count value */\n  value: number\n  /** Override the auto-generated synthetic ICU message id */\n  id?: string\n  /** Message context used for identity and translator disambiguation */\n  context?: string\n  /** Translator-facing note preserved in extraction catalogs */\n  comment?: string\n  /** Text for zero (if language supports) */\n  zero?: ReactNode\n  /** Singular form. `#` replaced with value */\n  one?: ReactNode\n  /** Dual form (Arabic, etc.) */\n  two?: ReactNode\n  /** Few form (Slavic languages, etc.) */\n  few?: ReactNode\n  /** Many form */\n  many?: ReactNode\n  /** Default plural form */\n  other: ReactNode\n  /** Offset from value before selecting form */\n  offset?: number\n}\n\nexport interface ServerSelectProps {\n  /** The selector value */\n  value: string\n  /** Override the auto-generated synthetic ICU message id */\n  id?: string\n  /** Message context used for identity and translator disambiguation */\n  context?: string\n  /** Translator-facing note preserved in extraction catalogs */\n  comment?: string\n  /** Default case */\n  other: ReactNode\n  /** Type-safe named options. Takes precedence over direct case props. */\n  options?: Record<string, ReactNode>\n  /** Named cases — any string key maps to a ReactNode */\n  [key: string]: ReactNode | Record<string, ReactNode> | string | undefined\n}\n\nexport interface ServerDateTimeProps {\n  /** Date value to format */\n  value: Date | number\n  /** Named format key defined in dateFormats config */\n  format?: string\n}\n\nexport interface ServerNumberProps {\n  /** Number value to format */\n  value: number\n  /** Named format key defined in numberFormats config */\n  format?: string\n}\n\n// ─── Server Component Types ──────────────────────────────────────────────────\n\ntype ServerTransComponent = (props: ServerTransProps) => Promise<ReactElement>\ntype ServerPluralComponent = (props: ServerPluralProps) => Promise<ReactElement>\ntype ServerSelectComponent = (props: ServerSelectProps) => Promise<ReactElement>\ntype ServerDateTimeComponent = (props: ServerDateTimeProps) => Promise<ReactElement>\ntype ServerNumberComponent = (props: ServerNumberProps) => Promise<ReactElement>\n\n/**\n * The object returned by `createServerI18n`.\n */\nexport interface ServerI18n {\n  /**\n   * Set the locale for the current server request.\n   * Call this once in your root layout or page before any `getI18n()` calls.\n   *\n   * Uses `React.cache()` — scoped to the current request automatically.\n   */\n  setLocale: (locale: string) => void\n\n  /**\n   * Get a fully configured i18n instance for the current request.\n   * Messages are loaded lazily and cached per-request.\n   *\n   * @example\n   * ```tsx\n   * // In any Server Component\n   * const { t, d, n, locale } = await getI18n()\n   * return <h1>{t('welcome')}</h1>\n   * ```\n   */\n  getI18n: () => Promise<FluentiCoreInstanceFull & { locale: string }>\n\n  /**\n   * `<Trans>` for React Server Components.\n   * Async component — automatically resolves the i18n instance.\n   *\n   * @example\n   * ```tsx\n   * <Trans>Read the <a href=\"/docs\">documentation</a>.</Trans>\n   * ```\n   */\n  Trans: ServerTransComponent\n\n  /**\n   * `<Plural>` for React Server Components.\n   *\n   * @example\n   * ```tsx\n   * <Plural value={count} one=\"# item\" other=\"# items\" />\n   * ```\n   */\n  Plural: ServerPluralComponent\n\n  /**\n   * `<Select>` for React Server Components.\n   *\n   * @example\n   * ```tsx\n   * <Select value={gender} male=\"He liked this\" other=\"They liked this\" />\n   * ```\n   */\n  Select: ServerSelectComponent\n\n  /**\n   * `<DateTime>` for React Server Components.\n   *\n   * @example\n   * ```tsx\n   * <DateTime value={new Date()} format=\"long\" />\n   * ```\n   */\n  DateTime: ServerDateTimeComponent\n\n  /**\n   * `<NumberFormat>` for React Server Components.\n   *\n   * @example\n   * ```tsx\n   * <NumberFormat value={1234.56} format=\"currency\" />\n   * ```\n   */\n  NumberFormat: ServerNumberComponent\n\n  /**\n   * Check if a translation key exists in the catalog.\n   * Optionally check a specific locale instead of the current one.\n   */\n  te: (key: string, locale?: string) => Promise<boolean>\n\n  /**\n   * Get the raw compiled message without interpolation.\n   * Optionally look up in a specific locale instead of the current one.\n   */\n  tm: (key: string, locale?: string) => Promise<Messages[string] | undefined>\n\n  /**\n   * Synchronous accessor for the cached i18n instance.\n   * Used internally by @fluenti/next webpack loader.\n   * @internal\n   */\n  __getSyncInstance: () => FluentiCoreInstanceFull & { locale: string }\n}\n\n/**\n * Create server-side i18n utilities for React Server Components.\n *\n * Uses `React.cache()` to share state within a single server request\n * without React Context (which is unavailable in Server Components).\n *\n * @example\n * ```ts\n * // lib/i18n.server.ts — define once\n * import { createServerI18n } from '@fluenti/react/server'\n *\n * export const { setLocale, getI18n, Trans, Plural, Select, DateTime, NumberFormat } = createServerI18n({\n *   loadMessages: (locale) => import(`../messages/${locale}.json`),\n *   fallbackLocale: 'en',\n * })\n * ```\n *\n * ```tsx\n * // app/[locale]/layout.tsx — set locale once\n * import { setLocale } from '@/lib/i18n.server'\n *\n * export default async function Layout({ params, children }) {\n *   const { locale } = await params\n *   setLocale(locale)\n *   return <html lang={locale}><body>{children}</body></html>\n * }\n * ```\n *\n * ```tsx\n * // app/[locale]/page.tsx — use Trans, Plural, etc. directly\n * import { Trans, Plural, Select } from '@/lib/i18n.server'\n *\n * export default async function Page() {\n *   return (\n *     <div>\n *       <Trans>Read the <a href=\"/docs\">documentation</a>.</Trans>\n *       <Plural value={5} one=\"# item\" other=\"# items\" />\n *       <Select value=\"male\" male=\"He liked this\" other=\"They liked this\" />\n *     </div>\n *   )\n * }\n * ```\n */\nexport function createServerI18n(config: ServerI18nConfig): ServerI18n {\n  // Request-scoped store using React.cache()\n  // Each server request gets its own isolated state\n  const getRequestStore = cache((): {\n    locale: string | null\n    instance: (FluentiCoreInstanceFull & { locale: string }) | null\n  } => ({\n    locale: null,\n    instance: null,\n  }))\n\n  // Cache loaded messages per-request to avoid redundant imports\n  const getMessageCache = cache((): Map<string, Messages> => new Map())\n\n  // Module-level fallback for server actions where React.cache()\n  // may not share state with the page render.\n  let _lastInstance: (FluentiCoreInstanceFull & { locale: string }) | null = null\n  let _requestId = 0\n  let _lastRequestId = 0\n\n  function setLocale(locale: string): void {\n    getRequestStore().locale = locale\n    _requestId++\n    _lastInstance = null\n  }\n\n  async function loadLocaleMessages(locale: string): Promise<Messages> {\n    const messageCache = getMessageCache()\n    const cached = messageCache.get(locale)\n    if (cached) return cached\n\n    const raw = await config.loadMessages(locale)\n    const messages: Messages =\n      typeof raw === 'object' && raw !== null && 'default' in raw\n        ? (raw as { default: Messages }).default\n        : (raw as Messages)\n\n    messageCache.set(locale, messages)\n    return messages\n  }\n\n  async function getI18n(): Promise<FluentiCoreInstanceFull & { locale: string }> {\n    const store = getRequestStore()\n\n    // If setLocale() was never called (e.g. Server Action — independent request\n    // that skips the layout), try the resolveLocale fallback.\n    if (!store.locale && config.resolveLocale) {\n      store.locale = await config.resolveLocale()\n    }\n\n    const locale = store.locale\n\n    if (!locale) {\n      throw new Error(\n        '[fluenti] No locale set. Call setLocale(locale) in your layout before using getI18n(), ' +\n          'or provide a resolveLocale function in createServerI18n config to auto-detect locale ' +\n          'in Server Actions and other contexts where the layout does not run.',\n      )\n    }\n\n    // Return cached instance if locale hasn't changed\n    if (store.instance && store.instance.locale === locale) {\n      return store.instance\n    }\n\n    // Load messages for current locale (and fallback if configured)\n    const allMessages: Record<string, Messages> = {}\n    allMessages[locale] = await loadLocaleMessages(locale)\n\n    if (config.fallbackLocale && config.fallbackLocale !== locale) {\n      allMessages[config.fallbackLocale] = await loadLocaleMessages(config.fallbackLocale)\n    }\n\n    const fluentConfig: FluentiCoreConfigFull = {\n      locale,\n      messages: allMessages,\n    }\n    if (config.fallbackLocale !== undefined) fluentConfig.fallbackLocale = config.fallbackLocale\n    if (config.fallbackChain !== undefined) fluentConfig.fallbackChain = config.fallbackChain\n    if (config.dateFormats !== undefined) fluentConfig.dateFormats = config.dateFormats\n    if (config.numberFormats !== undefined) fluentConfig.numberFormats = config.numberFormats\n    if (config.missing !== undefined) fluentConfig.missing = config.missing\n\n    store.instance = createFluentiCore(fluentConfig)\n    _lastInstance = store.instance\n    _lastRequestId = _requestId\n    return store.instance\n  }\n\n  // ─── Async Server Components ─────────────────────────────────────────────\n\n  async function Trans({ children, id, context, comment, render }: ServerTransProps): Promise<ReactElement> {\n    const i18n = await getI18n()\n    const { message, components } = extractMessage(children)\n    const messageId = id ?? hashMessage(message, context)\n    const translated = i18n.t({\n      id: messageId,\n      message,\n      ...(context !== undefined ? { context } : {}),\n      ...(comment !== undefined ? { comment } : {}),\n    })\n    const result = reconstruct(translated, components)\n    return createElement(Fragment, null, render ? render(result) : result)\n  }\n\n  async function Plural({\n    value,\n    id,\n    context,\n    comment,\n    zero,\n    one,\n    two,\n    few,\n    many,\n    other,\n    offset,\n  }: ServerPluralProps): Promise<ReactElement> {\n    const i18n = await getI18n()\n    const forms: Record<PluralCategory, ReactNode | undefined> = {\n      zero,\n      one,\n      two,\n      few,\n      many,\n      other,\n    }\n    const { messages, components } = serializeRichForms(PLURAL_CATEGORIES, forms)\n    const icuMessage = buildICUPluralMessage(\n      {\n        ...(messages.zero !== undefined && { zero: messages.zero }),\n        ...(messages.one !== undefined && { one: messages.one }),\n        ...(messages.two !== undefined && { two: messages.two }),\n        ...(messages.few !== undefined && { few: messages.few }),\n        ...(messages.many !== undefined && { many: messages.many }),\n        other: messages.other ?? '',\n      },\n      offset,\n    )\n\n    const result = renderRichTranslation(\n      {\n        id: id ?? (context === undefined ? icuMessage : hashSyntheticMessage(icuMessage, context)),\n        message: icuMessage,\n        ...(context !== undefined ? { context } : {}),\n        ...(comment !== undefined ? { comment } : {}),\n      },\n      { count: value },\n      (descriptor, values) => i18n.t(descriptor, values),\n      components,\n    )\n\n    return createElement(Fragment, null, result)\n  }\n\n  async function Select({\n    value,\n    id,\n    context,\n    comment,\n    other,\n    options,\n    ...cases\n  }: ServerSelectProps): Promise<ReactElement> {\n    const i18n = await getI18n()\n    const forms: Record<string, ReactNode | undefined> = options === undefined\n      ? {\n        ...Object.fromEntries(\n          Object.entries(cases).filter(([key]) => !['value', 'id', 'context', 'comment', 'options', 'other'].includes(key)),\n        ),\n        other,\n      }\n      : {\n        ...options,\n        other,\n      }\n\n    const orderedKeys = [...Object.keys(forms).filter(key => key !== 'other'), 'other'] as const\n    const { messages, components } = serializeRichForms(orderedKeys, forms)\n    const normalized = normalizeSelectForms(\n      Object.fromEntries(\n        [...orderedKeys].map((key) => [key, messages[key] ?? '']),\n      ),\n    )\n    const icuMessage = buildICUSelectMessage(normalized.forms)\n\n    const result = renderRichTranslation(\n      {\n        id: id ?? (context === undefined ? icuMessage : hashSyntheticMessage(icuMessage, context)),\n        message: icuMessage,\n        ...(context !== undefined ? { context } : {}),\n        ...(comment !== undefined ? { comment } : {}),\n      },\n      { value: normalized.valueMap[value] ?? 'other' },\n      (descriptor, values) => i18n.t(descriptor, values),\n      components,\n    )\n\n    return createElement(Fragment, null, result)\n  }\n\n  async function DateTime({ value, format }: ServerDateTimeProps): Promise<ReactElement> {\n    const i18n = await getI18n()\n    return createElement(Fragment, null, i18n.d(value, format))\n  }\n\n  async function NumberFormat({ value, format }: ServerNumberProps): Promise<ReactElement> {\n    const i18n = await getI18n()\n    return createElement(Fragment, null, i18n.n(value, format))\n  }\n\n  /**\n   * Synchronous accessor for the cached i18n instance.\n   * Used by @fluenti/next webpack loader for t`` in RSC.\n   *\n   * Falls back to creating a minimal instance from the message cache when the\n   * React.cache() request store hasn't been populated yet — this handles\n   * Suspense boundaries and streamed components where React.cache() state\n   * may not propagate from the layout render into streamed children.\n   * @internal\n   */\n  function __getSyncInstance(): FluentiCoreInstanceFull & { locale: string } {\n    const store = getRequestStore()\n    if (store.instance) {\n      return store.instance\n    }\n\n    // Module-level fallback for server actions where React.cache()\n    // may not share state across different call contexts.\n    // Only use within the same request (tracked by _requestId).\n    if (_lastInstance && _lastRequestId === _requestId) {\n      return _lastInstance\n    }\n\n    // Final fallback: create instance synchronously with the default locale.\n    // This handles Suspense boundaries and streamed components where\n    // the React.cache store may not have been populated yet.\n    const locale = store.locale ?? config.fallbackLocale ?? 'en'\n    const messageCache = getMessageCache()\n    const messages: Record<string, Messages> = {}\n    const cached = messageCache.get(locale)\n    if (cached) messages[locale] = cached\n    if (config.fallbackLocale && config.fallbackLocale !== locale) {\n      const fallback = messageCache.get(config.fallbackLocale)\n      if (fallback) messages[config.fallbackLocale] = fallback\n    }\n\n    const fluentConfig: FluentiCoreConfigFull = { locale, messages }\n    if (config.fallbackLocale !== undefined) fluentConfig.fallbackLocale = config.fallbackLocale\n    if (config.fallbackChain !== undefined) fluentConfig.fallbackChain = config.fallbackChain\n    if (config.dateFormats !== undefined) fluentConfig.dateFormats = config.dateFormats\n    if (config.numberFormats !== undefined) fluentConfig.numberFormats = config.numberFormats\n    if (config.missing !== undefined) fluentConfig.missing = config.missing\n\n    store.instance = createFluentiCore(fluentConfig)\n    return store.instance\n  }\n\n  /**\n   * Check if a translation key exists in the catalog for the given (or current) locale.\n   * Async because it needs to ensure messages are loaded via getI18n().\n   */\n  async function te(key: string, locale?: string): Promise<boolean> {\n    const i18n = await getI18n()\n    const targetLocale = locale ?? i18n.locale\n    const msgs = await loadLocaleMessages(targetLocale)\n    return msgs[key] !== undefined\n  }\n\n  /**\n   * Get the raw compiled message for the given key without interpolation.\n   * Async because it needs to ensure messages are loaded via getI18n().\n   */\n  async function tm(key: string, locale?: string): Promise<Messages[string] | undefined> {\n    const i18n = await getI18n()\n    const targetLocale = locale ?? i18n.locale\n    const msgs = await loadLocaleMessages(targetLocale)\n    return msgs[key]\n  }\n\n  return { setLocale, getI18n, __getSyncInstance, te, tm, Trans, Plural, Select, DateTime, NumberFormat }\n}\n"],"mappings":"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"}
+{"version":3,"file":"server.js","names":[],"sources":["../src/server.ts"],"sourcesContent":["import { cache } from 'react'\nimport { createFluentiCore } from '@fluenti/core'\nimport type {\n  FluentiCoreInstanceFull,\n  FluentiCoreConfigFull,\n  Locale,\n  Messages,\n  DateFormatOptions,\n  NumberFormatOptions,\n} from '@fluenti/core'\nimport { hashMessage as hashSyntheticMessage } from '@fluenti/core/internal'\nimport { createElement, Fragment, type ReactNode, type ReactElement } from 'react'\nimport { hashMessage, extractMessage, reconstruct } from './components/trans-core'\nimport { PLURAL_CATEGORIES, type PluralCategory } from './components/plural-core'\nimport { buildICUPluralMessage, buildICUSelectMessage, normalizeSelectForms, renderRichTranslation, serializeRichForms } from './components/icu-rich'\n\n// Re-export SSR utilities from core for convenience\nexport { detectLocale, getSSRLocaleScript, getHydratedLocale } from '@fluenti/core/ssr'\nexport type { DetectLocaleOptions } from '@fluenti/core/ssr'\nexport { isRTL, getDirection } from '@fluenti/core'\n\n/**\n * Configuration for `createServerI18n`.\n */\nexport interface ServerI18nConfig {\n  /** Load messages for a given locale. Called once per locale per request. */\n  loadMessages: (locale: string) => Promise<Messages | { default: Messages }>\n  /** Fallback locale when a translation is missing */\n  fallbackLocale?: string\n  /**\n   * Auto-resolve locale when `setLocale()` was not called.\n   *\n   * This is the fallback for contexts where the layout doesn't run — most\n   * notably **Server Actions** (`'use server'`), which are independent\n   * requests that skip the layout tree entirely.\n   *\n   * Common patterns:\n   * - Read from a cookie (Next.js: `cookies().get('locale')`)\n   * - Read from a request header set by middleware\n   * - Query the database for the authenticated user's preference\n   *\n   * If omitted and `setLocale()` was not called, `getI18n()` will throw.\n   *\n   * @example\n   * ```ts\n   * resolveLocale: async () => {\n   *   const { cookies } = await import('next/headers')\n   *   return (await cookies()).get('locale')?.value ?? 'en'\n   * }\n   * ```\n   */\n  resolveLocale?: () => string | Promise<string>\n  /** Custom fallback chains per locale */\n  fallbackChain?: Record<string, Locale[]>\n  /** Custom date format styles */\n  dateFormats?: DateFormatOptions\n  /** Custom number format styles */\n  numberFormats?: NumberFormatOptions\n  /** Handler for missing translation keys */\n  missing?: (locale: Locale, id: string) => string | undefined\n  /**\n   * Custom interpolation function for ICU MessageFormat parsing.\n   *\n   * By default, the runtime uses a lightweight `{key}` replacer.\n   * Pass the full `interpolate` from `@fluenti/core` for runtime\n   * ICU MessageFormat parsing (plurals, selects, nested arguments).\n   *\n   * @example\n   * ```ts\n   * import { interpolate } from '@fluenti/core'\n   * createServerI18n({ interpolate, ... })\n   * ```\n   */\n  interpolate?: FluentiCoreConfigFull['interpolate']\n}\n\n// ─── Server Component Props ──────────────────────────────────────────────────\n\nexport interface ServerTransProps {\n  /** Source text with embedded components */\n  children: ReactNode\n  /** Override auto-generated hash ID */\n  id?: string\n  /** Message context used for identity and translator disambiguation */\n  context?: string\n  /** Context comment for translators */\n  comment?: string\n  /** Custom render wrapper */\n  render?: (translation: ReactNode) => ReactNode\n}\n\nexport interface ServerPluralProps {\n  /** The count value */\n  value: number\n  /** Override the auto-generated synthetic ICU message id */\n  id?: string\n  /** Message context used for identity and translator disambiguation */\n  context?: string\n  /** Translator-facing note preserved in extraction catalogs */\n  comment?: string\n  /** Text for zero (if language supports) */\n  zero?: ReactNode\n  /** Singular form. `#` replaced with value */\n  one?: ReactNode\n  /** Dual form (Arabic, etc.) */\n  two?: ReactNode\n  /** Few form (Slavic languages, etc.) */\n  few?: ReactNode\n  /** Many form */\n  many?: ReactNode\n  /** Default plural form */\n  other: ReactNode\n  /** Offset from value before selecting form */\n  offset?: number\n}\n\nexport interface ServerSelectProps {\n  /** The selector value */\n  value: string\n  /** Override the auto-generated synthetic ICU message id */\n  id?: string\n  /** Message context used for identity and translator disambiguation */\n  context?: string\n  /** Translator-facing note preserved in extraction catalogs */\n  comment?: string\n  /** Default case */\n  other: ReactNode\n  /** Type-safe named options. Takes precedence over direct case props. */\n  options?: Record<string, ReactNode>\n  /** Named cases — any string key maps to a ReactNode */\n  [key: string]: ReactNode | Record<string, ReactNode> | string | undefined\n}\n\nexport interface ServerDateTimeProps {\n  /** Date value to format */\n  value: Date | number\n  /** Named format key defined in dateFormats config */\n  format?: string\n}\n\nexport interface ServerNumberProps {\n  /** Number value to format */\n  value: number\n  /** Named format key defined in numberFormats config */\n  format?: string\n}\n\n// ─── Server Component Types ──────────────────────────────────────────────────\n\ntype ServerTransComponent = (props: ServerTransProps) => Promise<ReactElement>\ntype ServerPluralComponent = (props: ServerPluralProps) => Promise<ReactElement>\ntype ServerSelectComponent = (props: ServerSelectProps) => Promise<ReactElement>\ntype ServerDateTimeComponent = (props: ServerDateTimeProps) => Promise<ReactElement>\ntype ServerNumberComponent = (props: ServerNumberProps) => Promise<ReactElement>\n\n/**\n * The object returned by `createServerI18n`.\n */\nexport interface ServerI18n {\n  /**\n   * Set the locale for the current server request.\n   * Call this once in your root layout or page before any `getI18n()` calls.\n   *\n   * Uses `React.cache()` — scoped to the current request automatically.\n   */\n  setLocale: (locale: string) => void\n\n  /**\n   * Get a fully configured i18n instance for the current request.\n   * Messages are loaded lazily and cached per-request.\n   *\n   * @example\n   * ```tsx\n   * // In any Server Component\n   * const { t, d, n, locale } = await getI18n()\n   * return <h1>{t('welcome')}</h1>\n   * ```\n   */\n  getI18n: () => Promise<FluentiCoreInstanceFull & { locale: string }>\n\n  /**\n   * `<Trans>` for React Server Components.\n   * Async component — automatically resolves the i18n instance.\n   *\n   * @example\n   * ```tsx\n   * <Trans>Read the <a href=\"/docs\">documentation</a>.</Trans>\n   * ```\n   */\n  Trans: ServerTransComponent\n\n  /**\n   * `<Plural>` for React Server Components.\n   *\n   * @example\n   * ```tsx\n   * <Plural value={count} one=\"# item\" other=\"# items\" />\n   * ```\n   */\n  Plural: ServerPluralComponent\n\n  /**\n   * `<Select>` for React Server Components.\n   *\n   * @example\n   * ```tsx\n   * <Select value={gender} male=\"He liked this\" other=\"They liked this\" />\n   * ```\n   */\n  Select: ServerSelectComponent\n\n  /**\n   * `<DateTime>` for React Server Components.\n   *\n   * @example\n   * ```tsx\n   * <DateTime value={new Date()} format=\"long\" />\n   * ```\n   */\n  DateTime: ServerDateTimeComponent\n\n  /**\n   * `<NumberFormat>` for React Server Components.\n   *\n   * @example\n   * ```tsx\n   * <NumberFormat value={1234.56} format=\"currency\" />\n   * ```\n   */\n  NumberFormat: ServerNumberComponent\n\n  /**\n   * Check if a translation key exists in the catalog.\n   * Optionally check a specific locale instead of the current one.\n   */\n  te: (key: string, locale?: string) => Promise<boolean>\n\n  /**\n   * Get the raw compiled message without interpolation.\n   * Optionally look up in a specific locale instead of the current one.\n   */\n  tm: (key: string, locale?: string) => Promise<Messages[string] | undefined>\n\n  /**\n   * Synchronous accessor for the cached i18n instance.\n   * Used internally by @fluenti/next webpack loader.\n   * @internal\n   */\n  __getSyncInstance: () => FluentiCoreInstanceFull & { locale: string }\n}\n\n/**\n * Create server-side i18n utilities for React Server Components.\n *\n * Uses `React.cache()` to share state within a single server request\n * without React Context (which is unavailable in Server Components).\n *\n * @example\n * ```ts\n * // lib/i18n.server.ts — define once\n * import { createServerI18n } from '@fluenti/react/server'\n *\n * export const { setLocale, getI18n, Trans, Plural, Select, DateTime, NumberFormat } = createServerI18n({\n *   loadMessages: (locale) => import(`../messages/${locale}.json`),\n *   fallbackLocale: 'en',\n * })\n * ```\n *\n * ```tsx\n * // app/[locale]/layout.tsx — set locale once\n * import { setLocale } from '@/lib/i18n.server'\n *\n * export default async function Layout({ params, children }) {\n *   const { locale } = await params\n *   setLocale(locale)\n *   return <html lang={locale}><body>{children}</body></html>\n * }\n * ```\n *\n * ```tsx\n * // app/[locale]/page.tsx — use Trans, Plural, etc. directly\n * import { Trans, Plural, Select } from '@/lib/i18n.server'\n *\n * export default async function Page() {\n *   return (\n *     <div>\n *       <Trans>Read the <a href=\"/docs\">documentation</a>.</Trans>\n *       <Plural value={5} one=\"# item\" other=\"# items\" />\n *       <Select value=\"male\" male=\"He liked this\" other=\"They liked this\" />\n *     </div>\n *   )\n * }\n * ```\n */\nexport function createServerI18n(config: ServerI18nConfig): ServerI18n {\n  // Request-scoped store using React.cache()\n  // Each server request gets its own isolated state\n  const getRequestStore = cache((): {\n    locale: string | null\n    instance: (FluentiCoreInstanceFull & { locale: string }) | null\n  } => ({\n    locale: null,\n    instance: null,\n  }))\n\n  // Cache loaded messages per-request to avoid redundant imports\n  const getMessageCache = cache((): Map<string, Messages> => new Map())\n\n  // Module-level fallback for server actions where React.cache()\n  // may not share state with the page render.\n  let _lastInstance: (FluentiCoreInstanceFull & { locale: string }) | null = null\n  let _requestId = 0\n  let _lastRequestId = 0\n\n  function setLocale(locale: string): void {\n    getRequestStore().locale = locale\n    _requestId++\n    _lastInstance = null\n  }\n\n  async function loadLocaleMessages(locale: string): Promise<Messages> {\n    const messageCache = getMessageCache()\n    const cached = messageCache.get(locale)\n    if (cached) return cached\n\n    const raw = await config.loadMessages(locale)\n    const messages: Messages =\n      typeof raw === 'object' && raw !== null && 'default' in raw\n        ? (raw as { default: Messages }).default\n        : (raw as Messages)\n\n    messageCache.set(locale, messages)\n    return messages\n  }\n\n  async function getI18n(): Promise<FluentiCoreInstanceFull & { locale: string }> {\n    const store = getRequestStore()\n\n    // If setLocale() was never called (e.g. Server Action — independent request\n    // that skips the layout), try the resolveLocale fallback.\n    if (!store.locale && config.resolveLocale) {\n      store.locale = await config.resolveLocale()\n    }\n\n    const locale = store.locale\n\n    if (!locale) {\n      throw new Error(\n        '[fluenti] No locale set. Call setLocale(locale) in your layout before using getI18n(), ' +\n          'or provide a resolveLocale function in createServerI18n config to auto-detect locale ' +\n          'in Server Actions and other contexts where the layout does not run.',\n      )\n    }\n\n    // Return cached instance if locale hasn't changed\n    if (store.instance && store.instance.locale === locale) {\n      return store.instance\n    }\n\n    // Load messages for current locale (and fallback if configured)\n    const allMessages: Record<string, Messages> = {}\n    allMessages[locale] = await loadLocaleMessages(locale)\n\n    if (config.fallbackLocale && config.fallbackLocale !== locale) {\n      allMessages[config.fallbackLocale] = await loadLocaleMessages(config.fallbackLocale)\n    }\n\n    const fluentConfig: FluentiCoreConfigFull = {\n      locale,\n      messages: allMessages,\n    }\n    if (config.fallbackLocale !== undefined) fluentConfig.fallbackLocale = config.fallbackLocale\n    if (config.fallbackChain !== undefined) fluentConfig.fallbackChain = config.fallbackChain\n    if (config.dateFormats !== undefined) fluentConfig.dateFormats = config.dateFormats\n    if (config.numberFormats !== undefined) fluentConfig.numberFormats = config.numberFormats\n    if (config.missing !== undefined) fluentConfig.missing = config.missing\n    if (config.interpolate !== undefined) fluentConfig.interpolate = config.interpolate\n\n    store.instance = createFluentiCore(fluentConfig)\n    _lastInstance = store.instance\n    _lastRequestId = _requestId\n    return store.instance\n  }\n\n  // ─── Async Server Components ─────────────────────────────────────────────\n\n  async function Trans({ children, id, context, comment, render }: ServerTransProps): Promise<ReactElement> {\n    const i18n = await getI18n()\n    const { message, components } = extractMessage(children)\n    const messageId = id ?? hashMessage(message, context)\n    const translated = i18n.t({\n      id: messageId,\n      message,\n      ...(context !== undefined ? { context } : {}),\n      ...(comment !== undefined ? { comment } : {}),\n    })\n    const result = reconstruct(translated, components)\n    return createElement(Fragment, null, render ? render(result) : result)\n  }\n\n  async function Plural({\n    value,\n    id,\n    context,\n    comment,\n    zero,\n    one,\n    two,\n    few,\n    many,\n    other,\n    offset,\n  }: ServerPluralProps): Promise<ReactElement> {\n    const i18n = await getI18n()\n    const forms: Record<PluralCategory, ReactNode | undefined> = {\n      zero,\n      one,\n      two,\n      few,\n      many,\n      other,\n    }\n    const { messages, components } = serializeRichForms(PLURAL_CATEGORIES, forms)\n    const icuMessage = buildICUPluralMessage(\n      {\n        ...(messages.zero !== undefined && { zero: messages.zero }),\n        ...(messages.one !== undefined && { one: messages.one }),\n        ...(messages.two !== undefined && { two: messages.two }),\n        ...(messages.few !== undefined && { few: messages.few }),\n        ...(messages.many !== undefined && { many: messages.many }),\n        other: messages.other ?? '',\n      },\n      offset,\n    )\n\n    const result = renderRichTranslation(\n      {\n        id: id ?? (context === undefined ? icuMessage : hashSyntheticMessage(icuMessage, context)),\n        message: icuMessage,\n        ...(context !== undefined ? { context } : {}),\n        ...(comment !== undefined ? { comment } : {}),\n      },\n      { count: value },\n      (descriptor, values) => i18n.t(descriptor, values),\n      components,\n    )\n\n    return createElement(Fragment, null, result)\n  }\n\n  async function Select({\n    value,\n    id,\n    context,\n    comment,\n    other,\n    options,\n    ...cases\n  }: ServerSelectProps): Promise<ReactElement> {\n    const i18n = await getI18n()\n    const forms: Record<string, ReactNode | undefined> = options === undefined\n      ? {\n        ...Object.fromEntries(\n          Object.entries(cases).filter(([key]) => !['value', 'id', 'context', 'comment', 'options', 'other'].includes(key)),\n        ),\n        other,\n      }\n      : {\n        ...options,\n        other,\n      }\n\n    const orderedKeys = [...Object.keys(forms).filter(key => key !== 'other'), 'other'] as const\n    const { messages, components } = serializeRichForms(orderedKeys, forms)\n    const normalized = normalizeSelectForms(\n      Object.fromEntries(\n        [...orderedKeys].map((key) => [key, messages[key] ?? '']),\n      ),\n    )\n    const icuMessage = buildICUSelectMessage(normalized.forms)\n\n    const result = renderRichTranslation(\n      {\n        id: id ?? (context === undefined ? icuMessage : hashSyntheticMessage(icuMessage, context)),\n        message: icuMessage,\n        ...(context !== undefined ? { context } : {}),\n        ...(comment !== undefined ? { comment } : {}),\n      },\n      { value: normalized.valueMap[value] ?? 'other' },\n      (descriptor, values) => i18n.t(descriptor, values),\n      components,\n    )\n\n    return createElement(Fragment, null, result)\n  }\n\n  async function DateTime({ value, format }: ServerDateTimeProps): Promise<ReactElement> {\n    const i18n = await getI18n()\n    return createElement(Fragment, null, i18n.d(value, format))\n  }\n\n  async function NumberFormat({ value, format }: ServerNumberProps): Promise<ReactElement> {\n    const i18n = await getI18n()\n    return createElement(Fragment, null, i18n.n(value, format))\n  }\n\n  /**\n   * Synchronous accessor for the cached i18n instance.\n   * Used by @fluenti/next webpack loader for t`` in RSC.\n   *\n   * Falls back to creating a minimal instance from the message cache when the\n   * React.cache() request store hasn't been populated yet — this handles\n   * Suspense boundaries and streamed components where React.cache() state\n   * may not propagate from the layout render into streamed children.\n   * @internal\n   */\n  function __getSyncInstance(): FluentiCoreInstanceFull & { locale: string } {\n    const store = getRequestStore()\n    if (store.instance) {\n      return store.instance\n    }\n\n    // Module-level fallback for server actions where React.cache()\n    // may not share state across different call contexts.\n    // Only use within the same request (tracked by _requestId).\n    if (_lastInstance && _lastRequestId === _requestId) {\n      return _lastInstance\n    }\n\n    // Final fallback: create instance synchronously with the default locale.\n    // This handles Suspense boundaries and streamed components where\n    // the React.cache store may not have been populated yet.\n    const locale = store.locale ?? config.fallbackLocale ?? 'en'\n    const messageCache = getMessageCache()\n    const messages: Record<string, Messages> = {}\n    const cached = messageCache.get(locale)\n    if (cached) messages[locale] = cached\n    if (config.fallbackLocale && config.fallbackLocale !== locale) {\n      const fallback = messageCache.get(config.fallbackLocale)\n      if (fallback) messages[config.fallbackLocale] = fallback\n    }\n\n    const fluentConfig: FluentiCoreConfigFull = { locale, messages }\n    if (config.fallbackLocale !== undefined) fluentConfig.fallbackLocale = config.fallbackLocale\n    if (config.fallbackChain !== undefined) fluentConfig.fallbackChain = config.fallbackChain\n    if (config.dateFormats !== undefined) fluentConfig.dateFormats = config.dateFormats\n    if (config.numberFormats !== undefined) fluentConfig.numberFormats = config.numberFormats\n    if (config.missing !== undefined) fluentConfig.missing = config.missing\n    if (config.interpolate !== undefined) fluentConfig.interpolate = config.interpolate\n\n    store.instance = createFluentiCore(fluentConfig)\n    return store.instance\n  }\n\n  /**\n   * Check if a translation key exists in the catalog for the given (or current) locale.\n   * Async because it needs to ensure messages are loaded via getI18n().\n   */\n  async function te(key: string, locale?: string): Promise<boolean> {\n    const i18n = await getI18n()\n    const targetLocale = locale ?? i18n.locale\n    const msgs = await loadLocaleMessages(targetLocale)\n    return msgs[key] !== undefined\n  }\n\n  /**\n   * Get the raw compiled message for the given key without interpolation.\n   * Async because it needs to ensure messages are loaded via getI18n().\n   */\n  async function tm(key: string, locale?: string): Promise<Messages[string] | undefined> {\n    const i18n = await getI18n()\n    const targetLocale = locale ?? i18n.locale\n    const msgs = await loadLocaleMessages(targetLocale)\n    return msgs[key]\n  }\n\n  return { setLocale, getI18n, __getSyncInstance, te, tm, Trans, Plural, Select, DateTime, NumberFormat }\n}\n"],"mappings":"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"}

package/dist/types.d.ts

@@ -52,6 +52,11 @@ export interface I18nProviderProps {
     missing?: (locale: Locale, id: string) => string | undefined;
     /** Runtime diagnostics configuration */
     diagnostics?: DiagnosticsConfig;
+    /**
+     * Custom message interpolation function.
+     * Pass `interpolate` from `@fluenti/core/internal` for full ICU support at runtime.
+     */
+    interpolate?: (message: string, values: Record<string, unknown> | undefined, locale: string, formatters?: Record<string, unknown>) => string;
     /** App content */
     children: ReactNode;
     /** Pre-created FluentiInstance (alternative to inline config) */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/llms-full.txt

@@ -118,7 +118,8 @@ Cross-framework contract highlights:
 ## Example
 
 ```tsx
-import { I18nProvider, t, useI18n, Trans, Plural, Select } from '@fluenti/react'
+import { I18nProvider, t, useI18n } from '@fluenti/react'
+import { Trans, Plural, Select } from '@fluenti/react/components'
 
 function Home() {
   const name = 'Fluenti'

package/llms-migration.txt

@@ -78,7 +78,7 @@ import { Trans } from 'react-i18next'
 
 After (Fluenti):
 ```tsx
-import { Trans } from '@fluenti/react'
+import { Trans } from '@fluenti/react/components'
 <Trans message="Welcome to {0}our app{1}">
   {(text) => <strong>{text}</strong>}
 </Trans>
@@ -182,7 +182,7 @@ import { FormattedMessage, FormattedDate, FormattedNumber } from 'react-intl'
 
 After (Fluenti):
 ```tsx
-import { Trans, DateTime, NumberFormat } from '@fluenti/react'
+import { Trans, DateTime, NumberFormat } from '@fluenti/react/components'
 <Trans message="Hello, {name}!" values={{ name: 'World' }} />
 <DateTime value={date} style="long" />
 <NumberFormat value={1234} style="decimal" />

package/llms.txt

@@ -52,6 +52,67 @@ Server entry (`@fluenti/react/server`):
 
 ❌ AVOID: `t('some.key')` as the default — this is a legacy i18n pattern.
 
+## Code Examples — React
+
+### Tagged template (PREFERRED)
+
+```tsx
+import { useI18n } from '@fluenti/react'
+
+function MyComponent() {
+  const { t } = useI18n()
+
+  return (
+    <div>
+      <h1>{t\`Welcome to our app\`}</h1>
+      <p>{t\`Hello, ${name}!\`}</p>
+      <p>{t\`You have ${count} unread messages\`}</p>
+    </div>
+  )
+}
+```
+
+### Rich text with \<Trans\>
+
+```tsx
+import { Trans } from '@fluenti/react/components'
+
+function Terms() {
+  return (
+    <Trans>
+      Read our <a href="/terms">terms of service</a>
+    </Trans>
+  )
+}
+```
+
+### Plurals
+
+```tsx
+import { Plural } from '@fluenti/react/components'
+
+function ItemCount({ count }: { count: number }) {
+  return (
+    <Plural
+      value={count}
+      one="# item in cart"
+      other="# items in cart"
+    />
+  )
+}
+```
+
+### What NOT to write
+
+❌ Do not use t() with manual key strings:
+```tsx
+// WRONG
+const msg = t('welcome_message', { name })
+
+// CORRECT
+const msg = t\`Welcome, ${name}!\`
+```
+
 ## Lazy locale loading
 
 React uses `loadMessages(locale)` on `I18nProvider` for async locale chunks.