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

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

@@ -409,6 +409,16 @@ For more details, see the [HTML Content Documentation](https://github.com/aymeri
 
 ---
 
+## YAML & Markdown Content Files (v8.10.0)
+
+You can now declare content directly using the `.content.md` and `.content.yaml` file extensions. This is perfect for long-form content, blogs, documentation, and privacy policies.
+
+These files are fully editable from the Visual Editor, providing a streamlined workflow for non-technical team members.
+
+For more details, see the [YAML Content Files Documentation](https://intlayer.org/doc/concept/content#yaml-content-file) and [Markdown Content Files Documentation](https://intlayer.org/doc/concept/content/markdown).
+
+---
+
 ## Custom URL Rewrites
 
 Intlayer v8 introduces support for **Custom URL Rewrites**, allowing you to define locale-specific paths that differ from the standard `/locale/path` structure. This is a powerful feature for improving local SEO and providing a more natural user experience for non-English speakers.
@@ -753,6 +763,62 @@ export default {
   </Tab>
 </Tabs>
 
+## Unicode CLDR Plural Rules (v8.8.0)
+
+A new `plural` node helper has been introduced based on the plural rules defined by the Unicode CLDR Project, improving support for complex languages.
+
+```typescript fileName="src/openings.content.ts"
+import { plural, t, type Dictionary } from "intlayer";
+
+const openingsContent = {
+  key: "total_openings",
+  content: {
+    totalOpenings: t({
+      "en-GB": plural({
+        one: "{{count}} opening",
+        other: "{{count}} openings",
+      }),
+      en: plural({
+        one: "{{count}} opening",
+        other: "{{count}} openings",
+      }),
+      fr: plural({
+        one: "{{count}} offre",
+        other: "{{count}} offres",
+      }),
+    }),
+  },
+} satisfies Dictionary;
+
+export default openingsContent;
+```
+
+You can then pass the count dynamically in your framework component:
+
+```tsx
+import type { FC } from "react";
+import { useIntlayer } from "react-intlayer";
+
+const OpeningsComponent: FC<{ count: number }> = ({ count }) => {
+  const { totalOpenings } = useIntlayer("total_openings");
+
+  return (
+    <div>
+      {/* In British English:                          */}
+      {/*  count=0  → "0 openings"   (other)           */}
+      {/*  count=1  → "1 opening"    (one)             */}
+      {/*  count=2  → "2 openings"   (other)           */}
+      {/*  count=21 → "21 openings"  (other)           */}
+      <p>{totalOpenings(count)}</p>
+    </div>
+  );
+};
+```
+
+For more information, see the [Pluralization Documentation](https://intlayer.org/doc/concept/content/plural).
+
+---
+
 ## Content Schema Validation
 
 Intlayer v8 introduces schema validation for dictionaries. You can now define reusable validation schemas in your configuration using Zod and apply them to your content files. This ensures your content always adheres to the expected structure, catching errors at build time.
@@ -797,6 +863,34 @@ If the content doesn't match the schema (e.g., title is too short), the build pr
 
 ---
 
+## TypeScript: IntlayerNode Primitive Accessors
+
+The `IntlayerNode` type has been updated to allow calling primitive JavaScript methods directly on content nodes. This makes it possible to interact with your localised content directly as if it were a standard string, number, boolean, or array primitive.
+
+Supported across React, Preact, Solid, Svelte, Vue, and Angular.
+
+### String Example
+
+```typescript
+content.placeholder; // Returns IntlayerNode<string>
+content.placeholder.value; // Returns string
+content.placeholder.toString(); // Returns string
+content.placeholder.toLowerCase(); // Returns string
+String(content.placeholder); // Returns string
+content.placeholder.toUpperCase(); // Returns uppercased string
+content.placeholder.replace("a", "b"); // Returns modified string
+```
+
+### Array Example
+
+```typescript
+content.myArrayOfString             // Returns IntlayerNode<Array<string>>
+content.myArrayOfString.find(...)   // Returns element
+content.myArrayOfString.join(', ')  // Returns joined string
+```
+
+---
+
 ### Enhanced Automatic Content Detection
 
 In v8, Intlayer intelligently detects Markdown syntax, HTML tags, and variable insertions in your content strings. This means you can often omit helper functions like `md()`, `html()`, or `insert()`.
@@ -1002,6 +1096,17 @@ The Intlayer VSCode extension receives major updates in v8 to streamline your in
 
 ---
 
+## Tooling: C++ Watcher & OXC-based LSP (v8.12.0)
+
+Intlayer v8.12.0 brings major improvements to the developer experience:
+
+- **Parcel Watcher**: The content watcher has been migrated from `chokidar` to `@parcel/watcher`, leveraging native C++ file watching to provide faster updates and significantly lower memory consumption.
+- **New Language Server Protocol (LSP)**: A brand new LSP is now available. Built with OXC-based parsing, it helps your IDE and AI agents seamlessly link `useIntlayer('my-key')` calls with their corresponding `.content` files, and vice versa.
+
+For more details, see the [LSP Documentation](https://intlayer.org/doc/lsp).
+
+---
+
 ## Compiler Optimizations
 
 Intlayer v8 includes a new caching layer for the Markdown and HTML compiler. This ensures that identical content strings with the same configuration are only parsed once, significantly reducing the overhead during re-renders or when using the same content in multiple places.
@@ -1057,6 +1162,48 @@ Intlayer v8 includes a new caching layer for the Markdown and HTML compiler. Thi
 
 ---
 
+## Experimental Build Optimizations: Minify & Purge (v8.7.0)
+
+Intlayer v8.7.0 introduces new experimental build features in your `intlayer.config.ts` designed to optimise your production bundle:
+
+- **Dictionary Minification**: Minifies dictionary files to decrease size.
+- **Unused Key Purging**: Scans and removes unused translation keys from dictionaries, renaming active keys to short characters (e.g. `"products" -> "a"`, `"pricing" -> "b"`). This reduces bundle size by up to 5%.
+- **Disable TypeScript Checks**: Speed up builds by disabling TypeScript typechecking during the compilation step.
+
+```typescript fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  dictionary: {
+    importMode: "dynamic",
+  },
+  build: {
+    /**
+     * Minify the dictionaries to reduce the bundle size.
+     */
+    minify: true,
+
+    /**
+     * Purge the unused keys in dictionaries
+     */
+    purge: true,
+
+    /**
+     * Indicates if the build should check TypeScript types
+     */
+    checkTypes: false,
+  },
+};
+
+export default config;
+```
+
+---
+
 ## Flexibility: Unified Import Mode
 
 The `live` boolean property has been deprecated in favour of a more comprehensive `importMode` property. This allows for explicit definition of how dictionaries should be loaded: statically, dynamically, or via live sync.
@@ -1204,6 +1351,49 @@ Markdown and HTML content in Svelte now automatically parse to HTML when stringi
 
 ---
 
+## Angular Support: Vite Bundler (v8.11.0)
+
+For Angular users, Intlayer now natively supports the Vite bundler through a new custom esbuild plugin, speeding up development and build times.
+
+For details on configuration, see the [Angular Environment Documentation](https://intlayer.org/doc/environment/angular).
+
+---
+
+## Sitemap Generation (v8.6.0)
+
+Intlayer now generates sitemaps automatically based on your locales and routing mode. This is particularly useful for SEO optimisation in router architectures like TanStack Router:
+
+```typescript fileName="src/routes/sitemap.xml.ts"
+import { createFileRoute } from "@tanstack/react-router";
+import { generateSitemap } from "intlayer";
+
+const SITE_URL = (
+  import.meta.env.VITE_SITE_URL ?? "http://localhost:3000"
+).replace(/\/$/, "");
+
+export const Route = createFileRoute("/sitemap.xml")({
+  server: {
+    handlers: {
+      GET: async () => {
+        const sitemap = generateSitemap(
+          [
+            { path: "/", changefreq: "daily", priority: 1.0 },
+            { path: "/about", changefreq: "monthly", priority: 0.8 },
+          ],
+          { siteUrl: SITE_URL }
+        );
+
+        return new Response(sitemap, {
+          headers: { "Content-Type": "application/xml" },
+        });
+      },
+    },
+  },
+});
+```
+
+---
+
 ## Migration notes from v7
 
 ### Configuration Changes

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

@@ -1,15 +1,17 @@
 ---
 createdAt: 2026-06-14
-updatedAt: 2026-06-14
+updatedAt: 2026-07-08
 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, support for Collections and Variants, and self-hosting via Docker Compose.
 keywords:
   - Intlayer
   - Compatibility
   - Migration
   - Collections
   - Variants
-  - Dynamic Records
+  - CMS SDK
+  - Self-Hosting
+  - Docker
   - i18next
   - next-intl
   - vue-i18n
@@ -22,7 +24,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 +43,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 +104,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.
 
@@ -108,34 +112,48 @@ Intlayer v9 expands beyond static key-value objects, allowing dictionaries to de
 
 Define a CMS-managed list of ordered items (e.g. FAQs, products, or blog lists):
 
-```ts fileName="faq.content.ts"
+```ts fileName="faq.1.content.ts"
 import { t, type Dictionary } from "intlayer";
 
 export default {
   key: "faq",
-  content: [
-    {
-      question: t({ en: "What is Intlayer?", fr: "Qu'est-ce qu'Intlayer ?" }),
-      answer: t({ en: "An i18n toolkit.", fr: "Une boîte à outils i18n." }),
-    },
-  ],
+  item: 1,
+  content: {
+    question: t({ en: "What is Intlayer?", fr: "Qu'est-ce qu'Intlayer ?" }),
+    answer: t({ en: "An i18n toolkit.", fr: "Une boîte à outils i18n." }),
+  },
+} satisfies Dictionary;
+```
+
+```ts fileName="faq.2.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "faq",
+  item: 2,
+  content: {
+    question: t({ en: "Is it free?", fr: "Est-ce gratuit ?" }),
+    answer: t({ en: "Yes, open-source.", fr: "Oui, open-source." }),
+  },
 } satisfies Dictionary;
 ```
 
 #### Usage:
 
 ```ts
-// Fetch all items
+// Fetch all items as an array
 const allFaqs = useIntlayer("faq"); // -> { question: string, answer: string }[]
 
-// Fetch single item by index
-const faq = useIntlayer("faq", { item: 1 }); // -> { question: string, answer: string }
+// Fetch a single item by index
+const faq = useIntlayer("faq", { item: 2 }); // -> { question: string, answer: string }
 ```
 
 ### 2. Variants
 
 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 +173,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",
   },
@@ -179,28 +195,171 @@ export default {
 ```ts
 // Fetches only the requested item dynamically (requires Suspense)
 const product = useIntlayer("product-copy", {
-  id: "prod_123",
-  category: "books",
+  variant: { id: "prod_123", category: "books" },
 });
 ```
 
 ---
 
-## Dynamic Loading & Bundle Size Optimisations
+## `@intlayer/analytics`: content exposure tracking & A/B testing
+
+A new optional package, [`@intlayer/analytics`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/analytics.md), tells you which content is actually shown to your visitors — and closes the loop on **Collections & Variants** by letting you A/B test content and measure conversions per variant.
+
+- **Provider-level tracking**: `IntlayerProvider` (React / Next.js / React Native) automatically records `page_view` events on load, route change, and locale change.
+- **Node-level tracking**: every `useIntlayer` resolution reports a `content_exposure` event — which dictionary key, key path, locale, and (when applicable) A/B **variant** was displayed. Repeated exposures within a flush window are coalesced.
+- **Deterministic A/B assignment**: `getVariant(experimentKey, variants)` assigns each session to a variant with **no server round-trip**, so there is no flicker before first render.
+- **`useConversion()`**: attribute a goal (signup, click, purchase…) to the variant a session was exposed to.
+- **Zero cost when not installed**: same tree-shakeable pattern as `@intlayer/editor` — dynamic `import()` wrapped in `try/catch`, plus a compile-time env var (`INTLAYER_ANALYTICS_ENABLED`) that dead-code-eliminates the whole integration for apps that don't opt in.
+- **No new config schema**: reuses `editor.backendURL` (ingestion endpoint / self-hosting) and `editor.clientId` (project key, also the enable switch).
+- **Privacy-respecting**: anonymous session hashing (SHA-256, no raw ids stored), no IP storage, coarse country-only geolocation, batched requests roughly every 20 seconds.
+- **Dashboard**: a new **Analytics** page (shown in the sidebar once a project is selected) reports active users, users today, users over the last 7/30/90 days, a visitor evolution graph, and Locales vs. Location breakdowns.
+
+```tsx fileName="CTAButton.tsx" codeFormat="tsx"
+import { useConversion } from "react-intlayer";
+
+const CTAButton = () => {
+  const trackConversion = useConversion();
+
+  return (
+    <button
+      onClick={() =>
+        trackConversion({
+          experimentKey: "homepage-hero",
+          variant: "black_friday",
+          goal: "cta_click",
+        })
+      }
+    >
+      Get started
+    </button>
+  );
+};
+```
 
-To keep bundles extremely small, Intlayer v9 supports dynamic lazy loading.
+```bash packageManager="npm"
+npm install @intlayer/analytics
+```
+
+Available today for React, Next.js, and React Native (via `react-intlayer`); other framework bindings (Vue, Svelte, Angular, …) are planned, following the same rollout pattern as `@intlayer/editor`. See the [Analytics documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/analytics.md) for the full guide.
+
+---
 
-In your configuration, set `importMode` to `'dynamic'` or `'fetch'`:
+## Vite Plugin: Bundled Compiler & Proxy
+
+The `intlayer()` Vite plugin now bundles the **compiler** and the **locale-routing proxy** directly, so most projects only need a single plugin in `vite.config.ts`:
+
+```ts fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+- **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
+
+A new `routing.enableProxy` option controls whether the locale-routing proxy is plugged in. It defaults to `true`. Disable it when you want to handle locale routing yourself:
 
 ```ts fileName="intlayer.config.ts"
-export default {
-  dictionary: {
-    importMode: "dynamic", // "static" | "dynamic" | "fetch"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  routing: {
+    enableProxy: false, // Default: true
   },
 };
+
+export default config;
+```
+
+The standalone `intlayerCompiler()` and `intlayerProxy()` plugins remain exported for advanced setups. Registering them alongside `intlayer()` is safe — each plugin deduplicates itself and runs only once.
+
+---
+
+## 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.
+
+---
+
+## CMS SDK: use Intlayer as a headless content database
+
+Intlayer v9 ships a clean, auto-authenticating SDK in `@intlayer/api` to interact with the CMS programmatically — fetch projects, fetch dictionaries, and push or update them from your own server, scripts, or CI. Authentication (OAuth2 `client_credentials`) is handled and refreshed for you.
+
+The SDK is split into **two separate imports** so your bundle includes only the domains you actually use:
+
+1. `createIntlayerCMS` — a lightweight **authenticator** holding the credentials and the managed token (no domain client bundled).
+2. `dictionaryEndpoint`, `projectEndpoint`, … — per-domain **endpoint binders**, each imported from its own subpath.
+
+```ts fileName="cms.ts"
+import { createIntlayerCMS } from "@intlayer/api";
+import { dictionaryEndpoint } from "@intlayer/api/dictionary";
+
+// Config is optional: credentials fall back to INTLAYER_CLIENT_ID /
+// INTLAYER_CLIENT_SECRET resolved by `@intlayer/config/built`.
+const cms = createIntlayerCMS();
+
+// Read
+const { data: dictionaries } = await dictionaryEndpoint(cms).getDictionaries();
+
+// Write — use the CMS like a database
+await dictionaryEndpoint(cms).pushDictionaries([myDictionary]);
+```
+
+> Security: the CMS credentials grant write access to your content. Only ever create the authenticator on the **server side** — never ship `clientId` / `clientSecret` to the browser.
+
+---
+
+## Self-Hosting
+
+Intlayer v9 ships first-class support for running your own Intlayer instance with a single command. No Intlayer Cloud account required.
+
+```sh
+curl -fsSL https://intlayer.org/install.sh | sh
 ```
 
-At build time, `@intlayer/swc` and `@intlayer/babel` scan your files and replace `useIntlayer` / `getIntlayer` calls with tree-shakeable wrappers (`useDictionary` / `useDictionaryDynamic`). Only the content required for the selected collection item, variant, or locale is loaded, preventing your production bundle from containing unused translations.
+The installer downloads a `docker-compose.yml` and a `.env`, auto-generates the required secrets, and runs `docker compose up -d`. Everything — the dashboard, the API, the database, object storage, and transactional email — runs locally in containers.
 
 ---
 
@@ -208,13 +367,17 @@ At build time, `@intlayer/swc` and `@intlayer/babel` scan your files and replace
 
 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)
+- [Analytics - Content exposure tracking & A/B testing](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/analytics.md)
 - [Configuration Reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md)
+- [CMS SDK - Programmatic access with @intlayer/api](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_CMS.md)
+- [Self-Hosting Guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/self_hosting.md)

package/docs/en-GB/roadmap.md

@@ -29,6 +29,12 @@ Intlayer is a content management and internationalisation solution designed to s
 
 ---
 
+## Table of Contents
+
+<TOC/>
+
+---
+
 ## Current Features
 
 ### 1. Content Declaration