@intlayer/docs 8.12.5-canary.0 → 9.0.0-canary.3

package/docs/en/releases/v8.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-09-22
-updatedAt: 2026-01-26
+updatedAt: 2026-06-14
 title: New Intlayer v8 - What's new?
 description: Discover what's new in Intlayer v8. Major improvements in developer experience, content validation, and dictionary management.
 keywords:
@@ -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,58 @@ 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: 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 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 +859,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 localized 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 +1092,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 +1158,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 optimize 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 favor 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 +1347,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 optimization 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/releases/v9.md

@@ -0,0 +1,220 @@
+---
+createdAt: 2026-06-14
+updatedAt: 2026-06-14
+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.
+keywords:
+  - Intlayer
+  - Compatibility
+  - Migration
+  - Collections
+  - Variants
+  - Dynamic Records
+  - i18next
+  - next-intl
+  - vue-i18n
+slugs:
+  - doc
+  - releases
+  - v9
+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**.
+
+## Table of contents
+
+<TOC levels={[2]} maxDepth={1} />
+
+---
+
+## Compat Adapter Packages
+
+Migrating to Intlayer from popular i18n libraries is now easier than ever. We have created five compat packages that expose the **exact same public APIs** as standard i18n libraries but delegate all translation work to Intlayer at runtime.
+
+### Expose Same Public API with Strict Typing
+
+By replacing imports, you get all the benefits of Intlayer (including compile-time type safety against your actual dictionaries) with minimal code changes:
+
+- `@intlayer/i18next`
+- `@intlayer/react-i18next`
+- `@intlayer/next-intl`
+- `@intlayer/next-i18next`
+- `@intlayer/vue-i18n`
+
+For example, simply change:
+
+```ts
+import { useTranslation } from "react-i18next";
+```
+
+to:
+
+```ts
+import { useTranslation } from "@intlayer/react-i18next";
+```
+
+Your keys will now be **strictly typed** against your Intlayer dictionaries, offering full dot-path auto-completion in your IDE!
+
+### Bundler Alias Plugins (Vite, Next.js, Turbopack)
+
+To allow migrating without rewriting all your import statements manually, each compat adapter package includes a **custom bundler plugin** (Vite or Next.js) under the `/plugin` subpath.
+
+These plugins automatically rewrite existing imports (e.g. `react-i18next` or `next-intl`) to their `@intlayer/*` equivalents at build time.
+
+#### Next.js (Webpack / Turbopack) Example
+
+Instead of `withIntlayer`, wrap your Next.js configuration with the compat plugin:
+
+```ts fileName="next.config.ts"
+import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
+import type { NextConfig } from "next";
+
+const withIntlayer = createNextI18nPlugin();
+const nextConfig: NextConfig = {};
+
+export default withIntlayer(nextConfig);
+```
+
+#### Vite (React, Vue, Solid, Svelte) Example
+
+```ts fileName="vite.config.ts"
+import vueI18nVitePlugin from "@intlayer/vue-i18n/plugin";
+
+export default defineConfig({
+  plugins: [vueI18nVitePlugin()],
+});
+```
+
+---
+
+## Mutualized Runtime Resolver
+
+All compat adapters now route translation resolution through a single, highly optimized runtime parser: `@intlayer/core/messageFormat`.
+
+- **Interpolate Message**: Resolves standard `{{var}}` (whitespace & dot-paths), ICU formatted args (`{v, number, percent}` etc.), and bare `{var}` templates.
+- **Message Node Resolver**: Resolves nested nodes: `insert()`, `plural()` (CLDR plural rules), `enu()` (enumeration), `gender()`, HTML tags, arrays, and callable function nodes.
+- **Tokenized Tag Parser**: Supports inline XML/HTML tags and numbered tags (e.g., `<1>children</1>`) to power rich-text rendering out of the box.
+
+---
+
+## Feature Spec: Collections, Variants & Dynamic Records
+
+Intlayer v9 expands beyond static key-value objects, allowing dictionaries to declare dynamic layout structures that are fully typed end-to-end.
+
+### 1. Collections
+
+Define a CMS-managed list of ordered items (e.g. FAQs, products, or blog lists):
+
+```ts fileName="faq.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." }),
+    },
+  ],
+} satisfies Dictionary;
+```
+
+#### Usage:
+
+```ts
+// Fetch all items
+const allFaqs = useIntlayer("faq"); // -> { question: string, answer: string }[]
+
+// Fetch single item by index
+const faq = useIntlayer("faq", { item: 1 }); // -> { question: string, answer: string }
+```
+
+### 2. Variants
+
+Deliver A/B tests, seasonal headers, feature flags, or custom landing pages:
+
+```ts fileName="hero.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "hero-banner",
+  variant: "default",
+  content: {
+    control: t({ en: "Welcome", fr: "Bienvenue" }),
+    black_friday: t({ en: "Shop now", fr: "Acheter maintenant" }),
+  },
+} satisfies Dictionary;
+```
+
+#### Usage:
+
+```ts
+const banner = useIntlayer("hero-banner", { variant: "black_friday" });
+```
+
+### 3. Dynamic Records
+
+Define dictionaries whose entries are loaded dynamically at runtime via query IDs:
+
+```ts fileName="product.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "product-copy",
+  meta: {
+    id: "prod_123",
+    category: "books",
+  },
+  content: {
+    title: t({ en: "Clean Code", fr: "Code Propre" }),
+  },
+} satisfies Dictionary;
+```
+
+#### Usage:
+
+```ts
+// Fetches only the requested item dynamically (requires Suspense)
+const product = useIntlayer("product-copy", {
+  id: "prod_123",
+  category: "books",
+});
+```
+
+---
+
+## Dynamic Loading & Bundle Size Optimizations
+
+To keep bundles extremely small, Intlayer v9 supports dynamic lazy loading.
+
+In your configuration, set `importMode` to `'dynamic'` or `'fetch'`:
+
+```ts fileName="intlayer.config.ts"
+export default {
+  dictionary: {
+    importMode: "dynamic", // "static" | "dynamic" | "fetch"
+  },
+};
+```
+
+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.
+
+---
+
+## 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:
+
+- **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.
+
+---
+
+## 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)
+- [Configuration Reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md)

package/docs/en-GB/cli/doc-review.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-11
-updatedAt: 2025-11-22
+updatedAt: 2026-06-17
 title: Review Document
 description: Learn how to review documentation files for quality, consistency, and completeness across different locales.
 keywords:
@@ -15,6 +15,10 @@ slugs:
   - concept
   - cli
   - doc-review
+history:
+  - version: 9.0.0
+    date: 2026-06-17
+    changes: "Add --log option"
 author: aymericzip
 ---
 
@@ -55,8 +59,110 @@ For most use cases,
 
 ## Arguments:
 
-The `doc review` command accepts the same arguments as `doc translate`, allowing you to review specific documentation files and apply quality checks.
+**File list options:**
 
-If you have activated one of the git options, the command will only review the parts of the files that are being changed. The script will process by chunking the file and reviewing each chunk. If there are no changes in the chunk, the script will skip it to speed up the review process and limit the AI Provider API cost.
+- **`--doc-pattern [docPattern...]`**: Glob patterns to match documentation files to review.
 
-For a complete list of arguments, see the [Translate Document](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/doc-translate.md) command documentation.
+  > Example: `npx intlayer doc review --doc-pattern "docs/**/*.md" "src/**/*.mdx"`
+
+- **`--excluded-glob-pattern [excludedGlobPattern...]`**: Glob patterns to exclude from review.
+
+  > Example: `npx intlayer doc review --excluded-glob-pattern "docs/internal/**"`
+
+- **`--skip-if-modified-before [skipIfModifiedBefore]`**: Skip the file if it has been modified before the specified time.
+  - Can be an absolute time such as "2025-12-05" (string or Date)
+  - Can be a relative time in ms `1 * 60 * 60 * 1000` (1 hour)
+  - This option checks the update time of the file using the `fs.stat` method. Therefore, it could be affected by Git or other tools that modify the file.
+
+  > Example: `npx intlayer doc review --skip-if-modified-before "2025-12-05"`
+
+- **`--skip-if-modified-after [skipIfModifiedAfter]`**: Skip the file if it has been modified within the specified time.
+  - Can be an absolute time such as "2025-12-05" (string or Date)
+  - Can be a relative time in ms `1 * 60 * 60 * 1000` (1 hour)
+  - This option checks the update time of the file using the `fs.stat` method. Therefore, it could be affected by Git or other tools that modify the file.
+
+  > Example: `npx intlayer doc review --skip-if-modified-after "2025-12-05"`
+
+- **`--skip-if-exists`**: Skip the file if it already exists.
+
+  > Example: `npx intlayer doc review --skip-if-exists`
+
+**Review mode options:**
+
+- **`--log`**: Log-only mode. Do not translate with AI; instead log the blocks that need attention (with line numbers and content) for the base and target locales, to help another agent generate the translations.
+
+  > Example: `npx intlayer doc review --log`
+
+**Entry output options:**
+
+- **`--locales [locales...]`**: Target locales to review documentation for.
+
+  > Example: `npx intlayer doc review --locales fr es de`
+
+- **`--base-locale [baseLocale]`**: Source locale (base document) to compare with.
+
+  > Example: `npx intlayer doc review --base-locale en`
+
+**File processing options:**
+
+- **`--nb-simultaneous-file-processed [nbSimultaneousFileProcessed]`**: Number of files to process simultaneously for review.
+
+  > Example: `npx intlayer doc review --nb-simultaneous-file-processed 5`
+
+**AI options:**
+
+- **`--model [model]`**: The AI model to use for review (e.g., `gpt-3.5-turbo`).
+- **`--provider [provider]`**: The AI provider to use for review.
+- **`--temperature [temperature]`**: Temperature setting for the AI model.
+- **`--api-key [apiKey]`**: Provide your own API key for the AI service.
+- **`--application-context [applicationContext]`**: Provide additional context for the AI review.
+- **`--data-serialization [dataSerialization]`**: The data serialization format to use for the AI features of Intlayer. Options: `json` (standard, reliable), `toon` (fewer tokens, less consistent).
+- **`--custom-prompt [prompt]`**: Customise the base prompt used for review. (Note: For most use cases, the `--custom-instructions` option is recommended instead.)
+
+  > Example: `npx intlayer doc review --model deepseek-chat --provider deepseek --temperature 0.5 --api-key sk-1234567890 --application-context "My application is a cat store"`
+
+**Environment variables options:**
+
+- **`--env`**: Specify the environment (e.g., `development`, `production`).
+- **`--env-file [envFile]`**: Provide a custom environment file to load variables from.
+- **`--base-dir`**: Specify the base directory for the project.
+- **`--no-cache`**: Disable the cache.
+
+  > Example: `npx intlayer doc review --base-dir ./docs --env-file .env.production.local`
+
+**Log options:**
+
+- **`--verbose`**: Enable verbose logging for debugging. (defaults to true when using CLI)
+
+  > Example: `npx intlayer doc review --verbose`
+
+**Custom instructions options:**
+
+- **`--custom-instructions [customInstructions]`**: Custom instructions added to the prompt. Useful for applying specific rules regarding formatting, URL translation, etc.
+
+  > Example: `npx intlayer doc review --custom-instructions "Avoid translating URLs, and keep the markdown format"`
+
+  > Example: `npx intlayer doc review --custom-instructions "$(cat ./instructions.md)"`
+
+**Git options:**
+
+- **`--git-diff`**: Only run on files that include changes from base (default `origin/main`) to current branch (default: `HEAD`).
+- **`--git-diff-base`**: Specify the base reference for git diff (default `origin/main`).
+- **`--git-diff-current`**: Specify the current reference for git diff (default: `HEAD`).
+- **`--uncommitted`**: Include uncommitted changes.
+- **`--unpushed`**: Include unpushed changes.
+- **`--untracked`**: Include untracked files.
+
+  > Example: `npx intlayer doc review --git-diff --git-diff-base origin/main --git-diff-current HEAD`
+
+  > Example: `npx intlayer doc review --uncommitted --unpushed --untracked`
+
+> Note that the output file path will be determined by replacing the following patterns:
+>
+> - `/{{baseLocale}}/` with `/{{locale}}/` (Unix)
+> - `\{{baseLocale}}\` with `\{{locale}}\` (Windows)
+> - `_{{baseLocale}}.` with `_{{locale}}.`
+> - `{{baseLocale}}_` with `{{locale}}_`
+> - `.{{baseLocaleName}}.` with `.{{localeName}}.`
+>
+> If the pattern is not found, the output file will add `.{{locale}}` to the file extension. For example, `./my/file.md` will be reviewed and updated to `./my/file.fr.md` for the French locale.

package/docs/en-GB/cli/index.md

@@ -17,7 +17,7 @@ slugs:
   - concept
   - cli
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-11
     changes: "Added scan command"
   - version: 8.6.4

package/docs/en-GB/cli/scan.md

@@ -18,7 +18,7 @@ slugs:
   - cli
   - scan
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-11
     changes: "Added scan command"
 author: aymericzip