@intlayer/docs 9.0.0-canary.2 → 9.0.0-canary.21

package/docs/en/packages/vite-intlayer/intlayerProxy.md

@@ -0,0 +1,172 @@
+---
+createdAt: 2026-06-25
+updatedAt: 2026-06-25
+title: intlayerProxy Vite Plugin Documentation | vite-intlayer
+description: Locale-routing middleware for Vite dev/preview servers and production SSR. Handles locale detection, URL redirects, and internal rewrites.
+keywords:
+  - intlayerProxy
+  - vite
+  - plugin
+  - middleware
+  - locale
+  - routing
+  - internationalization
+  - i18n
+  - SSR
+slugs:
+  - doc
+  - packages
+  - vite-intlayer
+  - intlayerProxy
+history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "Merged configOptions into single options object; proxy bundled into intlayer()"
+author: aymericzip
+---
+
+# intlayerProxy
+
+`intlayerProxy` is a Vite plugin that registers locale-routing middleware for **every environment**: dev server, preview server, and production SSR (Nitro / TanStack Start).
+
+> **Since Intlayer v9** `intlayerProxy` is automatically included inside the main [`intlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/vite-intlayer/intlayer.md) plugin and enabled by default via `routing.enableProxy: true`. You only need to register it separately if you need lower-level control or are using it outside the standard `intlayer()` setup.
+
+## Usage
+
+### As part of `intlayer()` (recommended, v9+)
+
+Pass `proxy` options to the main plugin instead of registering `intlayerProxy` separately:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
+});
+```
+
+### Standalone (when needed)
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+## Options
+
+```ts
+import type { IntlayerProxyPluginOptions } from "vite-intlayer";
+```
+
+All options are optional and passed as a single object:
+
+| Option          | Type                                | Description                                                                                                                                        |
+| --------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ignore`        | `(req: IncomingMessage) => boolean` | Predicate that excludes requests from locale routing. Return `true` to skip a request (e.g. API routes, health checks).                            |
+| `configOptions` | `GetConfigurationOptions`           | Intlayer configuration overrides forwarded to `getConfiguration()`. Use when you need the proxy to read a specific config file or override values. |
+
+### Example
+
+```ts
+intlayerProxy({
+  ignore: (req) => req.url?.startsWith("/api"),
+  configOptions: { configFile: "./config/intlayer.config.ts" },
+});
+```
+
+## createIntlayerProxyHandler
+
+`createIntlayerProxyHandler` creates a standalone, framework-agnostic Node.js `(req, res, next)` middleware that contains all the locale-routing logic. It is useful in environments where the Vite plugin API is unavailable (e.g. a plain Node.js server or a custom Nitro module).
+
+```ts
+import { createIntlayerProxyHandler } from "vite-intlayer";
+
+const handler = createIntlayerProxyHandler({
+  ignore: (req) => req.url?.startsWith("/api"),
+  configOptions: { configFile: "./config/intlayer.config.ts" },
+});
+
+// Express / Connect
+app.use(handler);
+```
+
+### Production SSR (TanStack Start / Nitro via h3)
+
+```ts
+// server/middleware/intlayerProxy.ts
+import { fromNodeMiddleware } from "h3";
+import { createIntlayerProxyHandler } from "vite-intlayer";
+
+export default fromNodeMiddleware(
+  createIntlayerProxyHandler({
+    ignore: (req) => req.url?.startsWith("/api"),
+  })
+);
+```
+
+## Routing behaviour
+
+The middleware mirrors the routing logic from `next-intlayer` middleware and supports all Intlayer routing modes.
+
+### Routing modes
+
+| Mode            | URL visible in browser   | Behaviour                                                                                               |
+| --------------- | ------------------------ | ------------------------------------------------------------------------------------------------------- |
+| `prefix`        | `/en/about`              | Default. Locale prefix in the URL. Default locale redirects to the un-prefixed URL unless `prefix-all`. |
+| `prefix-all`    | `/en/about`, `/fr/about` | All locales — including default — are always prefixed.                                                  |
+| `no-prefix`     | `/about`                 | No locale in the URL. Locale is stored in cookies only; URL rewrites happen internally.                 |
+| `search-params` | `/about?locale=en`       | Locale passed as a query parameter. Redirects to add/update the `locale` param when missing or stale.   |
+
+### Detection priority
+
+1. URL path prefix (e.g. `/fr/about` → `fr`).
+2. Cookie / localStorage value (`intlayer-locale`).
+3. `Accept-Language` header.
+4. `defaultLocale` from config.
+
+### Automatic bypass
+
+The middleware always passes these requests straight through without locale handling:
+
+- Requests matching the `ignore` predicate.
+- `/node_modules/**`
+- `/@**` – Vite internals (`@vite/`, `@fs/`, `@id/`, etc.).
+- `/_**` – server internals (`__vite_ping`, `__manifest`, etc.).
+- Requests whose path ends with a file extension (static assets). If a locale prefix is present on a static asset path (e.g. `/fr/logo.png`), it is stripped so the file can be served correctly.
+
+### Domain routing
+
+When `routing.domains` is configured in your Intlayer config, the middleware handles cross-domain locale routing:
+
+- A request for `/zh/about` on `intlayer.org` is redirected to `https://intlayer.zh/about` when `domains.zh = "intlayer.zh"`.
+- A request to `intlayer.zh/about` is rewritten internally to `/zh/about` so the `[locale]` route parameter is populated.
+
+### Redirect loop protection
+
+The middleware tracks redirect counts per `originalUrl → newUrl` pair within a 2-second sliding window. More than 10 redirects within that window returns a `500` response with a descriptive error instead of looping forever.
+
+## Nitro / production SSR (automatic injection, v9+)
+
+When `intlayerProxy` is used as a Vite plugin, it carries a `.nitro` property. The `nitro/vite` build plugin reads this property and pushes it into `nitroConfig.modules`, so `intlayerNitroHandler` is registered as a Nitro server middleware automatically — no manual configuration is needed for production SSR.
+
+The Nitro handler uses h3 v2's Web Fetch API event model (not `fromNodeMiddleware`) so it is compatible with all Nitro presets: Node, Bun, Deno, edge runtimes.
+
+## Deprecated aliases
+
+| Deprecated export          | Replacement     |
+| -------------------------- | --------------- |
+| `intlayerMiddleware`       | `intlayerProxy` |
+| `intLayerMiddlewarePlugin` | `intlayerProxy` |

package/docs/en/packages/vite-intlayer/intlayerPrune.md

@@ -1,45 +1,123 @@
 ---
 createdAt: 2026-01-21
-updatedAt: 2026-01-21
+updatedAt: 2026-06-25
 title: intlayerPrune Vite Plugin Documentation | vite-intlayer
-description: See how to use the intlayerPrune plugin for vite-intlayer package
+description: Vite plugin that tree-shakes unused dictionary fields from the production bundle to reduce bundle size.
 keywords:
   - intlayerPrune
   - vite
   - plugin
   - tree-shaking
-  - Intlayer
-  - intlayer
-  - Internationalization
-  - Documentation
+  - bundle size
+  - dictionary
+  - internationalization
+  - i18n
 slugs:
   - doc
   - packages
   - vite-intlayer
   - intlayerPrune
 history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "Expanded with field-level pruning, pruneContext, and edge-case details"
   - version: 8.0.0
     date: 2026-01-21
     changes: "Init doc"
 author: aymericzip
 ---
 
-# intlayerPrune Vite Plugin Documentation
+# intlayerPrune
 
-The `intlayerPrune` Vite plugin is used to tree-shake and prune unused dictionaries from your application bundle. This helps reduce the final bundle size by only including the necessary multilingual content.
+`intlayerPrune` is a Vite plugin that removes unused content fields from compiled dictionary JSON files during a production build. Instead of shipping every field from every dictionary, only the fields that are actually accessed in your source code are included in the bundle.
+
+> The plugin is already included and configured automatically when you use [`intlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/vite-intlayer/intlayer.md). You only need to register it manually if you are composing the plugin stack yourself.
 
 ## Usage
 
+### As part of `intlayer()` (recommended)
+
+Enable pruning through your Intlayer config and the main plugin handles everything:
+
+```ts
+// intlayer.config.ts
+import { defineConfig } from "intlayer";
+
+export default defineConfig({
+  build: {
+    optimize: true, // enables both prune and minify
+  },
+});
+```
+
 ```ts
 // vite.config.ts
 import { defineConfig } from "vite";
-import { intlayer, intlayerPrune } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
-  plugins: [intlayer(), intlayerPrune()],
+  plugins: [intlayer()],
 });
 ```
 
-## Description
+### Standalone
+
+If you are composing the plugin stack manually, `intlayerPrune` and `intlayerMinify` share a `PruneContext` object that must be created once and passed to both:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayerPrune, intlayerMinify } from "vite-intlayer";
+import { createPruneContext } from "@intlayer/babel";
+import { getConfiguration } from "@intlayer/config/node";
+
+const intlayerConfig = getConfiguration();
+const pruneContext = createPruneContext();
+
+export default defineConfig({
+  plugins: [
+    intlayerPrune(intlayerConfig, pruneContext),
+    intlayerMinify(intlayerConfig, pruneContext), // optional, reads from same context
+  ],
+});
+```
+
+## How it works
+
+### 1. Usage analysis (buildStart)
+
+During `buildStart`, the `intlayerOptimize` plugin (also part of `intlayer()`) scans every component source file listed in `build.filesList`. For each `useIntlayer('key')` or `getIntlayer('key')` call, it records exactly which fields are accessed, e.g.:
+
+```ts
+const { title, description } = useIntlayer("myDict");
+// records: myDict → { title, description }
+```
+
+This builds `pruneContext.fieldUsageMap` before any `transform` calls run.
+
+### 2. JSON pruning (transform, enforce: 'pre')
+
+When Vite processes a compiled dictionary JSON file, `intlayerPrune` intercepts it before Vite's built-in JSON → ESM conversion. It reads the field-usage map from `pruneContext` and removes any content field that is not in the recorded usage set.
+
+Two content shapes are supported:
+
+- **Static dictionaries** — `{ nodeType: "translation", translation: { en: {...}, fr: {...} } }`. Fields are pruned per-locale inside `translation`.
+- **Dynamic (per-locale) dictionaries** — flat `{ fieldA: ..., fieldB: ... }`. Fields are pruned at the top level.
+
+### 3. Edge cases
+
+If a dictionary's content structure cannot be recognised (e.g. an unusual nested shape), it is added to `pruneContext.dictionariesWithEdgeCases` and **left untouched**. A warning is logged. `intlayerMinify` also skips these dictionaries.
+
+### 4. Field-rename map
+
+When pruning succeeds, `intlayerPrune` also writes `pruneContext.dictionaryKeyToFieldRenameMap` — a mapping from original field names to short aliases. `intlayerMinify` reads this map to rename fields in the output JSON, and `intlayerOptimize`'s Babel rename pass updates property accesses in source files accordingly.
+
+## Activation conditions
+
+`intlayerPrune` is active **only** when all of the following are true:
+
+1. The Vite command is `build`.
+2. `build.optimize` is `true` (or `undefined`, which defaults to `true` for builds).
+3. `build.purge` is `true` in your Intlayer config.
 
-The plugin analyzes your source code to identify which dictionary keys are actually used. It then removes any unused content from the bundled dictionary files. This is particularly useful for large projects with many dictionaries where only a subset is used in specific pages or components.
+It is automatically **disabled** when `editor.enabled` is `true` because the editor needs the full dictionary content.

package/docs/en/packages/vue-intlayer/exports.md

@@ -14,6 +14,9 @@ slugs:
   - vue-intlayer
   - exports
 history:
+  - version: 10.0.0
+    date: 2026-06-23
+    changes: "Add usePathname utility"
   - version: 8.0.0
     date: 2026-01-21
     changes: "Unified documentation for all exports"
@@ -59,6 +62,7 @@ import "vue-intlayer";
 | `useDictionaryAsync`   | Same as `useDictionary`, but handles asynchronous dictionaries.                                                   | -                                                                                                                     |
 | `useDictionaryDynamic` | Same as `useDictionary`, but handles dynamic dictionaries.                                                        | -                                                                                                                     |
 | `useLocale`            | Returns the current locale and a function to set it.                                                              | -                                                                                                                     |
+| `usePathname`          | Returns the current pathname as a `ComputedRef<string>` with the locale segment removed. Reactive to `popstate`.  | [usePathname](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/vue-intlayer/usePathname.md)     |
 | `useRewriteURL`        | Client-side composable to manage URL rewrites. Automatically updates the URL if a localized rewrite rule exists.  | [useRewriteURL](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/vue-intlayer/useRewriteURL.md) |
 | `useIntl`              | Returns the Intl object for the current locale.                                                                   | -                                                                                                                     |
 | `useLoadDynamic`       | Composable to load dynamic dictionaries.                                                                          | -                                                                                                                     |

package/docs/en/packages/vue-intlayer/usePathname.md

@@ -0,0 +1,109 @@
+---
+createdAt: 2026-06-22
+updatedAt: 2026-06-22
+title: usePathname Composable Documentation | vue-intlayer
+description: See how to use the usePathname composable for vue-intlayer package
+keywords:
+  - usePathname
+  - pathname
+  - locale
+  - Intlayer
+  - Internationalization
+  - Documentation
+  - Vue
+  - JavaScript
+slugs:
+  - doc
+  - packages
+  - vue-intlayer
+  - usePathname
+history:
+  - version: 10.0.0
+    date: 2026-06-23
+    changes: "Add usePathname utility"
+  - version: 8.2.0
+    date: 2026-06-22
+    changes: "Init history"
+author: aymericzip
+---
+
+# Vue Integration: `usePathname` Composable Documentation
+
+The `usePathname` composable returns the current browser pathname with the locale segment stripped, as a reactive `ComputedRef<string>`. It is useful for building locale-aware navigation — for example, determining which nav item is active — without having to manually remove the locale prefix.
+
+## Importing `usePathname` in Vue
+
+```typescript
+import { usePathname } from "vue-intlayer";
+```
+
+## Overview
+
+`usePathname` reads `window.location.pathname`, strips the locale prefix via `getPathWithoutLocale`, and updates automatically when the browser fires a `popstate` event (back/forward navigation). The result is exposed as a `ComputedRef<string>` so it integrates naturally with Vue's reactivity system.
+
+## Usage
+
+```vue fileName="src/components/NavItem.vue"
+<script setup lang="ts">
+import { usePathname } from "vue-intlayer";
+
+const props = defineProps<{
+  href: string;
+  label: string;
+}>();
+
+const pathname = usePathname();
+</script>
+
+<template>
+  <a :href="href" :aria-current="pathname === href ? 'page' : undefined">
+    {{ label }}
+  </a>
+</template>
+```
+
+## Return Value
+
+| Type                  | Description                                                                      |
+| --------------------- | -------------------------------------------------------------------------------- |
+| `ComputedRef<string>` | Reactive computed ref containing the current pathname without the locale prefix. |
+
+## Behavior
+
+- **Locale stripping**: Removes the leading locale segment (e.g. `/fr/dashboard` → `/dashboard`).
+- **Reactive**: Updates automatically on `popstate` events (browser back / forward navigation).
+- **SSR-safe**: Returns `""` when `window` is not available.
+- **Cleanup**: The `popstate` listener is removed automatically when the component is unmounted (`onUnmounted`).
+
+## Example
+
+```vue fileName="src/components/Sidebar.vue"
+<script setup lang="ts">
+import { usePathname } from "vue-intlayer";
+
+const links = [
+  { href: "/dashboard", label: "Dashboard" },
+  { href: "/settings", label: "Settings" },
+];
+
+const pathname = usePathname();
+</script>
+
+<template>
+  <nav>
+    <a
+      v-for="link in links"
+      :key="link.href"
+      :href="link.href"
+      :style="{ fontWeight: pathname === link.href ? 'bold' : 'normal' }"
+    >
+      {{ link.label }}
+    </a>
+  </nav>
+</template>
+```
+
+## Related
+
+- [`useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/vue-intlayer/exports.md) — current locale + locale switcher
+- [`getPathWithoutLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/intlayer/getPathWithoutLocale.md) — the underlying utility used by this composable

package/docs/en/plugins/sync-json.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-03-13
-updatedAt: 2025-12-13
+updatedAt: 2026-06-21
 title: Sync JSON plugin
 description: Synchronize Intlayer dictionaries with third‑party i18n JSON files (i18next, next-intl, react-intl, vue-i18n, and more). Keep your existing i18n while using Intlayer to manage, translate, and test your messages.
 keywords:
@@ -24,6 +24,9 @@ slugs:
   - sync-json
 youtubeVideo: https://www.youtube.com/watch?v=MpGMxniDHNg
 history:
+  - version: 9.0.0
+    date: 2026-06-21
+    changes: "Add splitKeys option (one dictionary per top-level namespace key) for next-intl / react-intl single-file layouts"
   - version: 7.5.0
     date: 2025-12-13
     changes: "Add ICU and i18next format support"
@@ -105,7 +108,6 @@ const config: IntlayerConfig = {
      * Will load, and write the output and translations back to the JSON files in the locales directory
      */
     syncJSON({
-      format: "i18next",
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
       priority: 0,
       format: "i18next",
@@ -182,6 +184,7 @@ syncJSON({
   location?: string, // optional label, default: "plugin"
   priority?: number, // optional priority for conflict resolution, default: 0
   format?: 'intlayer' | 'icu' | 'i18next', // optional formatter, used for intlayer runtime compatibility
+  splitKeys?: boolean, // optional, split a single file into one dictionary per top-level key (auto-detected)
 });
 ```
 
@@ -206,6 +209,38 @@ syncJSON({
 }),
 ```
 
+#### `splitKeys` (boolean)
+
+Controls whether a single JSON file whose **first-level keys are namespaces** should become one dictionary per top-level key, instead of a single dictionary holding the whole file.
+
+This matches the namespace model of libraries like `next-intl` and `react-intl`, where one `messages/{locale}.json` file groups several namespaces by its first-level keys, each addressed independently (e.g. `useTranslations('Hero')` resolves to the `Hero` dictionary).
+
+- `undefined` (default): **auto-detected** — the file is split when the `source` pattern has no `{key}` segment (one file holds every namespace), and kept as a single dictionary otherwise (one file per key).
+- `true`: always split each top-level key into its own dictionary.
+- `false`: never split; the whole file becomes a single dictionary.
+
+Given a single `messages/{locale}.json` file:
+
+```json fileName="messages/en.json"
+{
+  "Hero": { "title": "Full-stack developer" },
+  "Nav": { "work": "Work", "about": "About" },
+  "About": { "lead": "I build apps end to end." }
+}
+```
+
+```ts fileName="intlayer.config.ts"
+syncJSON({
+  format: "icu",
+  source: ({ locale }) => `./messages/${locale}.json`,
+  // splitKeys: true, // implied because the pattern has no `{key}` segment
+}),
+```
+
+This produces three dictionaries — `Hero`, `Nav`, and `About` — so `useTranslations('Hero')` (next-intl) resolves correctly. On write-back, all namespaces are re-assembled into the same per-locale file.
+
+> When you keep the explicit `{key}` segment in your `source` (e.g. `./locales/${locale}/${key}.json`), each file is already one namespace, so splitting is disabled by default.
+
 ### Multiple JSON sources and priority
 
 You can add multiple `syncJSON` plugins to synchronize different JSON sources. This is useful when you have multiple i18n libraries or different JSON structures in your project.
@@ -338,6 +373,9 @@ loadJSON({
 
   // Optional formatter for the JSON content
   format?: 'intlayer' | 'icu' | 'i18next', // default: 'intlayer'
+
+  // Split a single file into one dictionary per top-level key (auto-detected)
+  splitKeys?: boolean,
 });
 ```
 
@@ -359,10 +397,25 @@ loadJSON({
 }),
 ```
 
+#### `splitKeys` (boolean)
+
+Same behavior as in [`syncJSON`](#splitkeys-boolean): when a single JSON file groups several namespaces by its first-level keys, each top-level key becomes its own dictionary.
+
+- `undefined` (default): **auto-detected** — split when the `source` pattern has no `{key}` segment, single dictionary otherwise.
+- `true` / `false`: force or disable splitting.
+
+```ts
+loadJSON({
+  source: ({ locale }) => `./messages/${locale}.json`,
+  format: "icu",
+  // splitKeys auto-enabled: `Hero`, `Nav`, `About`, … each become a dictionary
+}),
+```
+
 ### Behavior and conventions
 
 - If your `source` mask includes a locale placeholder, only files for the selected `locale` are ingested.
-- If there is no `{key}` segment in your mask, the dictionary key is "index".
+- If there is no `{key}` segment in your mask, each top-level key of the file becomes its own dictionary by default (see [`splitKeys`](#splitkeys-boolean)). Set `splitKeys: false` to instead load the whole file as a single `index` dictionary.
 - Keys are derived from file paths by substituting the `{key}` placeholder in your `source` builder.
 - The plugin only uses discovered files and does not fabricate missing locales or keys.
 - The `fill` path is inferred from your `source` and used to update missing values via CLI when you opt‑in.