@fluenti/nuxt 0.2.0 → 0.3.0

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,uBAAuB,GAAG,oBAAoB,GAAG,WAAW,CAAA;AAE9F,yCAAyC;AACzC,MAAM,WAAW,4BAA4B;IAC3C,kDAAkD;IAClD,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,2CAA2C;IAC3C,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,8BAA8B;AAC9B,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAA;AAEpE;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAA;IACZ,6BAA6B;IAC7B,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,qBAAqB;IACrB,aAAa,EAAE,MAAM,CAAA;IACrB,uBAAuB;IACvB,QAAQ,EAAE,QAAQ,CAAA;IAClB,mCAAmC;IACnC,qBAAqB,CAAC,EAAE,4BAA4B,CAAA;IACpD,4DAA4D;IAC5D,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,kDAAkD;IAClD,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;IACnC,2CAA2C;IAC3C,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,GAAG,EAAE,mBAAmB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AAEjF,+EAA+E;AAC/E,MAAM,WAAW,iBAAiB;IAChC,qCAAqC;IACrC,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,0BAA0B;IAC1B,aAAa,EAAE,MAAM,CAAA;IACrB,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,2CAA2C;IAC3C,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,8CAA8C;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,0CAA0C;IAC1C,qBAAqB,CAAC,EAAE,4BAA4B,CAAA;IACpD;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,KAAK,CAAC,eAAe,GAAG,MAAM,CAAC,CAAA;IAC7C;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,UAAU,CAAA;IAChB,kDAAkD;IAClD,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED,wBAAwB;AACxB,MAAM,WAAW,UAAU;IACzB,wCAAwC;IACxC,OAAO,EAAE,OAAO,CAAA;IAChB,oDAAoD;IACpD,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED,+DAA+D;AAC/D,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,aAAa,EAAE,MAAM,CAAA;IACrB,QAAQ,EAAE,QAAQ,CAAA;IAClB,qBAAqB,CAAC,EAAE,4BAA4B,CAAA;IACpD,2CAA2C;IAC3C,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;CAC3B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/llms-full.txt

@@ -0,0 +1,411 @@
+# @fluenti/nuxt
+
+> Nuxt 3 module for Fluenti — locale-prefixed routing, locale detection, SEO head helpers, and NuxtLinkLocale component.
+
+@fluenti/nuxt integrates Fluenti i18n into Nuxt 3 with four URL routing strategies, an ordered locale detection chain, automatic vite-plugin registration, SEO head helpers (hreflang, og:locale), a locale-aware NuxtLinkLocale component, and full SSR/SSG/SPA/ISR support. Compatible with Nuxt >= 3.0.0.
+
+## Install
+
+```bash
+pnpm add @fluenti/nuxt @fluenti/core @fluenti/vue
+```
+
+## Setup
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@fluenti/nuxt'],
+  fluenti: {
+    locales: ['en', 'ja', 'zh'],
+    defaultLocale: 'en',
+    strategy: 'prefix_except_default',
+  },
+})
+```
+
+## Preferred Usage (compile-time first)
+
+When writing Nuxt application code with Fluenti, prefer compile-time APIs:
+
+1. `v-t` directive — `<p v-t>Hello {name}</p>` (Vue templates, zero runtime cost)
+2. t`` tagged template — t`Hello {name}` (primary compile-time API)
+3. `<Trans>` / `<Plural>` / `<Select>` — rich text with inline markup
+4. `msg` tagged template — outside components (route meta, stores)
+5. `useI18n().t()` — runtime fallback for dynamic keys only
+
+❌ AVOID: `t('some.key')` as the default — this is a legacy i18n pattern.
+
+## Module Options
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  fluenti: {
+    // Required
+    locales: ['en', 'ja', 'zh'],
+    defaultLocale: 'en',
+
+    // Routing
+    strategy: 'prefix_except_default',
+
+    // Locale detection
+    detectOrder: ['path', 'cookie', 'header'],
+    detectBrowserLanguage: {
+      useCookie: true,
+      cookieKey: 'fluenti_locale',
+      fallbackLocale: 'en',
+    },
+
+    // Build
+    autoVitePlugin: true,
+    componentPrefix: '',
+
+    // ISR (Incremental Static Regeneration)
+    isr: { enabled: true, ttl: 3600 },
+  },
+})
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `locales` | `string[]` | — | Supported locale codes (required) |
+| `defaultLocale` | `string` | `'en'` | Default locale code (required) |
+| `strategy` | `Strategy` | `'prefix_except_default'` | URL routing strategy |
+| `detectOrder` | `string[]` | `['path', 'cookie', 'header']` | Ordered list of locale detectors |
+| `detectBrowserLanguage` | `object` | — | Cookie and fallback settings |
+| `autoVitePlugin` | `boolean` | `true` | Auto-register `@fluenti/vite-plugin` |
+| `componentPrefix` | `string` | `''` | Prefix for i18n components |
+| `isr` | `{ enabled, ttl? }` | — | ISR route rules generation |
+| `compat` | `boolean` | `false` | Enable vue-i18n bridge mode |
+
+## Routing Strategies
+
+| Strategy | Default locale | Other locales | Example |
+|----------|---------------|---------------|---------|
+| `prefix_except_default` | `/about` | `/ja/about` | Most common — clean URLs for default locale |
+| `prefix` | `/en/about` | `/ja/about` | Every locale gets a prefix |
+| `prefix_and_default` | `/about` + `/en/about` | `/ja/about` | Default locale accessible both ways |
+| `no_prefix` | `/about` | `/about` | No URL prefixes — locale set via cookie/header |
+
+## Locale Detection
+
+When a request arrives, the module runs a detection chain to determine which locale to use. Detectors run in the order specified by `detectOrder`. The first detector to resolve a locale wins.
+
+### Detection Flow
+
+```
+Request -> detectOrder chain -> fluenti:detect-locale hook -> fallback
+                                                                |
+                                                fallbackLocale -> defaultLocale
+```
+
+### Built-in Detectors
+
+| Detector | Reads from | Example | Notes |
+|----------|-----------|---------|-------|
+| `path` | URL prefix | `/ja/about` -> `ja` | Most reliable for SEO |
+| `cookie` | Cookie value | `fluenti_locale=ja` | Persists across visits |
+| `header` | `Accept-Language` | `ja,en;q=0.5` -> `ja` | Server-side only, content negotiation |
+| `query` | Query parameter | `?locale=ja` -> `ja` | Useful for previewing |
+
+### detectBrowserLanguage
+
+Controls cookie persistence and fallback behavior:
+
+```ts
+detectBrowserLanguage: {
+  useCookie: true,               // persist detected locale in a cookie
+  cookieKey: 'fluenti_locale',   // cookie name (default: 'fluenti_locale')
+  fallbackLocale: 'en',          // used when no detector resolves
+}
+```
+
+When `useCookie` is enabled, the module automatically:
+- Reads the locale from the cookie during detection
+- Writes the cookie whenever the locale changes
+
+The `fallbackLocale` is used when no detector in the chain resolves a locale. If not set, `defaultLocale` is used.
+
+### Custom Detector Hook
+
+Use the `fluenti:detect-locale` Nuxt hook to add custom detection logic. The hook runs after all built-in detectors, but only if no detector has resolved yet.
+
+```ts
+// modules/custom-detect.ts
+import { defineNuxtModule, addPlugin, createResolver } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup(_, nuxt) {
+    const { resolve } = createResolver(import.meta.url)
+    addPlugin({ src: resolve('./runtime/detect-plugin'), order: -1 })
+  },
+})
+```
+
+```ts
+// modules/runtime/detect-plugin.ts
+export default defineNuxtPlugin((nuxtApp) => {
+  nuxtApp.hook('fluenti:detect-locale', (ctx) => {
+    if (!ctx.isServer) return
+
+    const event = useRequestEvent()
+    const headerLocale = event?.headers?.get('x-user-locale')
+
+    if (headerLocale && ctx.locales.includes(headerLocale)) {
+      ctx.setLocale(headerLocale)
+    }
+  })
+})
+```
+
+The `LocaleDetectContext` passed to the hook:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `path` | `string` | The request path |
+| `locales` | `string[]` | Available locale codes |
+| `defaultLocale` | `string` | Default locale |
+| `strategy` | `Strategy` | Routing strategy |
+| `detectedLocale` | `string \| null` | Locale detected so far |
+| `setLocale` | `(locale) => void` | Call to claim a locale and stop the chain |
+| `isServer` | `boolean` | Whether running on the server |
+
+## Locale Redirect Middleware
+
+When using the `prefix` strategy, a global middleware automatically redirects unprefixed URLs to locale-prefixed ones:
+
+```
+GET /about -> 302 -> /en/about   (detected via cookie/header/fallback)
+GET /ja/about -> no redirect     (already has prefix)
+```
+
+The middleware only activates for the `prefix` strategy. For `prefix_except_default`, unprefixed paths are treated as the default locale.
+
+## Composables
+
+### useLocalePath()
+
+Generate locale-prefixed paths.
+
+```vue
+<script setup>
+const localePath = useLocalePath()
+</script>
+
+<template>
+  <NuxtLink :to="localePath('/about')">About</NuxtLink>
+  <NuxtLink :to="localePath('/about', 'ja')">About (JA)</NuxtLink>
+</template>
+```
+
+### useSwitchLocalePath()
+
+Get the current page path in a different locale.
+
+```vue
+<script setup>
+const switchLocalePath = useSwitchLocalePath()
+</script>
+
+<template>
+  <!-- If on /ja/about, this returns /about (en is default) -->
+  <NuxtLink :to="switchLocalePath('en')">English</NuxtLink>
+  <NuxtLink :to="switchLocalePath('ja')">日本語</NuxtLink>
+</template>
+```
+
+### useLocaleHead()
+
+Generate SEO-friendly `<head>` metadata — `hreflang` alternate links, `og:locale` meta tags, and `html[lang]`.
+
+```vue
+<script setup>
+const head = useLocaleHead({
+  addSeoAttributes: true,
+  baseUrl: 'https://example.com',
+})
+
+useHead(head.value)
+</script>
+```
+
+Generated output:
+
+```html
+<html lang="en">
+<head>
+  <link rel="alternate" hreflang="en" href="https://example.com/about" />
+  <link rel="alternate" hreflang="ja" href="https://example.com/ja/about" />
+  <link rel="alternate" hreflang="x-default" href="https://example.com/about" />
+  <meta property="og:locale" content="en" />
+  <meta property="og:locale:alternate" content="ja" />
+</head>
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `addSeoAttributes` | `boolean` | `false` | Generate hreflang and og:locale tags |
+| `baseUrl` | `string` | `''` | Base URL for absolute hreflang links |
+
+## Components
+
+### NuxtLinkLocale
+
+A locale-aware wrapper around `<NuxtLink>` that automatically prefixes paths based on the current locale and routing strategy.
+
+```vue
+<template>
+  <!-- Uses current locale -->
+  <NuxtLinkLocale to="/about">About</NuxtLinkLocale>
+  <!-- Renders: <a href="/ja/about">About</a> when locale is 'ja' -->
+
+  <!-- Override locale with the locale prop -->
+  <NuxtLinkLocale to="/about" locale="ja">About (JA)</NuxtLinkLocale>
+  <!-- Always renders: <a href="/ja/about">About (JA)</a> -->
+</template>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `to` | `string \| { path: string }` | — | Target path (required) |
+| `locale` | `string` | current locale | Override locale for this link |
+
+All other `<NuxtLink>` props and attributes are forwarded.
+
+## Route Utilities
+
+For programmatic use or custom module setup:
+
+```ts
+import { localePath, switchLocalePath, extractLocaleFromPath, extendPages } from '@fluenti/nuxt'
+
+// Add locale prefix to a path
+localePath('/about', 'ja', 'en', 'prefix_except_default')
+// -> '/ja/about'
+
+// Get current path in another locale
+switchLocalePath('/ja/about', 'en', ['en', 'ja'], 'en', 'prefix_except_default')
+// -> '/about'
+
+// Extract locale from a path
+extractLocaleFromPath('/ja/about', ['en', 'ja'])
+// -> { locale: 'ja', pathWithoutLocale: '/about' }
+
+// Extend Nuxt pages with locale-prefixed variants
+extendPages(pages, { locales: ['en', 'ja'], defaultLocale: 'en', strategy: 'prefix_except_default' })
+```
+
+## Auto-imported APIs
+
+The module auto-imports the following — no `import` statements needed in components:
+
+| API | Source |
+|-----|--------|
+| `useI18n()` | `@fluenti/vue` |
+| `useLocalePath()` | `@fluenti/nuxt` |
+| `useSwitchLocalePath()` | `@fluenti/nuxt` |
+| `useLocaleHead()` | `@fluenti/nuxt` |
+| `<NuxtLinkLocale>` | `@fluenti/nuxt` (global component) |
+
+## SSR / SSG / SPA
+
+The module works in all three Nuxt rendering modes.
+
+### SSR (Server-Side Rendering)
+
+- Server runs the full detection chain (path, cookie, Accept-Language header)
+- Detected locale is stored in `nuxtApp.payload` for hydration
+- Client reads locale from payload to prevent hydration mismatch
+- Route changes sync locale reactively via `watch(route.path)`
+
+### SSG (Static Site Generation)
+
+```ts
+export default defineNuxtConfig({
+  nitro: { preset: 'static' },
+  fluenti: {
+    locales: ['en', 'ja', 'zh'],
+    strategy: 'prefix_except_default',
+  },
+})
+```
+
+- All locale-prefixed routes are pre-rendered automatically (`crawlLinks: true`)
+- Each locale variant is a separate static HTML file
+- Client-side locale switching works via Vue reactivity
+
+### SPA (Single Page Application)
+
+```ts
+export default defineNuxtConfig({
+  ssr: false,
+  fluenti: {
+    locales: ['en', 'ja', 'zh'],
+    strategy: 'prefix_except_default',
+    detectBrowserLanguage: { useCookie: true },
+  },
+})
+```
+
+- No server-side detection — locale is detected on the client
+- Extracts locale from URL path, then checks cookie, then defaults
+
+### ISR (Incremental Static Regeneration)
+
+```ts
+export default defineNuxtConfig({
+  fluenti: {
+    locales: ['en', 'ja'],
+    strategy: 'prefix_except_default',
+    isr: { enabled: true, ttl: 3600 },
+  },
+})
+```
+
+The module automatically generates `routeRules` for each locale pattern:
+
+```ts
+// Generated route rules:
+{
+  '/**': { isr: 3600 },       // default locale (prefix_except_default)
+  '/ja/**': { isr: 3600 },    // Japanese routes
+}
+```
+
+## Cookie Persistence
+
+When `detectBrowserLanguage.useCookie` is enabled:
+
+1. On locale detection, the cookie value is checked (after path detection)
+2. When the user switches locale (via `setLocale()` or navigation), the cookie is updated automatically
+3. On return visits, the cookie restores the user's preferred locale
+
+The cookie is set with `path: '/'` and uses the key from `cookieKey` (default: `fluenti_locale`).
+
+## TypeScript
+
+All types are exported:
+
+```ts
+import type {
+  FluentNuxtOptions,
+  Strategy,
+  FluentNuxtRuntimeConfig,
+  DetectBrowserLanguageOptions,
+  LocaleDetectContext,
+  LocaleDetectorFn,
+  BuiltinDetector,
+  ISROptions,
+  PageRoute,
+  LocaleHeadMeta,
+  LocaleHeadOptions,
+} from '@fluenti/nuxt'
+```
+
+## Documentation
+
+- Full docs: https://fluenti.dev
+- llms.txt: Concise summary
+- Source: https://github.com/usefluenti/fluenti
+- License: MIT

package/llms-migration.txt

@@ -0,0 +1,201 @@
+# Migrating to @fluenti/nuxt from @nuxtjs/i18n
+
+> Step-by-step guide to migrate a Nuxt 3 app from @nuxtjs/i18n to Fluenti.
+
+## Overview
+
+Fluenti is a **compile-time** i18n library — translations are compiled to optimized JS at build time. @nuxtjs/i18n wraps vue-i18n with Nuxt-specific routing and detection. Fluenti's Nuxt module provides similar routing capabilities but with zero-overhead compiled messages.
+
+Key differences:
+- Compile-time compilation vs runtime message parsing
+- ICU MessageFormat vs vue-i18n syntax
+- PO or JSON catalogs managed by CLI vs JSON locale files
+- Built-in Vite plugin for build-time transforms
+- Same routing strategies (prefix, prefix_except_default, etc.)
+
+## Step-by-step Migration
+
+### 1. Install Fluenti
+
+```bash
+pnpm add @fluenti/core @fluenti/vue @fluenti/nuxt
+pnpm add -D @fluenti/cli
+```
+
+### 2. Update Nuxt config
+
+Before (@nuxtjs/i18n):
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@nuxtjs/i18n'],
+  i18n: {
+    locales: [
+      { code: 'en', file: 'en.json' },
+      { code: 'ja', file: 'ja.json' },
+    ],
+    defaultLocale: 'en',
+    langDir: 'locales',
+    strategy: 'prefix_except_default',
+    detectBrowserLanguage: {
+      useCookie: true,
+      cookieKey: 'i18n_redirected',
+    },
+  },
+})
+```
+
+After (Fluenti):
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@fluenti/nuxt'],
+  fluenti: {
+    locales: ['en', 'ja'],
+    defaultLocale: 'en',
+    strategy: 'prefix_except_default',
+    detectBrowserLanguage: {
+      useCookie: true,
+      cookieKey: 'fluenti_locale',
+    },
+    catalogDir: './locales',
+    format: 'po',
+  },
+})
+```
+
+### 3. Update composable usage
+
+Before (@nuxtjs/i18n):
+```ts
+const { t, locale, setLocale, locales } = useI18n()
+const localePath = useLocalePath()
+const switchLocalePath = useSwitchLocalePath()
+```
+
+After (Fluenti):
+```ts
+const { t, locale, setLocale } = useI18n()
+const localePath = useLocalePath()
+const switchLocalePath = useSwitchLocalePath()
+```
+
+Most composables have the same API. Key differences in `useI18n()`:
+
+### 4. Update template usage
+
+Before (@nuxtjs/i18n):
+```vue
+<template>
+  <NuxtLink :to="localePath('/about')">{{ t('about') }}</NuxtLink>
+  <NuxtLink :to="switchLocalePath('ja')">日本語</NuxtLink>
+  <i18n-t keypath="welcome" tag="p">
+    <template #name><strong>User</strong></template>
+  </i18n-t>
+</template>
+```
+
+After (Fluenti):
+```vue
+<template>
+  <NuxtLinkLocale to="/about">{{ t('about') }}</NuxtLinkLocale>
+  <NuxtLink :to="switchLocalePath('ja')">日本語</NuxtLink>
+  <Trans message="Welcome, {0}{1}{2}">
+    <template #0><strong></template>
+    <template #1>User</template>
+    <template #2></strong></template>
+  </Trans>
+  <!-- Or simpler with v-t -->
+  <p v-t>Welcome</p>
+</template>
+```
+
+### 5. Convert translation files
+
+@nuxtjs/i18n JSON format:
+```json
+{
+  "hello": "Hello, {name}!",
+  "items": "no items | one item | {count} items"
+}
+```
+
+Fluenti PO format:
+```po
+msgid "hello"
+msgstr "Hello, {name}!"
+
+msgid "items"
+msgstr "{count, plural, =0 {no items} one {one item} other {{count} items}}"
+```
+
+Use the CLI to manage catalogs:
+```bash
+# Create fluenti.config.ts
+npx fluenti extract    # Extract from source
+npx fluenti compile    # Compile to JS
+```
+
+### 6. Update SEO/head meta
+
+Before (@nuxtjs/i18n):
+```ts
+const head = useLocaleHead({ addSeoAttributes: true })
+useHead({ htmlAttrs: { lang: head.value.htmlAttrs?.lang }, link: head.value.link, meta: head.value.meta })
+```
+
+After (Fluenti):
+```ts
+const head = useLocaleHead()
+useHead(head)
+```
+
+### 7. Remove old library
+
+```bash
+pnpm remove @nuxtjs/i18n
+```
+
+## API Mapping Table
+
+| @nuxtjs/i18n | @fluenti/nuxt |
+|--------------|---------------|
+| `useI18n()` | `useI18n()` |
+| `useLocalePath()` | `useLocalePath()` |
+| `useSwitchLocalePath()` | `useSwitchLocalePath()` |
+| `useLocaleHead()` | `useLocaleHead()` |
+| `<NuxtLink :to="localePath(...)">` | `<NuxtLinkLocale to="...">` |
+| `$t(key)` | `t(key)` (via useI18n) |
+| `$tc(key, count)` | `t(key, { count })` (ICU plural) |
+| `strategy: 'prefix_except_default'` | `strategy: 'prefix_except_default'` (same) |
+| `strategy: 'prefix'` | `strategy: 'prefix'` (same) |
+| `strategy: 'prefix_and_default'` | `strategy: 'prefix_and_default'` (same) |
+| `strategy: 'no_prefix'` | `strategy: 'no_prefix'` (same) |
+| `detectBrowserLanguage` | `detectBrowserLanguage` (similar config) |
+| `<i18n-t>` component | `<Trans>` component |
+| Lazy loading via `file` in locales | `loadMessages` callback |
+| `langDir` option | `catalogDir` option |
+
+## Routing Strategy Compatibility
+
+All four routing strategies from @nuxtjs/i18n are supported with the same names:
+- `prefix_except_default` — `/about` for default, `/ja/about` for others
+- `prefix` — `/en/about`, `/ja/about`
+- `prefix_and_default` — both `/about` and `/en/about` work for default
+- `no_prefix` — no locale in URL, detection via cookie/header
+
+## Locale Detection
+
+@nuxtjs/i18n detection order: cookie → navigator → header
+Fluenti detection chain: path → cookie → header → fallback
+
+Both support cookie-based persistence. Configure via `detectBrowserLanguage` option.
+
+## Key Behavioral Differences
+
+1. **Compile-time** — messages compiled at build time, no runtime parser in bundle
+2. **ICU MessageFormat** — standard plural/select syntax instead of vue-i18n pipe syntax
+3. **CLI workflow** — extract → translate → compile pipeline
+4. **PO file support** — compatible with Poedit, Crowdin, Weblate
+5. **NuxtLinkLocale** — dedicated component instead of wrapping NuxtLink with localePath
+6. **AI translation** — `npx fluenti translate --provider claude` for automated translation