@intlayer/docs 8.11.2 → 8.12.0-canary.0

package/docs/en-GB/intlayer_with_react_router_v7.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2025-09-04
-updatedAt: 2026-05-06
-title: React Router v7 i18n - How to translate an React Router v7 app in 2026
-description: Learn how to add internationalisation (i18n) to your React Router v7 application using Intlayer. Follow this comprehensive guide to make your app multilingual with locale-aware routing.
+updatedAt: 2026-05-31
+title: "React Router v7 i18n - Complete guide to translate your app"
+description: "No more i18next. The 2026 guide to building a multilingual (i18n) React Router v7 app. Translate with AI agents and optimise bundle size, SEO and performances."
 keywords:
   - Internationalisation
   - Documentation
@@ -46,23 +46,62 @@ This guide demonstrates how to integrate **Intlayer** for seamless international
 
 <TOC/>
 
-## What is Intlayer?
+## Why Intlayer over alternatives?
 
-**Intlayer** is an innovative, open-source internationalisation (i18n) library designed to simplify multilingual support in modern web applications.
+Compared to main solutions like `react-i18next` or `i18next`, Intlayer is a solution that comes with integrated optimizations such as:
 
-With Intlayer, you can:
+<AccordionGroup>
 
-- **Easily manage translations** using declarative dictionaries at the component level.
-- **Dynamically localise metadata**, routes, and content.
-- **Ensure TypeScript support** with autogenerated types, improving autocompletion and error detection.
-- **Benefit from advanced features**, like dynamic locale detection and switching.
-- **Enable locale-aware routing** with React Router v7's configuration-based routing system.
+<Accordion header="Full React Router coverage">
+
+Intlayer is optimized to work perfectly with React Router by offering **locale-aware routing**, **middleware for locale detection**, and all the features needed for scaling internationalization (i18n).
+
+</Accordion>
+
+<Accordion header="Bundle size">
+
+Instead of loading massive JSON files into your pages, load only the necessary content. Intlayer helps **reduce your bundle and page sizes by up to 50%**.
+
+</Accordion>
+
+<Accordion header="Maintainability">
+
+Scoping your application's content **facilitates maintenance** for large-scale applications. You can duplicate or delete a single feature folder without the mental burden of reviewing your entire content codebase. Additionally, Intlayer is **fully typed** to ensure your content's accuracy.
+
+</Accordion>
+
+<Accordion header="AI Agent">
+
+Co-locating content **reduces the context needed** by Large Language Models (LLMs). Intlayer also comes with a suite of tools, such as a **CLI** to test for missing translations,**[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/lsp.md)**, **[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/mcp_server.md)**, and **[agent skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/agent_skills.md)**, to make the developer experience (DX) even smoother for AI agents.
+
+</Accordion>
+
+<Accordion header="Automation">
+
+Use automation to translate in your CI/CD pipeline using the LLM of your choice at the cost of your AI provider. Intlayer also offers a **compiler** to automate content extraction, as well as a [web platform](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md) to help **translate in the background**.
+
+</Accordion>
+
+<Accordion header="Performance">
+
+Connecting massive JSON files to components can lead to performance and reactivity issues. Intlayer optimizes your content loading at build time.
+
+</Accordion>
+
+<Accordion header="Scaling with none-dev">
+
+More than just an i18n solution, Intlayer provides an **self-hosted [visual editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md)** and a **[full CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)** to help you manage your multilingual content in **real-time**, making collaboration with translators, copywriters, and other team members seamless. Content can be stored locally and/or remotely.
+
+</Accordion>
+</AccordionGroup>
 
 ---
 
 ## Step-by-Step Guide to Set Up Intlayer in a React Router v7 Application
 
-### Step 1: Install Dependencies
+<Steps>
+
+<Step number={1} title="Install Dependencies">
 
 Install the necessary packages using your preferred package manager:
 
@@ -100,7 +139,13 @@ The core package that provides internationalisation tools for configuration mana
 - **vite-intlayer**
   Includes the Vite plugin for integrating Intlayer with the [Vite bundler](https://vite.dev/guide/why.html#why-bundle-for-production), as well as middleware for detecting the user's preferred locale, managing cookies, and handling URL redirection.
 
-### Step 2: Configuration of your project
+</Step>
+
+<Step number={2} title="Configuration of your project">
+
+</Step>
+
+</Steps>
 
 ## Step-by-Step Guide to Set Up Intlayer in a React Router v7 Application with File-System Routes
 
@@ -153,7 +198,9 @@ export default config;
 
 > Through this configuration file, you can set up localised URLs, middleware redirection, cookie names, the location and extension of your content declarations, disable Intlayer logs in the console, and more. For a complete list of available parameters, refer to the [configuration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md).
 
-### Step 3: Integrate Intlayer in Your Vite Configuration
+<Steps>
+
+<Step number={3} title="Integrate Intlayer in Your Vite Configuration">
 
 Add the intlayer plugin into your configuration:
 
@@ -169,7 +216,9 @@ export default defineConfig({
 
 > The `intlayer()` Vite plugin is used to integrate Intlayer with Vite. It ensures the building of content declaration files and monitors them in development mode. It defines Intlayer environment variables within the Vite application. Additionally, it provides aliases to optimise performance.
 
-### Step 4: Configure React Router v7 Routes
+</Step>
+
+<Step number={4} title="Configure React Router v7 Routes">
 
 Set up your routing configuration with locale-aware routes:
 
@@ -182,7 +231,9 @@ export default [
 ] satisfies RouteConfig;
 ```
 
-### Step 5: Create Layout Components
+</Step>
+
+<Step number={5} title="Create Layout Components">
 
 Set up your root layout and locale-specific layouts:
 
@@ -236,7 +287,9 @@ export function Layout({
 }
 ```
 
-### Step 6: Declare Your Content
+</Step>
+
+<Step number={6} title="Declare Your Content">
 
 Create and manage your content declarations to store translations:
 
@@ -276,7 +329,9 @@ export default pageContent;
 
 > For more details, refer to the [content declaration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/content_file.md).
 
-### Step 7: Create Locale-Aware Components
+</Step>
+
+<Step number={7} title="Create Locale-Aware Components">
 
 Create a `LocalizedLink` component for locale-aware navigation:
 
@@ -337,7 +392,9 @@ export const useLocalizedNavigate = () => {
 };
 ```
 
-### Step 8: Utilise Intlayer in Your Pages
+</Step>
+
+<Step number={8} title="Utilise Intlayer in Your Pages">
 
 Access your content dictionaries throughout your application:
 
@@ -389,7 +446,9 @@ export default function Page() {
 
 > To learn more about the `useIntlayer` hook, refer to the [documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/react-intlayer/useIntlayer.md).
 
-### Step 9: Create a Locale Switcher Component
+</Step>
+
+<Step number={9} title="Create a Locale Switcher Component">
 
 Create a component to allow users to change languages:
 
@@ -450,7 +509,9 @@ export const LocaleSwitcher: FC = () => {
 
 > To learn more about the `useLocale` hook, refer to the [documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/react-intlayer/useLocale.md).
 
-### Step 10: Add HTML Attributes Management (Optional)
+</Step>
+
+<Step number={10} title="Add HTML Attributes Management">
 
 Create a hook to manage HTML lang and dir attributes:
 
@@ -488,7 +549,9 @@ export default function RootLayout() {
 }
 ```
 
-### Step 11: Add middleware (Optional)
+</Step>
+
+<Step number={11} title="Add middleware">
 
 You can also use the `intlayerProxy` to add server-side routing to your application. This plugin will automatically detect the current locale based on the URL and set the appropriate locale cookie. If no locale is specified, the plugin will determine the most appropriate locale based on the user's browser language preferences. If no locale is detected, it will redirect to the default locale.
 
@@ -511,6 +574,10 @@ export default defineConfig({
 
 ---
 
+</Step>
+
+</Steps>
+
 ## Configure TypeScript
 
 Intlayer uses module augmentation to benefit from TypeScript and strengthen your codebase.

package/docs/en-GB/intlayer_with_react_router_v7_fs_routes.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2025-09-04
-updatedAt: 2026-05-06
-title: React Router v7 i18n - How to translate an React Router v7 app in 2026
-description: Learn how to add internationalisation (i18n) to your React Router v7 application using Intlayer. Follow this comprehensive guide to make your app multilingual with locale-aware routing.
+updatedAt: 2026-05-31
+title: "React Router v7 i18n - Complete guide to translate your app"
+description: "No more i18next. The 2026 guide to building a multilingual (i18n) React Router v7 app. Translate with AI agents and optimise bundle size, SEO and performances."
 keywords:
   - Internationalisation
   - Documentation
@@ -45,23 +45,62 @@ For client-side routing, refer to the [Intlayer with React Router v7](https://gi
 
 <TOC/>
 
-## What is Intlayer?
+## Why Intlayer over alternatives?
 
-**Intlayer** is an innovative, open-source internationalisation (i18n) library designed to simplify multilingual support in modern web applications.
+Compared to main solutions like `react-i18next` or `i18next`, Intlayer is a solution that comes with integrated optimizations such as:
 
-With Intlayer, you can:
+<AccordionGroup>
 
-- **Easily manage translations** using declarative dictionaries at the component level.
-- **Dynamically localise metadata**, routes, and content.
-- **Ensure TypeScript support** with autogenerated types, improving autocompletion and error detection.
-- **Benefit from advanced features**, like dynamic locale detection and switching.
-- **Enable locale-aware routing** with React Router v7's configuration-based routing system.
+<Accordion header="Full React Router coverage">
+
+Intlayer is optimized to work perfectly with React Router by offering **locale-aware routing**, **middleware for locale detection**, and all the features needed for scaling internationalization (i18n).
+
+</Accordion>
+
+<Accordion header="Bundle size">
+
+Instead of loading massive JSON files into your pages, load only the necessary content. Intlayer helps **reduce your bundle and page sizes by up to 50%**.
+
+</Accordion>
+
+<Accordion header="Maintainability">
+
+Scoping your application's content **facilitates maintenance** for large-scale applications. You can duplicate or delete a single feature folder without the mental burden of reviewing your entire content codebase. Additionally, Intlayer is **fully typed** to ensure your content's accuracy.
+
+</Accordion>
+
+<Accordion header="AI Agent">
+
+Co-locating content **reduces the context needed** by Large Language Models (LLMs). Intlayer also comes with a suite of tools, such as a **CLI** to test for missing translations,**[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/lsp.md)**, **[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/mcp_server.md)**, and **[agent skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/agent_skills.md)**, to make the developer experience (DX) even smoother for AI agents.
+
+</Accordion>
+
+<Accordion header="Automation">
+
+Use automation to translate in your CI/CD pipeline using the LLM of your choice at the cost of your AI provider. Intlayer also offers a **compiler** to automate content extraction, as well as a [web platform](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md) to help **translate in the background**.
+
+</Accordion>
+
+<Accordion header="Performance">
+
+Connecting massive JSON files to components can lead to performance and reactivity issues. Intlayer optimizes your content loading at build time.
+
+</Accordion>
+
+<Accordion header="Scaling with none-dev">
+
+More than just an i18n solution, Intlayer provides an **self-hosted [visual editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md)** and a **[full CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)** to help you manage your multilingual content in **real-time**, making collaboration with translators, copywriters, and other team members seamless. Content can be stored locally and/or remotely.
+
+</Accordion>
+</AccordionGroup>
 
 ---
 
 ## Step-by-Step Guide to Set Up Intlayer in a React Router v7 Application
 
-### Step 1: Install Dependencies
+<Steps>
+
+<Step number={1} title="Install Dependencies">
 
 Install the necessary packages using your preferred package manager:
 
@@ -99,7 +138,13 @@ The core package that provides internationalisation tools for configuration mana
 - **vite-intlayer**
   Includes the Vite plugin for integrating Intlayer with the [Vite bundler](https://vite.dev/guide/why.html#why-bundle-for-production), as well as middleware for detecting the user's preferred locale, managing cookies, and handling URL redirection.
 
-### Step 2: Configuration of your project
+</Step>
+
+<Step number={2} title="Configuration of your project">
+
+</Step>
+
+</Steps>
 
 ## Step-by-Step Guide to Set Up Intlayer in a React Router v7 Application with File-System Routes
 
@@ -152,7 +197,9 @@ export default config;
 
 > Through this configuration file, you can set up localised URLs, middleware redirection, cookie names, the location and extension of your content declarations, disable Intlayer logs in the console, and more. For a complete list of available parameters, refer to the [configuration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md).
 
-### Step 3: Integrate Intlayer in Your Vite Configuration
+<Steps>
+
+<Step number={3} title="Integrate Intlayer in Your Vite Configuration">
 
 Add the intlayer plugin into your configuration:
 
@@ -168,7 +215,9 @@ export default defineConfig({
 
 > The `intlayer()` Vite plugin is used to integrate Intlayer with Vite. It ensures the building of content declaration files and monitors them in development mode. It defines Intlayer environment variables within the Vite application. Additionally, it provides aliases to optimise performance.
 
-### Step 4: Configure React Router v7 Routes
+</Step>
+
+<Step number={4} title="Configure React Router v7 Routes">
 
 Set up your routing configuration with locale-aware routes:
 
@@ -183,7 +232,9 @@ export default [
 ] satisfies RouteConfig;
 ```
 
-### Step 5: Create Layout Components
+</Step>
+
+<Step number={5} title="Create Layout Components">
 
 Set up your root layout and locale-specific layouts:
 
@@ -206,7 +257,9 @@ export default function RootLayout({ params }: Route.ComponentProps) {
 }
 ```
 
-### Step 6: Declare Your Content
+</Step>
+
+<Step number={6} title="Declare Your Content">
 
 Create and manage your content declarations to store translations:
 
@@ -246,7 +299,9 @@ export default pageContent;
 
 > For more details, refer to the [content declaration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/content_file.md).
 
-### Step 7: Create Locale-Aware Components
+</Step>
+
+<Step number={7} title="Create Locale-Aware Components">
 
 Create a `LocalizedLink` component for locale-aware navigation:
 
@@ -307,7 +362,9 @@ export const useLocalizedNavigate = () => {
 };
 ```
 
-### Step 8: Utilise Intlayer in Your Pages
+</Step>
+
+<Step number={8} title="Utilise Intlayer in Your Pages">
 
 Access your content dictionaries throughout your application:
 
@@ -334,7 +391,9 @@ export default function Page() {
 
 > To learn more about the `useIntlayer` hook, refer to the [documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/react-intlayer/useIntlayer.md).
 
-### Step 9: Create a Locale Switcher Component
+</Step>
+
+<Step number={9} title="Create a Locale Switcher Component">
 
 Create a component to allow users to change languages:
 
@@ -395,7 +454,9 @@ export const LocaleSwitcher: FC = () => {
 
 > To learn more about the `useLocale` hook, refer to the [documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/react-intlayer/useLocale.md).
 
-### Step 10: Add HTML Attributes Management (Optional)
+</Step>
+
+<Step number={10} title="Add HTML Attributes Management">
 
 Create a hook to manage HTML lang and dir attributes:
 
@@ -433,7 +494,9 @@ export default function RootLayout() {
 }
 ```
 
-### Step 11: Add middleware (Optional)
+</Step>
+
+<Step number={11} title="Add middleware">
 
 You can also use the `intlayerProxy` to add server-side routing to your application. This plugin will automatically detect the current locale based on the URL and set the appropriate locale cookie. If no locale is specified, the plugin will determine the most appropriate locale based on the user's browser language preferences. If no locale is detected, it will redirect to the default locale.
 
@@ -456,6 +519,10 @@ export default defineConfig({
 
 ---
 
+</Step>
+
+</Steps>
+
 ## Configure TypeScript
 
 Intlayer uses module augmentation to benefit from TypeScript and strengthen your codebase.

package/docs/en-GB/intlayer_with_storybook.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2026-03-20
-updatedAt: 2026-05-06
-title: How to set up Intlayer with Storybook
-description: Learn how to make your design system multilingual using Intlayer with Storybook - compile content declarations, add a locale switcher, and preview your components in any language.
+updatedAt: 2026-05-31
+title: "Storybook i18n - Complete guide to translate your app"
+description: "No more i18next. The 2026 guide to building a multilingual (i18n) Storybook app. Translate with AI agents and optimise bundle size, SEO and performances."
 keywords:
   - Internationalisation
   - Documentation
@@ -31,16 +31,54 @@ history:
 
 <TOC/>
 
-## What is Intlayer?
+## Why Intlayer over alternatives?
 
-**Intlayer** is an innovative, open-source internationalisation (i18n) library designed to simplify multilingual support in modern web applications. It works at the **component level** - each component owns its content declarations - keeping translations co-located with the code that uses them.
+Compared to main solutions like `storybook-react-i18next` or `i18next`, Intlayer is a solution that comes with integrated optimizations such as:
 
-With Intlayer you can:
+<AccordionGroup>
 
-- **Manage translations declaratively** with per-component content files.
-- **Get full TypeScript support** through auto-generated types and IDE autocompletion.
-- **Switch locales at runtime** without a page reload.
-- **Translate automatically** with built-in AI provider integrations.
+<Accordion header="Full Storybook coverage">
+
+Intlayer is optimized to work perfectly with Storybook by offering **multilingual story decorators**, **locale switching**, and all the features needed for scaling internationalization (i18n) across your design system.
+
+</Accordion>
+
+<Accordion header="Bundle size">
+
+Instead of loading massive JSON files into your pages, load only the necessary content. Intlayer helps **reduce your bundle and page sizes by up to 50%**.
+
+</Accordion>
+
+<Accordion header="Maintainability">
+
+Scoping your application's content **facilitates maintenance** for large-scale applications. You can duplicate or delete a single feature folder without the mental burden of reviewing your entire content codebase. Additionally, Intlayer is **fully typed** to ensure your content's accuracy.
+
+</Accordion>
+
+<Accordion header="AI Agent">
+
+Co-locating content **reduces the context needed** by Large Language Models (LLMs). Intlayer also comes with a suite of tools, such as a **CLI** to test for missing translations,**[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/lsp.md)**, **[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/mcp_server.md)**, and **[agent skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/agent_skills.md)**, to make the developer experience (DX) even smoother for AI agents.
+
+</Accordion>
+
+<Accordion header="Automation">
+
+Use automation to translate in your CI/CD pipeline using the LLM of your choice at the cost of your AI provider. Intlayer also offers a **compiler** to automate content extraction, as well as a [web platform](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md) to help **translate in the background**.
+
+</Accordion>
+
+<Accordion header="Performance">
+
+Connecting massive JSON files to components can lead to performance and reactivity issues. Intlayer optimizes your content loading at build time.
+
+</Accordion>
+
+<Accordion header="Scaling with none-dev">
+
+More than just an i18n solution, Intlayer provides an **self-hosted [visual editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md)** and a **[full CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)** to help you manage your multilingual content in **real-time**, making collaboration with translators, copywriters, and other team members seamless. Content can be stored locally and/or remotely.
+
+</Accordion>
+</AccordionGroup>
 
 ---
 
@@ -59,7 +97,9 @@ Storybook is the industry-standard tool for developing and documenting UI compon
 <Tabs>
 <Tab value="Vite Setup">
 
-### Step 1: Install Dependencies
+<Steps>
+
+<Step number={1} title="Install Dependencies">
 
 ```bash packageManager="npm"
 npm install intlayer react-intlayer
@@ -89,7 +129,9 @@ bun add vite-intlayer --dev
 
 ---
 
-### Step 2: Create an Intlayer Configuration
+</Step>
+
+<Step number={2} title="Create an Intlayer Configuration">
 
 Create `intlayer.config.ts` at the root of your project (or inside your design-system package):
 
@@ -118,7 +160,9 @@ export default config;
 
 ---
 
-### Step 3: Add the Vite Plugin to Storybook
+</Step>
+
+<Step number={3} title="Add the Vite Plugin to Storybook">
 
 Storybook's `viteFinal` hook lets you extend the internal Vite config. Import and add the `intlayer()` plugin there:
 
@@ -159,7 +203,9 @@ The `intlayer()` plugin watches your `*.content.ts` files and rebuilds dictionar
 
 ---
 
-### Step 4: Add the `IntlayerProvider` Decorator and a Locale Toolbar
+</Step>
+
+<Step number={4} title="Add the `IntlayerProvider` Decorator and a Locale Toolbar">
 
 Storybook's `preview` file is the right place to wrap every story with the `IntlayerProvider` and expose a locale switcher in the toolbar:
 
@@ -216,7 +262,9 @@ export default preview;
 </Tab>
 <Tab value="Webpack Setup">
 
-### Step 1: Install Dependencies
+</Step>
+
+<Step number={1} title="Install Dependencies">
 
 ```bash packageManager="npm"
 npm install intlayer react-intlayer
@@ -240,7 +288,9 @@ bun add @intlayer/webpack --dev
 
 ---
 
-### Step 2: Create an Intlayer Configuration
+</Step>
+
+<Step number={2} title="Create an Intlayer Configuration">
 
 Create `intlayer.config.ts` at the root of your project:
 
@@ -262,7 +312,9 @@ export default config;
 
 ---
 
-### Step 3: Configure Storybook's Webpack
+</Step>
+
+<Step number={3} title="Configure Storybook's Webpack">
 
 For Webpack-based Storybook setups (e.g. `@storybook/react-webpack5`), extend the webpack config via `webpackFinal` to add the Intlayer aliases and loader:
 
@@ -289,7 +341,9 @@ export default config;
 
 ---
 
-### Step 4: Add the `IntlayerProvider` Decorator and a Locale Toolbar
+</Step>
+
+<Step number={4} title="Add the `IntlayerProvider` Decorator and a Locale Toolbar">
 
 Same as the Vite setup - add the decorator and global locale type in `.storybook/preview.tsx`:
 
@@ -335,6 +389,10 @@ export default preview;
 
 ---
 
+</Step>
+
+</Steps>
+
 ## Declaring Content
 
 Create a `*.content.ts` file next to each component. Intlayer picks it up automatically during compilation.