@intlayer/docs 9.0.0-canary.6 → 9.0.0-canary.8

package/docs/en-GB/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
+  - internationalisation
+  - 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-GB/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-GB/about`              | Default. Locale prefix in the URL. Default locale redirects to the un-prefixed URL unless `prefix-all`. |
+| `prefix-all`    | `/en/about`, `/en-GB/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-GB`       | 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. `/en-GB/about` → `en-GB`).
+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. `/en-GB/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-GB/plugins/sync-json.md

@@ -108,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",

package/docs/en-GB/releases/v9.md

@@ -1,15 +1,14 @@
 ---
 createdAt: 2026-06-14
-updatedAt: 2026-06-23
+updatedAt: 2026-06-26
 title: New Intlayer v9 - What's new?
-description: Discover what's new in Intlayer v9. Introducing drop-in compatibility packages for popular i18n libraries and support for Collections, Variants, and Dynamic Records.
+description: Discover what's new in Intlayer v9. Introducing drop-in compatibility packages for popular i18n libraries and support for Collections and Variants.
 keywords:
   - Intlayer
   - Compatibility
   - Migration
   - Collections
   - Variants
-  - Dynamic Records
   - i18next
   - next-intl
   - vue-i18n
@@ -22,7 +21,7 @@ author: aymericzip
 
 # New Intlayer v9 - What's new?
 
-Welcome to Intlayer v9! This major release marks a huge milestone in simplifying the migration path to Intlayer with **Compat Adapter Packages** for major i18n libraries (`react-i18next`, `next-intl`, `vue-i18n`, etc.) and adds support for rich content structures: **Collections**, **Variants**, and **Dynamic Records**.
+Welcome to Intlayer v9! This major release marks a huge milestone in simplifying the migration path to Intlayer with **Compat Adapter Packages** for major i18n libraries (`react-i18next`, `next-intl`, `vue-i18n`, etc.) and adds support for rich content structures: **Collections** and **Variants**.
 
 ## Table of contents
 
@@ -41,8 +40,10 @@ By replacing imports, you get all the benefits of Intlayer (including compile-ti
 - `@intlayer/i18next`
 - `@intlayer/react-i18next`
 - `@intlayer/next-intl`
+- `@intlayer/react-intl`
 - `@intlayer/next-i18next`
 - `@intlayer/vue-i18n`
+- `@intlayer/lingui`
 
 For example, simply change:
 
@@ -100,7 +101,7 @@ All compat adapters now route translation resolution through a single, highly op
 
 ---
 
-## Feature Spec: Collections, Variants & Dynamic Records
+## Feature Spec: Collections & Variants
 
 Intlayer v9 expands beyond static key-value objects, allowing dictionaries to declare dynamic layout structures that are fully typed end-to-end.
 
@@ -136,6 +137,8 @@ const faq = useIntlayer("faq", { item: 1 }); // -> { question: string, answer: s
 
 Deliver A/B tests, seasonal headers, feature flags, or custom landing pages:
 
+#### String variants (e.g. A/B testing)
+
 ```ts fileName="hero.content.ts"
 import { t, type Dictionary } from "intlayer";
 
@@ -155,16 +158,14 @@ export default {
 const banner = useIntlayer("hero-banner", { variant: "black_friday" });
 ```
 
-### 3. Dynamic Records
-
-Define dictionaries whose entries are loaded dynamically at runtime via query IDs:
+#### Object variants (e.g. Dynamic Records)
 
 ```ts fileName="product.content.ts"
 import { t, type Dictionary } from "intlayer";
 
 export default {
   key: "product-copy",
-  meta: {
+  variant: {
     id: "prod_123",
     category: "books",
   },
@@ -217,7 +218,7 @@ export default defineConfig({
 });
 ```
 
-- **Compiler**: Activates automatically when `compiler.enabled` is set and a `compiler.output` path is configured. You no longer need to register `intlayerCompiler()` separately.
+- **Compiler**: Activates automatically when `compiler.enabled` is set to `true` and a `compiler.output` path is configured. You no longer need to register `intlayerCompiler()` separately.
 - **Proxy**: Activates automatically based on the new `routing.enableProxy` option (`true` by default). It wires the locale detection / redirect / rewrite middleware in development, preview, and production SSR. You no longer need to register `intlayerProxy()` separately.
 
 ### `routing.enableProxy` option
@@ -240,17 +241,61 @@ The standalone `intlayerCompiler()` and `intlayerProxy()` plugins remain exporte
 
 ---
 
+## Compiler disabled by default
+
+Starting with Intlayer v9, the **compiler is disabled by default** (`compiler.enabled` now defaults to `false`). To opt in to build-time extraction of your `.content.ts` files, set `compiler.enabled: true` in your configuration:
+
+```ts fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  compiler: {
+    enabled: true, // Default: false — required to enable the compiler since v9
+    output: ({ fileName }) => `./${fileName}.content.ts`,
+  },
+};
+
+export default config;
+```
+
+When the compiler is disabled, Intlayer skips the build-time extraction step and relies on your already-declared dictionaries. Enable it only when you want the bundler plugin (`@intlayer/swc`, `@intlayer/babel`, or the `intlayer()` Vite plugin) to extract content automatically.
+
+---
+
+## React Native: single-package imports
+
+In a React Native or Expo app, you no longer need to juggle both `react-intlayer` and `react-native-intlayer`. The `react-native-intlayer` package now **re-exports the full `react-intlayer` API** (hooks, utilities, and the `/format`, `/html`, and `/markdown` subpaths), and its `IntlayerProvider` automatically applies the React Native polyfills.
+
+Import everything from the single `react-native-intlayer` package:
+
+```tsx
+import {
+  IntlayerProvider,
+  useIntlayer,
+  useLocale,
+} from "react-native-intlayer";
+```
+
+```bash
+npm install intlayer react-native-intlayer
+```
+
+> Importing from `react-intlayer` keeps working, but `react-native-intlayer` is now the recommended single entry point for React Native — its provider ships the polyfills the web-oriented `react-intlayer` provider does not.
+
+---
+
 ## Migration notes from v8
 
 If you are upgrading from v8, note that the v9 does not include breaking changes. But here are the key changes:
 
+- **Compiler disabled by default**: `compiler.enabled` now defaults to `false`. If you rely on build-time extraction of your `.content.ts` files, set `compiler.enabled: true` in your `intlayer.config.ts`.
 - **Locales & Dialects**: If using external i18n dependencies, add their respective compat adapter plugins in your configuration or bundler setup to automatically rewrite imports.
-- **Custom Selectors**: When calling `useIntlayer`, the second parameter is now reserved for an option object containing `{ locale, item, variant, id }`. If you previously passed a locale string directly, you can still do so, but using the options object is recommended for advanced selections.
+- **Custom Selectors**: When calling `useIntlayer`, the second parameter is now reserved for an option object containing `{ locale, item, variant }`. If you previously passed a locale string directly, you can still do so, but using the options object is recommended for advanced selections.
 
 ---
 
 ## Useful links
 
 - [Compat Adapter Packages Guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/index.md)
-- [Dynamic Dictionaries - Collections, Variants & Dynamic Records](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dynamic_dictionaries/index.md)
+- [Dynamic Dictionaries - Collections & Variants](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dynamic_dictionaries/index.md)
 - [Configuration Reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md)

package/docs/es/compiler.md

@@ -81,12 +81,15 @@ Actualiza tu `vite.config.ts` para incluir el plugin `intlayerCompiler`:
 
 ```ts fileName="vite.config.ts"
 import { defineConfig } from "vite";
-import { intlayer, intlayerCompiler } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
   plugins: [
-    intlayer(),
-    intlayerCompiler(), // Añade el plugin del compilador
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 });
 ```

package/docs/es/custom_domains.md

@@ -172,10 +172,16 @@ El complemento Vite `intlayerProxy` aplica la misma lógica durante el desarroll
 
 ```typescript fileName="vite.config.ts"
 import { defineConfig } from "vite";
-import { intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
-  plugins: [intlayerProxy()],
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
 });
 ```
 

package/docs/es/custom_url_rewrites.md

@@ -342,10 +342,16 @@ Para SolidJS, Vue y Svelte, el plugin de Vite `intlayerProxy` gestiona las reesc
 
 ```typescript fileName="vite.config.ts"
 import { defineConfig } from "vite";
-import { intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
-  plugins: [intlayerProxy()],
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
 });
 ```
 

package/docs/es/dynamic_dictionaries/index.md

@@ -1,13 +1,12 @@
 ---
 createdAt: 2026-06-12
-updatedAt: 2026-06-12
-title: Diccionarios Dinámicos
-description: Descripción general de las tres funciones de diccionario dinámico de Intlayer — colecciones, variantes y registros dinámicos — para crear contenido i18n flexible y controlado en tiempo de ejecución.
+updatedAt: 2026-06-26
+title: Diccionarios dinámicos
+description: Resumen de las funciones de diccionarios dinámicos de Intlayer — colecciones y variantes — para crear contenido i18n flexible y dirigido en tiempo de ejecución.
 keywords:
-  - Diccionarios Dinámicos
+  - Diccionarios dinámicos
   - Colecciones
   - Variantes
-  - Registros Dinámicos
   - Intlayer
   - Internacionalización
 slugs:
@@ -18,31 +17,38 @@ history:
   - version: 9.0.0
     date: 2026-06-12
     changes: "Lanzamiento de la función de diccionarios dinámicos"
+  - version: 9.1.0
+    date: 2026-06-26
+    changes: "Fusión de los registros dinámicos en las variantes — `variant` ahora acepta una cadena o un objeto"
 author: aymericzip
 ---
 
-# Diccionarios Dinámicos
+# Diccionarios dinámicos
 
-Intlayer admite tres mecanismos para expresar contenido que va más allá de un único diccionario estático por clave. Cada uno se declara a través de un **campo de metadatos de nivel superior** en el archivo de contenido; no se necesita ninguna función contenedora (wrapper).
+Intlayer admite dos mecanismos para expresar contenido que va más allá de un único diccionario estático por clave. Cada uno se declara mediante un **campo de metadatos de nivel superior** en el archivo de contenido; no se necesita ninguna función envolvente.
 
-| Característica                                                                                                               | Campo de metadatos | Selector en `useIntlayer` |
-| ---------------------------------------------------------------------------------------------------------------------------- | ------------------ | ------------------------- |
-| [Colecciones](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/dynamic_dictionaries/collections.md)             | `item: N`          | `{ item: N }`             |
-| [Variantes](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/dynamic_dictionaries/variants.md)                  | `variant: "name"`  | `{ variant: "name" }`     |
-| [Registros Dinámicos](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/dynamic_dictionaries/dynamic_content.md) | `meta: { id, … }`  | `{ id, … }`               |
+| Función                                                                                                          | Campo de metadatos                     | Selector en `useIntlayer`                      |
+| ---------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ---------------------------------------------- |
+| [Colecciones](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/dynamic_dictionaries/collections.md) | `item: N`                              | `{ item: N }`                                  |
+| [Variantes](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/dynamic_dictionaries/variants.md)      | `variant: "name"` _o_ `variant: { … }` | `{ variant: "name" }` _o_ `{ variant: { … } }` |
 
-Los tres se componen con el argumento de configuración regional y admiten la carga selectiva / diferida mediante `importMode`.
+Ambos se combinan con el argumento de locale y admiten la carga selectiva / diferida mediante `importMode`.
 
 ## Cuándo usar cada uno
 
-- **Colecciones**: lista ordenada de elementos gestionados en archivos separados (entradas de preguntas frecuentes, publicaciones de blog, productos).
-- **Variantes**: alternativas de contenido nombradas para pruebas A/B, banners estacionales o indicadores de funciones (feature flags).
-- **Registros dinámicos**: contenido obtenido en tiempo de ejecución mediante un ID opaco (registros de CMS, copia específica del usuario).
+- **Colecciones** — lista ordenada de elementos gestionados en archivos separados (entradas de FAQ, artículos de blog, productos).
+- **Variantes** — alternativas de contenido con nombre o estructuradas:
+  - una variante de **cadena** para pruebas A/B, banners de temporada o feature flags;
+  - una variante de **objeto** para registros de CMS, contenido específico de usuario o cualquier contenido direccionado por un conjunto de campos (los antiguos «registros dinámicos»).
 
-## Desambiguación de selectores
+> Las versiones anteriores exponían un campo `meta` separado para el contenido indexado por registro. Se ha fusionado en `variant`: pase un **objeto** a `variant` en lugar de usar `meta`.
 
-Cuando hay múltiples selectores presentes en un diccionario, el orden de resolución es:
+## Desambiguación del selector
+
+Una clave puede declarar ambas dimensiones a la vez (p. ej. una colección cuyos elementos tienen cada uno una variante). Se resuelven en el orden:
 
 ```
-variant → meta → item
+variant → item
 ```
+
+Así, `{ variant: "promo" }` en una clave variante × item devuelve todos los elementos promo como un array, y añadir `{ item: 2 }` lo reduce a una sola entrada.