@intlayer/docs 9.0.0-canary.4 → 9.0.0-canary.5

package/docs/en-GB/packages/react-intlayer/useIntlayer.md

@@ -29,49 +29,6 @@ author: aymericzip
 
 This section provides detailed guidance on using the `useIntlayer` hook within React applications, allowing for efficient content localisation.
 
-## Importing `useIntlayer` in React
-
-The `useIntlayer` hook can be integrated into React applications by importing it based on the context:
-
-- **Client Component:**
-
-  ```typescript codeFormat="typescript"
-  import { useIntlayer } from "react-intlayer"; // Used in client-side React components
-  ```
-
-  ```javascript codeFormat="esm"
-  import { useIntlayer } from "react-intlayer"; // Used in client-side React components
-  ```
-
-  ```javascript codeFormat="commonjs"
-  const { useIntlayer } = require("react-intlayer"); // Used in client-side React components
-  ```
-
-- **Server Component:**
-
-  ```typescript codeFormat="commonjs"
-  import { useIntlayer } from "react-intlayer/server"; // Used in server-side React components
-  ```
-
-  ```javascript codeFormat="esm"
-  import { useIntlayer } from "react-intlayer/server"; // Used in server-side React components
-  ```
-
-  ```javascript codeFormat="commonjs"
-  const { useIntlayer } = require("react-intlayer/server"); // Used in server-side React components
-  ```
-
-## Parameters
-
-The hook accepts two parameters:
-
-1. **`key`**: The dictionary key to retrieve localised content.
-2. **`locale`** (optional): The desired locale. Defaults to the context's locale if not specified.
-
-## Dictionary
-
-All dictionary keys must be declared within content declaration files to enhance type safety and avoid errors. You can find the [setup instructions here](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/content_file.md).
-
 ## Example Usage in React
 
 Demonstrating the `useIntlayer` hook within a React component:
@@ -131,14 +88,6 @@ const ServerComponentExample = () => {
 };
 ```
 
-## Handling Attributes
-
-When localising attributes, access the content values appropriately:
-
-```jsx
-<button title={content.buttonTitle.value}>{content.buttonText}</button>
-```
-
 ## Additional Resources
 
 - **Intlayer Visual Editor**: For a more intuitive content management experience, refer to the visual editor documentation [here](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_visual_editor.md).

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

@@ -429,65 +429,6 @@ When the same translation key exists in multiple JSON sources:
 2. Lower priority sources are used as fallbacks for missing keys
 3. This allows you to maintain legacy translations whilst gradually migrating to new structures
 
-## Integrations
-
-Below are common mappings. Keep your runtime untouched; only add the plugin.
-
-### i18next
-
-Typical file layout: `./public/locales/{locale}/{namespace}.json` or `./locales/{locale}/{namespace}.json`.
-
-```ts fileName="intlayer.config.ts"
-import { syncJSON } from "@intlayer/sync-json-plugin";
-
-export default {
-  plugins: [
-    syncJSON({
-      format: "i18next",
-      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
-    }),
-  ],
-};
-```
-
-### next-intl
-
-Per-locale JSON messages (often `./messages/{locale}.json`) or per-namespace.
-
-```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ locale, key }) => `./messages/${locale}/${key}.json`,
-  }),
-];
-```
-
-See also: `docs/en/intlayer_with_next-intl.md`.
-
-### react-intl
-
-A single JSON file per locale is common:
-
-```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ locale }) => `./locales/${locale}.json`,
-  }),
-];
-```
-
-### vue-i18n
-
-Either a single file per locale or per-namespace:
-
-```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ key, locale }) => `./src/locales/${locale}/${key}.json`,
-  }),
-];
-```
-
 ## CLI
 
 The synchronised JSON files will be considered as other `.content` files. That means, all intlayer commands will be available for the synchronised JSON files. Including:

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

@@ -25,6 +25,10 @@ author: aymericzip
 
 Welcome to Intlayer v6! This release focuses on performance, developer experience, and reliability. Below are the highlights, with migration notes and copy‑pasteable examples.
 
+## Table of contents
+
+<TOC levels={[2]} maxDepth={1} />
+
 ## Highlights
 
 - New command: `npx intlayer content test` to detect missing translations
@@ -264,12 +268,6 @@ See [Configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/e
 
 ---
 
-## Stronger validation
-
-Dictionary processing now performs more robust validation. When a dictionary fails to process, Intlayer avoids breaking your application and surfaces actionable errors.
-
----
-
 ## Live updates with CMS (Production‑safe)
 
 Serve live content updates (e.g., editorial updates) in production without rebuilding your application.
@@ -336,6 +334,12 @@ See [CMS and Live Sync](https://github.com/aymericzip/intlayer/blob/main/docs/do
 
 ---
 
+## Migration notes from v6 to v7
+
+Check the [migration notes from v6 to v7](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/releases/v7.md) for more information.
+
+---
+
 ## Useful links
 
 - [CLI reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/index.md)

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

@@ -25,6 +25,10 @@ author: aymericzip
 
 Welcome to Intlayer v7! This major release introduces significant improvements in performance, type safety, and developer experience. Below are the highlights, with migration notes and practical examples.
 
+## Table of contents
+
+<TOC levels={[2]} maxDepth={1} />
+
 ## Highlights
 
 - Caching strategy for faster builds
@@ -260,6 +264,126 @@ This results in faster download times and improved runtime performance for your
 
 ---
 
+## Automatic Code Formatting: formatCommand configuration
+
+v7 introduces the `formatCommand` option in the editor configuration, allowing you to automatically format content files when they are written by Intlayer. This ensures consistent code style and formatting across your content declaration files.
+
+If not set, Intlayer will try to detect the format command automatically. By trying to resolve the following commands: prettier, biome, eslint.
+
+### Configuration
+
+The `formatCommand` option accepts a string template where `{{file}}` will be replaced with the actual file path:
+
+```typescript fileName="intlayer.config.ts"
+export default {
+  content: {
+    formatCommand: 'bun x biome format "{{file}}" --write --log-level none',
+  },
+};
+```
+
+### Supported formatters
+
+You can use any code formatter that accepts file paths as arguments:
+
+**Using Biome:**
+
+```typescript
+formatCommand: 'bun x biome format "{{file}}" --write --log-level none';
+```
+
+**Using Prettier:**
+
+```typescript
+formatCommand: 'npx prettier --write "{{file}}" --log-level silent';
+```
+
+**Using ESLint:**
+
+```typescript
+formatCommand: 'npx eslint --fix "{{file}}" --quiet';
+```
+
+**Using Bun's built-in formatter:**
+
+```typescript
+formatCommand: 'bun format "{{file}}"';
+```
+
+### Benefits
+
+- **Consistent formatting**: All content files are automatically formatted according to your project's style guidelines
+- **Developer experience**: No need to manually format files after Intlayer writes them
+- **Team consistency**: Ensures all team members have the same formatting applied to content files
+- **CI/CD integration**: Content files maintain consistent formatting in automated workflows
+
+### How it works
+
+When Intlayer writes or updates a content declaration file (`.content.ts`, `.content.js`, etc.), it automatically runs the specified format command on the file. The `{{file}}` placeholder is replaced with the actual file path, and the command is executed in the project's base directory.
+
+---
+
+## Dictionary Configuration: Better organization and structure
+
+v7 introduces a new dedicated `dictionary` configuration section that provides better organisation for dictionary-related settings and improved content management.
+
+### New dictionary configuration structure
+
+The `fill` property has been moved from the `content` section to a new `dictionary` section, providing clearer separation of concerns:
+
+**v6 configuration:**
+
+```typescript fileName="intlayer.config.ts"
+export default {
+  content: {
+    autoFill: "./{{fileName}}.content.json",
+    contentDir: ["src"],
+  },
+};
+```
+
+**v7 configuration:**
+
+```typescript fileName="intlayer.config.ts"
+export default {
+  content: {
+    contentDir: ["src"],
+  },
+  dictionary: {
+    fill: "./{{fileName}}.content.json",
+  },
+};
+```
+
+### Benefits of the new structure
+
+- **Clearer organisation**: Dictionary-specific settings are now grouped together
+- **Better separation of concerns**: Content discovery vs. dictionary operations are clearly separated
+- **Enhanced maintainability**: Easier to understand and modify dictionary-related configurations
+- **Future extensibility**: The dictionary section can accommodate additional dictionary-specific settings
+- **Comprehensive dictionary management**: Includes properties like `title`, `live`, `priority`, `tags`, `version`, and `description` for creating and managing new dictionaries
+
+### Configuration usage
+
+The dictionary configuration serves two main purposes:
+
+1. **Default Values**: Define default values when creating content declaration files
+2. **Fallback Behaviour**: Provide fallback values when specific fields are not defined, allowing you to define dictionary operation behaviour globally
+
+The dictionary section includes comprehensive properties for dictionary management:
+
+- **`fill`**: Auto-fill behaviour for content generation
+- **`title`**: Default title for new dictionaries
+- **`live`**: Live sync configuration for real-time updates
+- **`priority`**: Priority settings for dictionary resolution
+- **`tags`**: Default tags for content organisation
+- **`version`**: Version management for dictionary updates
+- **`description`**: Default description for new content
+
+For more information about content declaration files and how configuration values are applied, see the [Content File Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/content_file.md).
+
+---
+
 ## Fill command: Updated behaviour for better content management
 
 v7 introduces improved behaviour for the `fill` command, providing more predictable and flexible content management:
@@ -407,6 +531,10 @@ The system automatically:
 - **`middleware.prefixDefault`**: Replaced by `routing.mode`
 - **`middleware.noPrefix`**: Replaced by `routing.mode`
 
+### New configurations
+
+- **`editor.formatCommand`**: New option for automatic code formatting of content files
+
 ### Migration mapping
 
 #### Configuration mapping

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,6 +1,6 @@
 ---
 createdAt: 2026-06-14
-updatedAt: 2026-06-14
+updatedAt: 2026-06-23
 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:
@@ -204,6 +204,42 @@ At build time, `@intlayer/swc` and `@intlayer/babel` scan your files and replace
 
 ---
 
+## 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 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"
+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.
+
+---
+
 ## 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:

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

package/docs/es/CI_CD.md

@@ -26,6 +26,10 @@ author: aymericzip
 
 Intlayer permite la generación automática de traducciones para tus archivos de declaración de contenido. Existen múltiples formas de lograr esto dependiendo de tu flujo de trabajo.
 
+## Tabla de contenidos
+
+<TOC/>
+
 ## Uso del CMS
 
 Con Intlayer, puedes adoptar un flujo de trabajo donde solo se declara un único locale localmente, mientras que todas las traducciones se gestionan de forma remota a través del CMS. Esto permite que el contenido y las traducciones estén completamente desacoplados del código base, ofreciendo más flexibilidad para los editores de contenido y habilitando la recarga en caliente del contenido (no es necesario reconstruir la aplicación para aplicar cambios).