@intlayer/docs 9.3.3 → 9.4.0

package/docs/en/bundle_optimization.md

@@ -476,7 +476,7 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
-> Minification is skipped when `optimize` is `false` or when `editor.enabled` is `true` (the visual editor requires the original field names to allow editing).
+> Minification is skipped when `optimize` is `false`. When `editor.enabled` is `true` it still runs, but without the field-renaming step — the visual editor resolves edits by `keyPath`, so the original field names have to survive.
 
 > On Next.js, minification is also skipped when `@intlayer/swc` is not installed or cannot be loaded (Next.js below 16.1.0). The plugin is the half that rewrites the source accesses, so renaming the dictionaries without it would leave your code reading field names that no longer exist.
 
@@ -508,7 +508,7 @@ export default config;
 { "title": "…", "subtitle": "…" }
 ```
 
-> Purge is skipped when `optimize` is `false` or when `editor.enabled` is `true`. On Next.js it is additionally skipped when `@intlayer/swc` is unavailable, and when compat-adapter callers are configured.
+> Purge is skipped when `optimize` is `false`. It stays active when `editor.enabled` is `true` — a purged field is read by no component, so the editor never renders it. On Next.js it is additionally skipped when `@intlayer/swc` is unavailable, and when compat-adapter callers are configured.
 
 > Purge is also skipped conservatively when a source file cannot be parsed, or when the result of `useIntlayer` is assigned to a variable and passed around in ways the static analyser cannot follow (e.g. spread into an object, passed as a prop without destructuring). In those cases the full dictionary is kept.
 

package/docs/en/cli/index.md

@@ -127,6 +127,8 @@ To see how to configure available locales, or other parameters, refer to the [co
 
 - **[Login](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/login.md)** - Authenticate with the Intlayer CMS and get access credentials
 
+> `intlayer login` issues an **access key** (`clientId` / `clientSecret`) that every credentialed command uses. The secret is a server-side credential and never reaches your client bundle — see [Keeping the access key safe](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/login.md#keeping-the-access-key-safe).
+
 ### Core Commands
 
 - **[Build Dictionaries](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/build.md)** - Build your dictionaries from content declaration files

package/docs/en/cli/login.md

@@ -118,6 +118,34 @@ INTLAYER_CLIENT_SECRET=your_client_secret
 }
 ```
 
+## Keeping the access key safe
+
+`intlayer login` issues an **access key**: a `clientId` / `clientSecret` pair that every credentialed command (`push`, `pull`, `fill`, `configuration push`, `live`, …) uses to authenticate.
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+  },
+};
+
+export default config;
+```
+
+> **`clientSecret` is a server-side credential.** It grants full project-scoped API access — reading and writing your dictionaries, your project and your organization. Keep it in `.env` (git-ignored) or your CI secret store, and never inline it in the configuration file.
+
+Intlayer enforces this rather than only documenting it:
+
+- `clientSecret` is **stripped from the configuration your bundler inlines**, so it cannot reach a browser bundle whatever framework integration you use. It is only ever read server-side, at runtime, from the environment.
+- `clientId` is different: it is the **public** project key, safe to ship, and used by [`@intlayer/analytics`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/analytics.md#how-events-are-authenticated) to obtain a short-lived, ingest-only token.
+
+Commenting `clientId` out is enough to disable every credentialed behaviour — remote dictionary fetching, CMS access, analytics — even when the environment variables are still defined.
+
+For CI pipelines, prefer the [`ci` command](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/ci.md), which injects the credentials for the duration of a single run instead of persisting them.
+
 ## Manual Configuration
 
 If the browser doesn't open automatically, you can manually visit the URL displayed in the terminal.

package/docs/en/configuration.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-08-06
+updatedAt: 2026-08-22
 title: Configuration
 description: Learn how to configure Intlayer for your application. Understand the various settings and options available to customize Intlayer to your needs.
 keywords:
@@ -14,6 +14,9 @@ slugs:
   - concept
   - configuration
 history:
+  - version: 9.3.3
+    date: 2026-08-22
+    changes: "Enable analytics by default — active as soon as `@intlayer/analytics` is installed"
   - version: 9.1.3
     date: 2026-08-06
     changes: "Make `routing.enableProxy` tri-state: unset (auto), `true`, `false`"
@@ -383,8 +386,8 @@ const config: IntlayerConfig = {
   analytics: {
     /**
      * Whether analytics collection is enabled (page views, content exposures, A/B events).
-     * Requires `editor.clientId` to be set for attribution.
-     * Default: false
+     * Requires `@intlayer/analytics` to be installed, and `editor.clientId` to be set for attribution.
+     * Default: true
      */
     enabled: true,
 
@@ -743,13 +746,13 @@ Defines settings related to the integrated editor, including server port and act
 
 Defines settings related to Intlayer analytics: collecting which content is actually shown to users (page views, content exposures) and powering content A/B testing.
 
-Analytics is strictly opt-in: nothing is collected unless `analytics.enabled` is explicitly set to `true` **and** a project key (`editor.clientId`) is configured for attribution. When disabled (the default), the whole analytics integration is dead-code-eliminated from your application bundle.
+Analytics is opt-out: it is enabled by default, and starts collecting as soon as the [`@intlayer/analytics`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/analytics.md) package is installed **and** a project key (`editor.clientId`) is configured for attribution. Set `analytics.enabled` to `false` — or leave the package uninstalled — and the whole analytics integration is dead-code-eliminated from your application bundle.
 
-| Field           | Description                                                               | Type      | Default | Example | Note                                                                                                                  |
-| --------------- | ------------------------------------------------------------------------- | --------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
-| `enabled`       | Enables analytics collection (page views, content exposures, A/B events). | `boolean` | `false` | `true`  | Requires `editor.clientId` to be set for attribution; otherwise analytics stays disabled even if `enabled` is `true`. |
-| `flushInterval` | Milliseconds between automatic batched flushes to the backend.            | `number`  | `20000` | `10000` |                                                                                                                       |
-| `sampleRate`    | Fraction of sessions to record, from `0` (none) to `1` (all).             | `number`  | `1`     | `0.5`   | Sampling is deterministic per session, so a recorded session reports all of its events (no partial funnels).          |
+| Field           | Description                                                               | Type      | Default | Example | Note                                                                                                                                                            |
+| --------------- | ------------------------------------------------------------------------- | --------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `enabled`       | Enables analytics collection (page views, content exposures, A/B events). | `boolean` | `true`  | `false` | Requires `@intlayer/analytics` to be installed and `editor.clientId` to be set for attribution; otherwise analytics stays disabled even if `enabled` is `true`. |
+| `flushInterval` | Milliseconds between automatic batched flushes to the backend.            | `number`  | `20000` | `10000` |                                                                                                                                                                 |
+| `sampleRate`    | Fraction of sessions to record, from `0` (none) to `1` (all).             | `number`  | `1`     | `0.5`   | Sampling is deterministic per session, so a recorded session reports all of its events (no partial funnels).                                                    |
 
 ---
 

package/docs/en/custom_domains.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-04-03
-updatedAt: 2026-04-03
+updatedAt: 2026-08-22
 title: Custom Domains
 description: Configure domain-based locale routing in Intlayer to serve different locales from dedicated hostnames.
 keywords:
@@ -14,6 +14,9 @@ slugs:
   - concept
   - custom_domains
 history:
+  - version: 9.4.0
+    date: 2026-08-22
+    changes: "Narrow the return type of getLocalizedUrl and getLocalizedPath from routing.domains, and emit domain-aware sitemap alternates."
   - version: 8.7.0
     date: 2026-04-03
     changes: "Add domain-based locale routing via routing.domains configuration."
@@ -104,7 +107,7 @@ getLocalizedUrl("/about", "fr", { currentDomain: "intlayer.zh" });
 
 1. The hostname of an absolute input URL (e.g. `https://intlayer.org/about` → `intlayer.org`).
 2. `window.location.hostname` in browser environments.
-3. If neither is available (SSR without explicit option), a relative URL is returned for same-domain locales and no absolute URL is produced - this is the safe fallback.
+3. If neither is available (SSR, static generation), the absolute URL on the locale's domain is returned - this is the safe fallback. A relative URL could not be trusted there: the prefix of an exclusive-domain locale is already stripped, so it would resolve to the wrong locale on whichever domain happens to serve the page.
 
 ```ts
 // Browser - window.location.hostname === 'intlayer.org'
@@ -133,6 +136,38 @@ getMultilingualUrls("/about", { currentDomain: "intlayer.org" });
 
 These absolute URLs are ready to use in `<link rel="alternate" hreflang="...">` tags for SEO.
 
+## Type Inference
+
+`routing.domains` is serialized into the generated module augmentation, so
+`getLocalizedUrl` and `getLocalizedPath` narrow their return type to the exact
+URL a domain-routed locale resolves to — the prefix suppression included.
+
+```ts
+// routing: { mode: 'prefix-no-default', domains: { en: 'intlayer.org', zh: 'intlayer.zh' } }
+
+getLocalizedUrl("/about", "zh");
+//     ^? "https://intlayer.zh/about" | "/about"
+
+getLocalizedPath("/about", "zh");
+//     ^? "/about"   (never an origin, and no /zh/ prefix)
+```
+
+The URL type is the **union** of the two values the function can return: the
+absolute URL on the locale's domain, and the relative one it returns when the
+page being rendered already lives on that domain. `getLocalizedPath` has no such
+ambiguity - it never emits an origin - so it stays a single literal.
+
+Locales that share a domain keep their normal prefix in the type as well:
+
+```ts
+getLocalizedUrl("/about", "fr");
+//     ^? "https://intlayer.org/fr/about" | "/fr/about"
+```
+
+> Regenerate the types (`npx intlayer build`, or any dev server run) after
+> changing `routing.domains` - the narrowing comes from the generated
+> `__RoutingRegistry`, not from the config file itself.
+
 ## Proxy Behaviour
 
 ### Next.js
@@ -252,3 +287,5 @@ This produces:
 | `getLocalizedUrl(url, locale, { currentDomain })` | Returns relative or absolute URL depending on whether the target locale is on the current domain. |
 | `getMultilingualUrls(url, { currentDomain })`     | Returns a locale-keyed map of localized URLs, mixing relative and absolute as needed.             |
 | `getPrefix(locale, { domains })`                  | Returns an empty prefix for exclusive-domain locales, normal prefix otherwise.                    |
+| `getLocalizedPath(path, locale, { domains })`     | Returns the path served on the locale's domain, without its prefix - never an origin.             |
+| `generateSitemap(entries, { domains })`           | Emits `hreflang` alternates pointing at each locale's own domain.                                 |

package/docs/en/dictionary/html.md

@@ -245,7 +245,7 @@ You can configure HTML rendering globally for your entire application. This is i
 
 <Tabs group="framework">
   <Tab label="React / Next.js" value="react">
-  
+
     ```tsx fileName="AppProvider.tsx"
     import { HTMLProvider } from "react-intlayer/html";
 
@@ -327,7 +327,7 @@ You can configure HTML rendering globally for your entire application. This is i
 
   </Tab>
   <Tab label="Svelte" value="svelte">
-   
+
     ```svelte fileName="App.svelte"
     <script lang="ts">
       import { HTMLProvider } from "svelte-intlayer/html";
@@ -364,7 +364,7 @@ You can configure HTML rendering globally for your entire application. This is i
 
   </Tab>
   <Tab label="Preact" value="preact">
-   
+
     ```tsx fileName="AppProvider.tsx"
     import { HTMLProvider } from "preact-intlayer/html";
 
@@ -400,7 +400,7 @@ You can configure HTML rendering globally for your entire application. This is i
 
   </Tab>
   <Tab label="Solid" value="solid">
-   
+
     ```tsx fileName="AppProvider.tsx"
     import { HTMLProvider } from "solid-intlayer/html";
 
@@ -460,9 +460,9 @@ You can configure HTML rendering globally for your entire application. This is i
     export const appConfig: ApplicationConfig = {
       providers: [
         createIntlayerHTMLProvider({
-          renderMarkdown: async (html) => {
-            const { renderMarkdown } = await import('angular-intlayer/html');
-            return renderMarkdown(html);
+          renderHTML: async (html) => {
+            const { renderHTML } = await import('angular-intlayer/html');
+            return renderHTML(html);
           },
         }),
       ],
@@ -519,9 +519,9 @@ If you need to render raw HTML strings or have more control over the component m
 
   </Tab>
   <Tab label="Vue" value="vue">
-   
+
     #### `<HTMLRenderer />` Component
-   
+
     ```vue
     <script setup>
     import { HTMLRenderer } from "vue-intlayer/html";
@@ -534,9 +534,9 @@ If you need to render raw HTML strings or have more control over the component m
 
   </Tab>
   <Tab label="Svelte" value="svelte">
-  
+
     #### `<HTMLRenderer />` Component
-   
+
     ```svelte
     <script lang="ts">
     import { HTMLRenderer } from "svelte-intlayer/html";
@@ -568,9 +568,9 @@ If you need to render raw HTML strings or have more control over the component m
 
   </Tab>
   <Tab label="Preact" value="preact">
-   
+
     #### `<HTMLRenderer />` Component
-   
+
     ```tsx
     import { HTMLRenderer } from "preact-intlayer/html";
 
@@ -599,9 +599,9 @@ If you need to render raw HTML strings or have more control over the component m
 
   </Tab>
   <Tab label="Solid" value="solid">
-   
+
     #### `<HTMLRenderer />` Component
-   
+
     ```tsx
     import { HTMLRenderer } from "solid-intlayer/html";
 
@@ -640,7 +640,7 @@ If you need to render raw HTML strings or have more control over the component m
       constructor(private markdownService: IntlayerHTMLService) {}
 
       renderHTML(html: string) {
-        return this.markdownService.renderMarkdown(html);
+        return this.markdownService.renderHTML(html);
       }
     }
     ```

package/docs/en/dynamic_dictionaries/variants.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-06-12
-updatedAt: 2026-08-04
+updatedAt: 2026-08-22
 title: Variants
 description: Use the variant metadata field in Intlayer content files to declare named or structured content alternatives — A/B tests, seasonal banners, feature-flagged copy, CMS records, user-specific content — and switch between them at runtime without code changes.
 keywords:
@@ -17,6 +17,9 @@ slugs:
   - concept
   - variants
 history:
+  - version: 9.4.0
+    date: 2026-08-22
+    changes: "Update to Next.js >= 9.4.0 architecture"
   - version: 9.0.0
     date: 2026-06-12
     changes: "Release of the variants feature"
@@ -523,23 +526,43 @@ Declare the variant once on the provider instead, exactly like `locale`:
 
   </Tab>
   <Tab label="Next.js" value="nextjs">
-    ```tsx fileName="layout.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
-    import { IntlayerServerProvider } from "next-intlayer/server";
-    import { IntlayerClientProvider } from "next-intlayer";
-
-    export default async function Layout({ children, params }) {
-      const { locale } = await params;
-      const schoolType = await getSchoolType();
-
-      return (
-        <IntlayerServerProvider locale={locale} variant={schoolType}>
-          <IntlayerClientProvider locale={locale} variant={schoolType}>
-            {children}
-          </IntlayerClientProvider>
-        </IntlayerServerProvider>
-      );
-    }
-    ```
+    <Tabs>
+      <Tab label="Intlayer >=9.4" value=">=9.4">
+        ```tsx fileName="layout.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+        import { IntlayerProvider } from "next-intlayer/server";
+
+        export default async function Layout({ children, params }) {
+          const { locale } = await params;
+          const schoolType = await getSchoolType();
+
+          return (
+            <IntlayerProvider locale={locale} variant={schoolType}>
+              {children}
+            </IntlayerProvider>
+          );
+        }
+        ```
+      </Tab>
+      <Tab label="Intlayer <9.4" value="<9.4">
+        ```tsx fileName="layout.tsx" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+        import { IntlayerServerProvider } from "next-intlayer/server";
+        import { IntlayerClientProvider } from "next-intlayer";
+
+        export default async function Layout({ children, params }) {
+          const { locale } = await params;
+          const schoolType = await getSchoolType();
+
+          return (
+            <IntlayerServerProvider locale={locale} variant={schoolType}>
+              <IntlayerClientProvider locale={locale} variant={schoolType}>
+                {children}
+              </IntlayerClientProvider>
+            </IntlayerServerProvider>
+          );
+        }
+        ```
+      </Tab>
+    </Tabs>
 
   </Tab>
   <Tab label="Vue" value="vue">

package/docs/en/formatters.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-01-20
+updatedAt: 2026-08-22
 title: Formatters
 description: Locale-aware formatting utilities based on Intl for numbers, percentages, currency, dates, relative time, units, and compact notation. Includes a cached Intl helper.
 keywords:
@@ -19,6 +19,9 @@ slugs:
   - doc
   - formatters
 history:
+  - version: 9.4.0
+    date: 2026-08-22
+    changes: "Update to Next.js >= 9.4.0 architecture"
   - version: 8.0.0
     date: 2026-01-20
     changes: "Add useIntl"
@@ -103,7 +106,7 @@ const PriceDisplay = () => {
 
 ### Available Hooks
 
-All hooks automatically use the locale from `IntlayerProvider` or `IntlayerServerProvider`.
+All hooks automatically use the locale from `IntlayerProvider` (or `IntlayerClientProvider` / `IntlayerServerProvider`).
 
 | Hook                | Description                        | Example Output                |
 | ------------------- | ---------------------------------- | ----------------------------- |

package/docs/en/intlayer_with_adonisjs.md

@@ -254,9 +254,11 @@ import { Locales, type IntlayerConfig } from "intlayer";
 
 const config: IntlayerConfig = {
   // ... Other configuration options
-  middleware: {
-    headerName: "my-locale-header",
-    cookieName: "my-locale-cookie",
+  routing: {
+    storage: [
+      { type: "header", name: "my-locale-header" },
+      { type: "cookie", name: "my-locale-cookie" },
+    ],
   },
 };