@intlayer/docs 8.11.2 → 8.12.0-canary.0

package/docs/en-GB/intlayer_with_tanstack.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2025-09-09
-updatedAt: 2026-05-06
-title: Tanstack Start i18n - How to translate an Tanstack Start app in 2026
-description: Learn how to add internationalisation (i18n) to your Tanstack Start application using Intlayer. Follow this comprehensive guide to make your app multilingual with locale-aware routing.
+updatedAt: 2026-05-31
+title: "TanStack Start i18n - Complete guide to translate your app"
+description: "No more i18next. The 2026 guide to building a multilingual (i18n) TanStack Start app. Translate with AI agents and optimise bundle size, SEO and performances."
 keywords:
   - Internationalisation
   - Documentation
@@ -54,17 +54,54 @@ history:
 
 This guide demonstrates how to integrate **Intlayer** for seamless internationalisation in Tanstack Start projects with locale-aware routing, TypeScript support, and modern development practices.
 
-## 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 `use-intl`, or `paraglide`, 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 Tanstack Start's file-based routing system.
+<Accordion header="Full TanStack Start coverage">
+
+Intlayer is fully optimized for TanStack Start, providing **multilingual routing**, **cookie management**, **sitemap generation**, **dynamic content loading**, and all the features needed to scale your internationalization (i18n) efforts.
+
+</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>
 
 ---
 
@@ -102,11 +139,15 @@ With Intlayer, you can:
 
 See [Application Template](https://github.com/aymericzip/intlayer-tanstack-start-template) on GitHub.
 
-### Step 1: Create Project
+<Steps>
+
+<Step number={1} title="Create Project">
 
 Start by creating a new Tanstack Start project by following the [Start new project](https://tanstack.com/start/latest/docs/framework/react/quick-start) guide on the Tanstack Start website.
 
-### Step 2: Install Intlayer Packages
+</Step>
+
+<Step number={2} title="Install Intlayer Packages">
 
 Install the necessary packages using your preferred package manager:
 
@@ -144,7 +185,9 @@ bun x intlayer init
 - **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 3: Configuration of your project
+</Step>
+
+<Step number={3} title="Configuration of your project">
 
 Create a config file to configure the languages of your application:
 
@@ -165,7 +208,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 4: Integrate Intlayer in Your Vite Configuration
+</Step>
+
+<Step number={4} title="Integrate Intlayer in Your Vite Configuration">
 
 Add the intlayer plugin into your configuration:
 
@@ -195,7 +240,9 @@ export default config;
 
 > 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 5: Create Root Layout
+</Step>
+
+<Step number={5} title="Create Root Layout">
 
 Configure your root layout to support internationalisation by using `useParams` to detect the current locale and setting the `lang` and `dir` attributes on the `html` tag.
 
@@ -255,7 +302,9 @@ function RootDocument({ children }: { children: ReactNode }) {
 > <img src="{String(content.image.src)}" alt="{String(content.image)}" />
 > ```
 
-### Step 6: Create Locale Layout
+</Step>
+
+<Step number={6} title="Create Locale Layout">
 
 Create a layout that handles the locale prefix and performs validation.
 
@@ -287,7 +336,9 @@ export const Route = createFileRoute("/{-$locale}")({
 > For the `'prefix-all'` mode, you may prefer switching the slot to `$locale` instead.
 > For the `'no-prefix'` or `'search-params'` mode, you can remove the slot entirely.
 
-### Step 7: Declare Your Content
+</Step>
+
+<Step number={7} title="Declare Your Content">
 
 Create and manage your content declarations to store translations:
 
@@ -333,7 +384,9 @@ export default appContent;
 
 > 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 8: Create Locale-Aware Components and Hooks
+</Step>
+
+<Step number={8} title="Create Locale-Aware Components and Hooks">
 
 Create a `LocalisedLink` component for locale-aware navigation:
 
@@ -437,7 +490,9 @@ export const useLocalizedNavigate = () => {
 };
 ```
 
-### Step 9: Utilize Intlayer in Your Pages
+</Step>
+
+<Step number={9} title="Utilize Intlayer in Your Pages">
 
 Access your content dictionaries throughout your application:
 
@@ -485,7 +540,9 @@ function RouteComponent() {
 
 > 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 10: Create a Locale Switcher Component
+</Step>
+
+<Step number={10} title="Create a Locale Switcher Component">
 
 Create a component to allow users to change languages:
 
@@ -546,7 +603,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 11: HTML Attributes Management
+</Step>
+
+<Step number={11} title="HTML Attributes Management">
 
 As seen in Step 5, you can manage the `lang` and `dir` attributes of the `html` tag using `useParams` in your root component. This ensures that the correct attributes are set on the server and client.
 
@@ -565,7 +624,9 @@ function RootDocument({ children }: { children: ReactNode }) {
 
 ---
 
-### Step 12: Add middleware (Optional)
+</Step>
+
+<Step number={12} 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.
 
@@ -596,7 +657,9 @@ export default defineConfig({
 
 ---
 
-### Step 13: Internationalise your Metadata (Optional)
+</Step>
+
+<Step number={13} title="Internationalise your Metadata">
 
 You can also use the `getIntlayer` hook to access your content dictionaries throughout your application:
 
@@ -643,7 +706,9 @@ export const Route = createFileRoute("/{-$locale}/")({
 
 ---
 
-### Step 14: Retrieve the locale in your server actions (Optional)
+</Step>
+
+<Step number={14} title="Retrieve the locale in your server actions">
 
 You may want to access the current locale from inside your server actions or API endpoints.
 You can do this using the `getLocale` helper from `intlayer`.
@@ -680,7 +745,9 @@ export const getLocaleServer = createServerFn().handler(async () => {
 
 ---
 
-### Step 15: Manage not found pages (Optional)
+</Step>
+
+<Step number={15} title="Manage not found pages">
 
 When a user visits a non-existing page, you can display a custom not found page and the locale prefix may impact the way the not found page is triggered.
 
@@ -756,7 +823,9 @@ export const Route = createFileRoute("/{-$locale}/$")({
 
 ---
 
-### Step 16: Generate Sitemap (Optional)
+</Step>
+
+<Step number={16} title="Generate Sitemap">
 
 Intlayer comes with a built-in sitemap generator to help you create a sitemap for your application easily. It handles localized routes and adds the necessary metadata for search engines.
 
@@ -829,7 +898,9 @@ export const Route = createFileRoute("/sitemap.xml")({
 
 ---
 
-### Step 17: Configure TypeScript (Optional)
+</Step>
+
+<Step number={17} title="Configure TypeScript">
 
 Intlayer uses module augmentation to get benefits of TypeScript and make your codebase stronger.
 
@@ -847,6 +918,10 @@ Ensure your TypeScript configuration includes the autogenerated types:
 
 ---
 
+</Step>
+
+</Steps>
+
 ### Git Configuration
 
 It is recommended to ignore the files generated by Intlayer. This allows you to avoid committing them to your Git repository.

package/docs/en-GB/intlayer_with_vanilla.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2026-03-31
-updatedAt: 2026-05-06
-title: Vanilla JS i18n - How to translate a Vanilla JS app in 2026
-description: Discover how to make your Vanilla JS website multilingual. Follow the documentation to internationalise (i18n) and translate it.
+updatedAt: 2026-05-31
+title: "Vanilla JS i18n - Complete guide to translate your app"
+description: "No more i18next. The 2026 guide to building a multilingual (i18n) Vanilla JS app. Translate with AI agents and optimise bundle size, SEO and performances."
 keywords:
   - Internationalisation
   - Documentation
@@ -57,28 +57,62 @@ 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.
+Compared to main solutions like `i18next` or `i18n.js`, 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.
+<Accordion header="Full Vanilla JS coverage">
 
-This guide demonstrates how to use Intlayer in a Vanilla JavaScript application **without using a package manager or a bundler** (like Vite, Webpack, etc.).
+Intlayer is optimized to work perfectly with Vanilla JavaScript by offering **framework-agnostic content management**, **TypeScript support**, and all the features needed for scaling internationalization (i18n).
 
-If your application uses a bundler (like Vite), we recommend following the [Vite + Vanilla JS Guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_with_vite+vanilla.md) instead.
+</Accordion>
 
-Using the standalone bundle, you can import Intlayer directly into your HTML files via a single JavaScript file, making it perfect for legacy projects or simple static sites.
+<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 Vanilla JS Application
 
-### Step 1: Install Dependencies
+<Steps>
+
+<Step number={1} title="Install Dependencies">
 
 Install the necessary packages using npm:
 
@@ -138,7 +172,9 @@ bun x intlayer build
 
 > The `intlayer standalone` CLI's bundling export creates an optimised build through tree-shaking for unused packages, locales, and non-essential logic (like redirects or prefixes) specific to your configuration.
 
-### Step 2: Configuration of your project
+</Step>
+
+<Step number={2} title="Configuration of your project">
 
 Create a config file to configure the languages of your application:
 
@@ -162,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: Import the bundle in your HTML
+</Step>
+
+<Step number={3} title="Import the bundle in your HTML">
 
 Once you have generated the `intlayer.js` bundle, you can import it in your HTML file:
 
@@ -186,7 +224,9 @@ Once you have generated the `intlayer.js` bundle, you can import it in your HTML
 
 The bundle exposes `Intlayer` and `VanillaIntlayer` as global objects on the `window`.
 
-### Step 4: Bootstrap Intlayer in your entry point
+</Step>
+
+<Step number={4} title="Bootstrap Intlayer in your entry point">
 
 In your `src/main.js`, call `installIntlayer()` **before** any content is rendered so that the global locale singleton is ready.
 
@@ -206,7 +246,9 @@ installIntlayer();
 installIntlayerMarkdown();
 ```
 
-### Step 5: Declare Your Content
+</Step>
+
+<Step number={5} title="Declare Your Content">
 
 Create and manage your content declarations to store translations:
 
@@ -284,7 +326,9 @@ export default appContent;
 >
 > 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 6: Use Intlayer in Your JavaScript
+</Step>
+
+<Step number={6} title="Use Intlayer in Your JavaScript">
 
 The `window.VanillaIntlayer` object provides API helpers: `useIntlayer(key, locale?)` returns the translated content for a given key.
 
@@ -318,7 +362,9 @@ document.querySelector(".read-the-docs").textContent = String(
 > img.alt = content.viteLogoLabel.value;
 > ```
 
-### (Optional) Step 7: Change the language of your content
+</Step>
+
+<Step number={7} title="Change the language of your content" isOptional={true}>
 
 To change the language of your content, use the `setLocale` function exposed by `useLocale`.
 
@@ -353,7 +399,9 @@ export function setupLocaleSwitcher(container) {
 }
 ```
 
-### (Optional) Step 8: Switch the HTML Language and Direction Attributes
+</Step>
+
+<Step number={8} title="Switch the HTML Language and Direction Attributes" isOptional={true}>
 
 Update the `<html>` tag's `lang` and `dir` attributes to match the current locale for accessibility and SEO.
 
@@ -371,7 +419,9 @@ useLocale({
 });
 ```
 
-### (Optional) Step 9: Lazy-load dictionaries per locale
+</Step>
+
+<Step number={9} title="Lazy-load dictionaries per locale" isOptional={true}>
 
 If you want to lazy-load dictionaries per locale, you can use `useDictionaryDynamic`. This is useful if you don't want to bundle all translations in the initial `intlayer.js` file.
 
@@ -393,6 +443,9 @@ const unsubscribe = useDictionaryDynamic(
 ```
 
 > Note: `useDictionaryDynamic` requires the dictionaries to be available as separate ESM files. This approach is typically used if you have a web server serving the dictionaries.
+> </Step>
+
+</Steps>
 
 ### Configure TypeScript
 

package/docs/en-GB/intlayer_with_vite+lit.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2026-03-23
-updatedAt: 2026-05-06
-title: Vite + Lit i18n - How to translate a Lit app in 2026
-description: Discover how to make your Vite and Lit website multilingual. Follow the documentation to internationalise (i18n) and translate it.
+updatedAt: 2026-05-31
+title: "Vite + Lit i18n - Complete guide to translate your app"
+description: "No more i18next. The 2026 guide to building a multilingual (i18n) Vite + Lit app. Translate with AI agents and optimise bundle size, SEO and performances."
 keywords:
   - Internationalisation
   - Documentation
@@ -57,16 +57,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.
+Compared to main solutions like `lit-localize` 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.
+<Accordion header="Full Lit coverage">
+
+Intlayer is optimized to work perfectly with Lit by offering **Web Component-level content scoping**, **TypeScript support**, 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>
 
 ---
 
@@ -74,7 +112,9 @@ See [Application Template](https://github.com/aymericzip/intlayer-vite-lit-templ
 
 ## Step-by-Step Guide to Set Up Intlayer in a Vite and Lit Application
 
-### Step 1: Install Dependencies
+<Steps>
+
+<Step number={1} title="Install Dependencies">
 
 Install the necessary packages using npm:
 
@@ -112,7 +152,9 @@ bun x intlayer init
 - **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">
 
 Create a config file to configure the languages of your application:
 
@@ -136,7 +178,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
+</Step>
+
+<Step number={3} title="Integrate Intlayer in Your Vite Configuration">
 
 Add the intlayer plugin into your configuration.
 
@@ -152,7 +196,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: Bootstrap Intlayer in your entry point
+</Step>
+
+<Step number={4} title="Bootstrap Intlayer in your entry point">
 
 Call `installIntlayer()` **before** any custom elements are registered so that the global locale singleton is ready when the first element connects.
 
@@ -177,7 +223,9 @@ installIntlayerMarkdown();
 import "./my-element.js";
 ```
 
-### Step 5: Declare Your Content
+</Step>
+
+<Step number={5} title="Declare Your Content">
 
 Create and manage your content declarations to store translations:
 
@@ -263,7 +311,9 @@ export default appContent;
 >
 > 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 6: Utilise Intlayer in Your LitElement
+</Step>
+
+<Step number={6} title="Utilise Intlayer in Your LitElement">
 
 Use `useIntlayer` inside a `LitElement`. It returns a `ReactiveController` proxy that automatically triggers re-renders whenever the active locale changes - no extra setup required.
 
@@ -308,7 +358,9 @@ export class MyElement extends LitElement {
 > html`<img alt=${String(content.viteLogo)} />`;
 > ```
 
-### (Optional) Step 7: Change the language of your content
+</Step>
+
+<Step number={7} title="Change the language of your content" isOptional={true}>
 
 To change the language of your content, use the `setLocale` method exposed by the `useLocale` controller.
 
@@ -343,7 +395,9 @@ export class LocaleSwitcher extends LitElement {
 }
 ```
 
-### (Optional) Step 8: Render Markdown and HTML content
+</Step>
+
+<Step number={8} title="Render Markdown and HTML content" isOptional={true}>
 
 Intlayer supports `md()` and `html()` content declarations. In Lit, compiled output is injected as raw HTML via the `unsafeHTML` directive.
 
@@ -393,7 +447,9 @@ export class MyElement extends LitElement {
 > [!TIP]
 > `String(content.editNote)` calls `toString()` on the `IntlayerNode`, which returns the raw Markdown string. Pass it to `compileMarkdown` to get an HTML string, then render it with Lit's `unsafeHTML` directive.
 
-### (Optional) Step 9: Add localised Routing to your application
+</Step>
+
+<Step number={9} title="Add localised Routing to your application" isOptional={true}>
 
 To make unique routes for each language (useful for SEO), you can use a client-side router alongside Intlayer's `localeMap` / `localeFlatMap` helpers, and the `intlayerProxy` Vite plugin for server-side locale detection.
 
@@ -413,7 +469,9 @@ export default defineConfig({
 });
 ```
 
-### (Optional) Step 10: Change the URL when the locale changes
+</Step>
+
+<Step number={10} title="Change the URL when the locale changes" isOptional={true}>
 
 To update the browser URL when the locale changes, use `useRewriteURL` alongside the locale switcher:
 
@@ -451,7 +509,9 @@ export class LocaleSwitcher extends LitElement {
 }
 ```
 
-### (Optional) Step 11: Switch the HTML Language and Direction Attributes
+</Step>
+
+<Step number={11} title="Switch the HTML Language and Direction Attributes" isOptional={true}>
 
 Update the `<html>` tag's `lang` and `dir` attributes to match the current locale for accessibility and SEO.
 
@@ -476,7 +536,9 @@ export class MyElement extends LitElement {
 }
 ```
 
-### (Optional) Step 12: Extract the content of your components
+</Step>
+
+<Step number={12} title="Extract the content of your components" isOptional={true}>
 
 If you have an existing codebase, transforming thousands of files can be time-consuming.
 
@@ -519,6 +581,10 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
+</Step>
+
+</Steps>
+
 ### (Optional) Sitemap and robots.txt (build-time)
 
 Intlayer includes formatters such as `generateSitemap` and `getMultilingualUrls` that produce crawler-ready multilingual `sitemap.xml` and `robots.txt` output you can write into your project’s `public/` folder. In practice you run a small Node script **before** Vite (for example `predev` / `prebuild` npm hooks) so those files exist when you build or serve the app.