@fluenti/next 0.2.0 → 0.3.0

package/llms-full.txt

@@ -0,0 +1,122 @@
+# @fluenti/next
+
+> Next.js integration for Fluenti — `withFluenti()`, strict compile-time transforms, and generated server runtime helpers.
+
+@fluenti/next integrates Fluenti into Next.js projects. Its job is to:
+
+- wrap `next.config` with `withFluenti()`
+- install the Fluenti loader
+- generate the internal server runtime module consumed as `@fluenti/next`
+- keep Next authoring aligned with the main React authoring surface
+
+## Install
+
+```bash
+pnpm add @fluenti/core @fluenti/react @fluenti/next
+```
+
+## Main public entry
+
+```ts
+import { withFluenti } from '@fluenti/next'
+
+export default withFluenti()({
+  reactStrictMode: true,
+})
+```
+
+### `withFluenti(config?)`
+
+Supports:
+
+- `withFluenti(fluentiConfig?)(nextConfig)`
+- `withFluenti(nextConfig)`
+
+Public config fields:
+
+- `locales`
+- `defaultLocale`
+- `compiledDir`
+- `serverModule`
+- `serverModuleOutDir`
+- `resolveLocale`
+- `dateFormats`
+- `numberFormats`
+- `fallbackChain`
+
+## Authoring model in Next
+
+In a `withFluenti()` project, the recommended authoring surface is:
+
+```tsx
+// ✅ Preferred: compile-time authoring surface
+import { t, Trans, Plural, Select, DateTime, NumberFormat } from '@fluenti/react'
+```
+
+This applies to both client and server authoring.
+
+For runtime and integration concerns, use the generated module:
+
+```ts
+import { I18nProvider, getI18n, setLocale } from '@fluenti/next'
+```
+
+### Important boundaries
+
+- imported `t` is compile-time only — ✅ this is the preferred API
+- client and server authoring should stay on `@fluenti/react`
+- server runtime access should use `await getI18n()` — ⚠️ runtime fallback for dynamic keys
+- direct-import server `t` requires an async server scope
+
+## What `withFluenti()` does
+
+1. resolves Fluenti config from `fluenti.config.ts` and explicit overrides
+2. generates a server module under the configured output directory
+3. aliases that generated module as `@fluenti/next`
+4. runs the loader on app code so official authoring APIs are transformed correctly
+
+## Generated runtime module
+
+`@fluenti/next` is not a hand-authored package entry. It is a generated module created by `withFluenti()`.
+
+It provides:
+
+- `I18nProvider`
+- `setLocale`
+- `getI18n`
+- compile-time `t` stub
+- server-side `Trans`
+- server-side `Plural`
+- server-side `Select`
+- server-side `DateTime`
+- server-side `NumberFormat`
+
+### `I18nProvider`
+
+Use in root layouts to initialize server and client runtime state.
+
+### `getI18n()`
+
+Use in server components, route handlers, metadata functions, and server actions when you need the full runtime API.
+
+### `setLocale()`
+
+Sets the request locale for the generated server runtime.
+
+## Public package subpaths
+
+- `@fluenti/next` — config wrapper and types
+- `@fluenti/next/server` — server-side helpers exported by the package itself
+- `@fluenti/next/provider` — provider-related types/helpers
+- `@fluenti/next/client` — client-side type declarations
+
+`@fluenti/next` is created per project by `withFluenti()`.
+
+## Relationship to `@fluenti/react`
+
+`@fluenti/next` builds on `@fluenti/react`.
+
+- authoring surface: `@fluenti/react`
+- Next-specific runtime integration: `@fluenti/next` + generated module
+
+This keeps the main mental model aligned across React SPA, Vite, and Next.

package/llms-migration.txt

@@ -0,0 +1,262 @@
+# Migrating to @fluenti/next from next-intl / next-i18next
+
+> Step-by-step guide to migrate a Next.js app from next-intl or next-i18next to Fluenti.
+
+## Overview
+
+Fluenti is a **compile-time** i18n library — translations are compiled to optimized JS at build time. next-intl and next-i18next are runtime libraries. Fluenti's Next.js plugin provides webpack loader integration, React Server Component support, and zero-overhead compiled messages.
+
+Key differences:
+- Compile-time compilation vs runtime message parsing
+- ICU MessageFormat (same as next-intl, different from next-i18next)
+- Webpack loader for build-time `t` tag transforms
+- PO or JSON catalogs managed by CLI
+- RSC-native with server and client component support
+
+---
+
+## Migrating from next-intl
+
+### 1. Install Fluenti
+
+```bash
+pnpm add @fluenti/core @fluenti/react @fluenti/next
+pnpm add -D @fluenti/cli
+```
+
+### 2. Update Next.js config
+
+Before (next-intl):
+```ts
+// next.config.ts
+import createNextIntlPlugin from 'next-intl/plugin'
+const withNextIntl = createNextIntlPlugin()
+export default withNextIntl({ /* next config */ })
+```
+
+After (Fluenti):
+```ts
+// next.config.ts
+import { withFluenti } from '@fluenti/next'
+export default withFluenti({ /* next config */ })
+```
+
+### 3. Replace provider
+
+Before (next-intl):
+```tsx
+// app/[locale]/layout.tsx
+import { NextIntlClientProvider } from 'next-intl'
+import { getMessages } from 'next-intl/server'
+
+export default async function Layout({ children, params }) {
+  const messages = await getMessages()
+  return (
+    <NextIntlClientProvider messages={messages}>
+      {children}
+    </NextIntlClientProvider>
+  )
+}
+```
+
+After (Fluenti):
+```tsx
+// app/[locale]/layout.tsx
+import { I18nProvider } from '@fluenti/react'
+import en from '@/locales/compiled/en'
+
+export default function Layout({ children, params }) {
+  return (
+    <I18nProvider locale={params.locale} fallbackLocale="en" messages={{ en }}>
+      {children}
+    </I18nProvider>
+  )
+}
+```
+
+### 4. Update usage in components
+
+Before (next-intl):
+```tsx
+import { useTranslations } from 'next-intl'
+const t = useTranslations('namespace')
+t('hello', { name: 'World' })
+```
+
+After (Fluenti):
+```tsx
+import { useI18n } from '@fluenti/react'
+const { i18n } = useI18n()
+i18n.t('hello', { name: 'World' })
+```
+
+### 5. Server components
+
+Before (next-intl):
+```tsx
+import { getTranslations } from 'next-intl/server'
+const t = await getTranslations('namespace')
+```
+
+After (Fluenti):
+```tsx
+import { createServerI18n } from '@fluenti/react/server'
+const i18n = createServerI18n({ locale: 'en', messages: { en } })
+i18n.t('hello')
+```
+
+### API Mapping: next-intl → Fluenti
+
+| next-intl | Fluenti |
+|-----------|---------|
+| `useTranslations()` | `useI18n()` |
+| `t(key, values)` | `i18n.t(key, values)` |
+| `t.rich(key, { bold: (text) => ... })` | `<Trans>` component |
+| `useFormatter()` | `i18n.d()`, `i18n.n()` |
+| `<NextIntlClientProvider>` | `<I18nProvider>` |
+| `getTranslations()` (server) | `createServerI18n()` |
+| `getMessages()` (server) | Import compiled messages directly |
+| `createNextIntlPlugin()` | `withFluenti()` |
+| Namespace-based `t('ns.key')` | Flat key `i18n.t('key')` |
+| ICU MessageFormat | ICU MessageFormat (compatible) |
+
+---
+
+## Migrating from next-i18next
+
+### 1. Install Fluenti
+
+```bash
+pnpm add @fluenti/core @fluenti/react @fluenti/next
+pnpm add -D @fluenti/cli
+```
+
+### 2. Update Next.js config
+
+Before (next-i18next):
+```ts
+// next.config.js
+const { i18n } = require('./next-i18next.config')
+module.exports = { i18n }
+```
+
+After (Fluenti):
+```ts
+// next.config.ts
+import { withFluenti } from '@fluenti/next'
+export default withFluenti({})
+```
+
+### 3. Remove next-i18next.config.js
+
+The old config file is no longer needed. Create a Fluenti config instead:
+
+```ts
+// fluenti.config.ts
+export default {
+  sourceLocale: 'en',
+  locales: ['en', 'ja'],
+  catalogDir: './locales',
+  format: 'po',
+  include: ['./src/**/*.{tsx,jsx,ts,js}', './app/**/*.{tsx,jsx,ts,js}'],
+  compileOutDir: './locales/compiled',
+}
+```
+
+### 4. Replace serverSideTranslations
+
+Before (next-i18next):
+```tsx
+import { serverSideTranslations } from 'next-i18next/serverSideTranslations'
+
+export async function getStaticProps({ locale }) {
+  return { props: { ...(await serverSideTranslations(locale, ['common'])) } }
+}
+```
+
+After (Fluenti — App Router):
+```tsx
+// No getStaticProps needed — messages are compiled and imported directly
+import { I18nProvider } from '@fluenti/react'
+import en from '@/locales/compiled/en'
+```
+
+### 5. Update hook usage
+
+Before (next-i18next):
+```tsx
+import { useTranslation } from 'next-i18next'
+const { t, i18n } = useTranslation('common')
+t('hello', { name: 'World' })
+```
+
+After (Fluenti):
+```tsx
+import { useI18n } from '@fluenti/react'
+const { i18n } = useI18n()
+i18n.t('hello', { name: 'World' })
+```
+
+### 6. Convert message syntax
+
+next-i18next interpolation → ICU:
+```
+# next-i18next (i18next syntax)
+"hello": "Hello, {{name}}!"
+"items": "{{count}} item"
+"items_plural": "{{count}} items"
+
+# Fluenti (ICU MessageFormat)
+"hello": "Hello, {name}!"
+"items": "{count, plural, one {{count} item} other {{count} items}}"
+```
+
+### API Mapping: next-i18next → Fluenti
+
+| next-i18next | Fluenti |
+|--------------|---------|
+| `useTranslation()` | `useI18n()` |
+| `t(key, options)` | `i18n.t(key, values)` |
+| `i18n.changeLanguage()` | `setLocale()` |
+| `serverSideTranslations()` | Import compiled messages directly |
+| `<Trans>` (react-i18next) | `<Trans>` (@fluenti/react) |
+| `appWithTranslation()` HOC | `<I18nProvider>` |
+| `next-i18next.config.js` | `fluenti.config.ts` |
+| `{{var}}` interpolation | `{var}` interpolation |
+| `_plural` suffix | ICU `{n, plural, ...}` |
+| Namespaces | Flat message IDs |
+| `/public/locales/` JSON files | PO/JSON catalogs in `./locales/` |
+
+---
+
+## Common Steps
+
+### Extract and compile catalogs
+
+```bash
+npx fluenti extract    # Extract messages from source
+npx fluenti compile    # Compile to JS modules
+```
+
+### Locale routing
+
+For App Router, use `[locale]` dynamic segment in your route structure:
+
+```
+app/
+  [locale]/
+    layout.tsx    ← I18nProvider here
+    page.tsx
+    about/
+      page.tsx
+```
+
+## Key Behavioral Differences
+
+1. **Compile-time** — no runtime parser, messages are pre-compiled JS functions
+2. **No namespaces** — flat message IDs instead of namespace-based organization
+3. **No serverSideTranslations** — compiled messages imported directly, no serialization needed
+4. **ICU MessageFormat** — standard format for plurals, selects, formatting
+5. **PO file support** — compatible with Poedit, Crowdin, Weblate
+6. **Webpack loader** — transforms `t` tagged templates at build time
+7. **AI translation** — `npx fluenti translate --provider claude` for automated translation

package/llms.txt

@@ -0,0 +1,55 @@
+# @fluenti/next
+
+> Next.js integration for Fluenti — `withFluenti()`, strict compile-time transforms, and generated server runtime helpers.
+
+`@fluenti/next` wires Fluenti into Next.js. In a `withFluenti()` project, the recommended authoring path is:
+
+- client and server authoring: `import { t, Trans, Plural, Select, DateTime, NumberFormat } from '@fluenti/react'`
+- Next runtime/integration: `I18nProvider`, `getI18n()`, and `setLocale()` from `@fluenti/next`
+
+## Install
+
+```bash
+pnpm add @fluenti/core @fluenti/react @fluenti/next
+```
+
+## Main Exports
+
+Main entry (`@fluenti/next`) — resolved at runtime to the generated server module:
+
+- `withFluenti(config?)` — Next.js config wrapper (build-time only)
+- `I18nProvider` — async server component for layouts
+- `t` — compile-time authoring API
+- `Trans`, `Plural`, `Select`, `DateTime`, `NumberFormat` — RSC components
+- `getI18n()` — async server-side i18n instance access
+- `setLocale(locale)` — set locale in the async local storage scope
+
+Server entry (`@fluenti/next/server`):
+
+- `withLocale(locale, fn)` — run a function with a specific locale in RSC context
+
+Provider entry (`@fluenti/next/provider`):
+
+- `I18nProvider` — client-side provider component
+- `I18nProviderProps` — provider prop type
+
+## Important Boundaries
+
+- `withFluenti()` installs the loader and generates `@fluenti/next`
+- imported `t` remains compile-time only
+- server-side direct-import `t` requires an async server scope
+- `useI18n()` is not the server runtime escape hatch; use `await getI18n()` instead
+
+## Preferred Usage (compile-time first)
+
+1. t\`\` tagged template — t\`Hello {name}\` (primary compile-time API, works in client and server)
+2. `<Trans>` / `<Plural>` / `<Select>` — rich text with inline markup
+3. `msg` tagged template — outside components (route meta, stores)
+4. `getI18n().t()` / `useI18n().t()` — runtime fallback for dynamic keys only
+
+❌ AVOID: `t('some.key')` as the default — this is a legacy i18n pattern.
+
+## Docs
+
+- Full docs: https://fluenti.dev
+- Source: https://github.com/usefluenti/fluenti

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluenti/next",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Next.js plugin for Fluenti — withFluenti, I18nProvider, t`` transforms for App Router and Pages Router",
   "homepage": "https://fluenti.dev",
@@ -63,7 +63,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "llms*.txt"
   ],
   "peerDependencies": {
     "next": ">=14.0.0",
@@ -71,11 +72,12 @@
   },
   "dependencies": {
     "jiti": "^2",
-    "@fluenti/core": "0.2.0",
-    "@fluenti/react": "0.2.0"
+    "picomatch": "^4",
+    "@fluenti/react": "0.3.0",
+    "@fluenti/core": "0.3.0"
   },
   "devDependencies": {
-    "@types/node": "^22",
+    "@types/node": "^25",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@vitest/coverage-v8": "^4",

package/dist/scope-transform.d.ts

@@ -1,3 +0,0 @@
-export { scopeTransform } from '@fluenti/core/internal';
-export type { ScopeTransformOptions, ScopeTransformResult, Replacement } from '@fluenti/core/internal';
-//# sourceMappingURL=scope-transform.d.ts.map

package/dist/scope-transform.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"scope-transform.d.ts","sourceRoot":"","sources":["../src/scope-transform.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AACvD,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAA"}

package/dist/trans-transform.d.ts

@@ -1,3 +0,0 @@
-export { transformTransComponents } from '@fluenti/core/internal';
-export type { TransTransformResult } from '@fluenti/core/internal';
-//# sourceMappingURL=trans-transform.d.ts.map

package/dist/trans-transform.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"trans-transform.d.ts","sourceRoot":"","sources":["../src/trans-transform.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAA;AACjE,YAAY,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAA"}