@intlayer/docs 8.11.2 → 8.12.0-canary.0

package/docs/en-GB/intlayer_with_astro_svelte.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2026-04-24
-updatedAt: 2026-05-06
-title: Astro + Svelte i18n - How to translate an Astro + Svelte application in 2026
-description: Learn how to add internationalisation (i18n) to your Astro + Svelte site with Intlayer. Follow this guide to make your site multilingual.
+updatedAt: 2026-05-31
+title: "Astro + Svelte i18n - Complete guide to translate your app"
+description: "No more i18next. The 2026 guide to building a multilingual (i18n) Astro + Svelte app. Translate with AI agents and optimise bundle size, SEO and performances."
 keywords:
   - internationalisation
   - documentation
@@ -58,16 +58,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 `astro-i18n` or `i18next`, Intlayer is a solution that comes with integrated optimizations such as:
 
-With Intlayer, you can:
+<AccordionGroup>
 
-- **Manage translations easily**: Using declarative dictionaries at the component level.
-- **Localise metadata, routes and content dynamically**.
-- **Ensure TypeScript support**: With autogenerated types for better autocompletion and error detection.
-- **Benefit from advanced features**: Such as dynamic language detection and switching.
+<Accordion header="Full Astro coverage">
+
+Intlayer is optimized to work perfectly with Astro by offering **multilingual routing**, **sitemap**, 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>
 
 ---
 
@@ -75,7 +113,9 @@ With Intlayer, you can:
 
 Check out the [application template](https://github.com/aymericzip/intlayer-astro-template) on GitHub.
 
-### Step 1: Install Dependencies
+<Steps>
+
+<Step number={1} title="Install Dependencies">
 
 Install the necessary packages using your preferred package manager:
 
@@ -118,7 +158,9 @@ bun x intlayer init
 - **@astrojs/svelte**
   Official Astro integration that allows the use of Svelte component islands.
 
-### Step 2: Configure Your Project
+</Step>
+
+<Step number={2} title="Configure Your Project">
 
 Create a configuration file to define your application's languages:
 
@@ -143,7 +185,9 @@ export default config;
 
 > Through this configuration file, you can configure localised URLs, middleware redirects, cookie names, location and extensions of content declarations, disable Intlayer logs in the console, and more. For a full 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 into Your Astro Configuration
+</Step>
+
+<Step number={3} title="Integrate Intlayer into Your Astro Configuration">
 
 Add the `intlayer` plugin and Svelte integration to your Astro configuration.
 
@@ -164,7 +208,9 @@ export default defineConfig({
 
 > The `svelte()` integration allows for using Svelte component islands via `client:only="svelte"`.
 
-### Step 4: Declare Your Content
+</Step>
+
+<Step number={4} title="Declare Your Content">
 
 Create and manage your content declarations to store translations:
 
@@ -190,7 +236,9 @@ export default appContent;
 
 > For more information, refer to the [content declaration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/content_file.md).
 
-### Step 5: Using Content in Astro
+</Step>
+
+<Step number={5} title="Using Content in Astro">
 
 You can consume the dictionaries directly in your `.astro` files using the core helpers exported from `intlayer`. You should also add SEO metadata (such as hreflang and canonical links) to every page and introduce a Svelte island for interactive client-side content.
 
@@ -278,7 +326,9 @@ const { title } = getIntlayer("app", locale);
 > - **`prefix-all`:** all URLs get a language prefix. You can use standard `[locale]` if you don't need to handle the root separately.
 > - **`search-param` or `no-prefix`:** no language directories are needed. The language is handled via query parameters or cookies.
 
-### Step 6: Create a Svelte Island Component
+</Step>
+
+<Step number={6} title="Create a Svelte Island Component">
 
 Create an island component that wraps your Svelte application. You must call `setupIntlayer` with the server-detected locale before accessing the stores.
 
@@ -323,7 +373,9 @@ Create an island component that wraps your Svelte application. You must call `se
 
 > The `locale` prop is passed from the Astro page (server detection) and used to initialise `setupIntlayer`, setting the initial language for all stores in the component.
 
-### Step 7: Add a Language Switcher
+</Step>
+
+<Step number={7} title="Add a Language Switcher">
 
 The language switching functionality is integrated directly within the Svelte island (see step 6 above). It uses the `useLocale` store from `svelte-intlayer` and navigates to the localised URL when a user selects a new language:
 
@@ -367,7 +419,9 @@ The language switching functionality is integrated directly within the Svelte is
 > **Note on persistence:**
 > Using `onLocaleChange` to redirect via `window.location.href` ensures the new linguistic URL is visited, allowing the Intlayer middleware to set the language cookie and remember the user's preference in future visits.
 
-### Step 8: Sitemap and Robots.txt
+</Step>
+
+<Step number={8} title="Sitemap and Robots.txt">
 
 Intlayer offers utilities to dynamically create your localised sitemap and robots.txt files.
 
@@ -427,55 +481,9 @@ export const GET: APIRoute = ({ site }) => {
 };
 ```
 
-### TypeScript Configuration
-
-Intlayer uses module augmentation to leverage TypeScript, making your codebase more robust.
+</Step>
 
-![Autocompletion](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true)
-
-![Translation Error](https://github.com/aymericzip/intlayer/blob/main/docs/assets/translation_error.png?raw=true)
-
-Ensure your TypeScript configuration includes the autogenerated types.
-
-```json5 fileName="tsconfig.json"
-{
-  // ... your existing TypeScript configuration
-  "include": [
-    // ... your existing TypeScript configuration
-    ".intlayer/**/*.ts", // Include autogenerated types
-  ],
-}
-```
-
-### Git Configuration
-
-It is recommended to ignore the files generated by Intlayer. This avoids committing them to your Git repository.
-
-To do this, add the following instructions to your `.gitignore` file:
-
-```bash
-# Ignore the files generated by Intlayer
-.intlayer
-```
-
-### VS Code Extension
-
-To improve your development experience with Intlayer, you can install the **official Intlayer VS Code extension**.
-
-[Installation from the VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
-
-This extension provides:
-
-- **Autocompletion** for translation keys.
-- **Real-time error detection** for missing translations.
-- **Inline preview** of translated content.
-- **Quick actions** for easily creating and updating translations.
-
-For more information on using the extension, refer to the [VS Code Extension documentation](https://intlayer.org/doc/vs-code-extension).
-
----
-
-### (Optional) Step 15: Extract the content of your components
+<Step number={15} title="Extract the content of your components" isOptional={true}>
 
 If you have an existing codebase, transforming thousands of files can be time-consuming.
 
@@ -577,6 +585,58 @@ bun run build # Or bun run dev
 
 ---
 
+</Step>
+
+</Steps>
+
+### TypeScript Configuration
+
+Intlayer uses module augmentation to leverage TypeScript, making your codebase more robust.
+
+![Autocompletion](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true)
+
+![Translation Error](https://github.com/aymericzip/intlayer/blob/main/docs/assets/translation_error.png?raw=true)
+
+Ensure your TypeScript configuration includes the autogenerated types.
+
+```json5 fileName="tsconfig.json"
+{
+  // ... your existing TypeScript configuration
+  "include": [
+    // ... your existing TypeScript configuration
+    ".intlayer/**/*.ts", // Include autogenerated types
+  ],
+}
+```
+
+### Git Configuration
+
+It is recommended to ignore the files generated by Intlayer. This avoids committing them to your Git repository.
+
+To do this, add the following instructions to your `.gitignore` file:
+
+```bash
+# Ignore the files generated by Intlayer
+.intlayer
+```
+
+### VS Code Extension
+
+To improve your development experience with Intlayer, you can install the **official Intlayer VS Code extension**.
+
+[Installation from the VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
+
+This extension provides:
+
+- **Autocompletion** for translation keys.
+- **Real-time error detection** for missing translations.
+- **Inline preview** of translated content.
+- **Quick actions** for easily creating and updating translations.
+
+For more information on using the extension, refer to the [VS Code Extension documentation](https://intlayer.org/doc/vs-code-extension).
+
+---
+
 ### Deepen Your Knowledge
 
 If you want to learn more, you can also implement the [Visual Editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_visual_editor.md) or use the [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_CMS.md) to externalise your content.

package/docs/en-GB/intlayer_with_astro_vanilla.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2026-04-24
-updatedAt: 2026-05-06
-title: Astro + Vanilla JS i18n - How to translate an Astro + Vanilla JS application in 2026
-description: Learn how to add internationalisation (i18n) to your Astro + Vanilla JS site with Intlayer. Follow this guide to make your site multilingual.
+updatedAt: 2026-05-31
+title: "Astro + Vanilla JS i18n - Complete guide to translate your app"
+description: "No more i18next. The 2026 guide to building a multilingual (i18n) Astro + Vanilla JS app. Translate with AI agents and optimise bundle size, SEO and performances."
 keywords:
   - internationalisation
   - documentation
@@ -58,16 +58,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 `astro-i18n` or `i18next`, Intlayer is a solution that comes with integrated optimizations such as:
 
-With Intlayer, you can:
+<AccordionGroup>
 
-- **Manage translations easily**: Using declarative dictionaries at the component level.
-- **Localise metadata, routes and content dynamically**.
-- **Ensure TypeScript support**: With autogenerated types for better autocompletion and error detection.
-- **Benefit from advanced features**: Such as dynamic language detection and switching.
+<Accordion header="Full Astro coverage">
+
+Intlayer is optimized to work perfectly with Astro by offering **multilingual routing**, **sitemap**, 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>
 
 ---
 
@@ -75,7 +113,9 @@ With Intlayer, you can:
 
 Check out the [application template](https://github.com/aymericzip/intlayer-astro-template) on GitHub.
 
-### Step 1: Install Dependencies
+<Steps>
+
+<Step number={1} title="Install Dependencies">
 
 Install the necessary packages using your preferred package manager:
 
@@ -112,7 +152,9 @@ bun x intlayer init
 - **vanilla-intlayer**
   A package to integrate Intlayer into Vanilla JavaScript / TypeScript applications. It provides a Pub/Sub singleton (`IntlayerClient`) and callback-based helpers (`useIntlayer`, `useLocale`, etc.), allowing any part of your Astro `<script>` tags to respond to language changes without the need for a UI framework.
 
-### Step 2: Configure Your Project
+</Step>
+
+<Step number={2} title="Configure Your Project">
 
 Create a configuration file to define your application's languages:
 
@@ -137,7 +179,9 @@ export default config;
 
 > Through this configuration file, you can configure localised URLs, middleware redirects, cookie names, location and extensions of content declarations, disable Intlayer logs in the console, and more. For a full 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 into Your Astro Configuration
+</Step>
+
+<Step number={3} title="Integrate Intlayer into Your Astro Configuration">
 
 Add the `intlayer` plugin to your Astro configuration. For Vanilla JS, no additional UI framework integration is required.
 
@@ -155,7 +199,9 @@ export default defineConfig({
 
 > The `intlayer()` integration plugin is used to integrate Intlayer with Astro. It ensures the generation of the content declaration files and monitors them in development mode. It defines Intlayer environment variables within the Astro application and provides aliases to optimise performance.
 
-### Step 4: Declare Your Content
+</Step>
+
+<Step number={4} title="Declare Your Content">
 
 Create and manage your content declarations to store translations:
 
@@ -193,7 +239,9 @@ export default appContent;
 
 > For more information, refer to the [content declaration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/content_file.md).
 
-### Step 5: Using Content in Astro
+</Step>
+
+<Step number={5} title="Using Content in Astro">
 
 With Vanilla JS, all server-side rendering happens directly in `.astro` files using `getIntlayer`. Subsequently, a `<script>` block initialises `vanilla-intlayer` on the client to enable language switching.
 
@@ -302,7 +350,9 @@ const { greeting, description, switchLocale } = getIntlayer("app", locale);
 > - **`prefix-all`:** all URLs get a language prefix. You can use standard `[locale]` if you don't need to handle the root separately.
 > - **`search-param` or `no-prefix`:** no language directories are needed. The language is handled via query parameters or cookies.
 
-### Step 6: Adding a Language Switcher
+</Step>
+
+<Step number={6} title="Adding a Language Switcher">
 
 In Astro with Vanilla JS, the language switcher is rendered on the server as regular links and hydrated on the client via a `<script>` block. When a user clicks a language link, `vanilla-intlayer` sets the language cookie via `setLocale` before navigating to the localised URL.
 
@@ -343,7 +393,9 @@ In Astro with Vanilla JS, the language switcher is rendered on the server as reg
 > **Note on Progressive Enhancement:**
 > The links in the language switcher will work as standard `<a>` tags even without JavaScript. When JavaScript is available, calls to `setLocale` will update the cookie before navigating, ensuring the middleware performs the correct redirect.
 
-### Step 7: Sitemap and Robots.txt
+</Step>
+
+<Step number={7} title="Sitemap and Robots.txt">
 
 Intlayer offers utilities to dynamically create your localised sitemap and robots.txt files.
 
@@ -403,55 +455,9 @@ export const GET: APIRoute = ({ site }) => {
 };
 ```
 
-### TypeScript Configuration
-
-Intlayer uses module augmentation to leverage TypeScript, making your codebase more robust.
-
-![Autocompletion](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true)
-
-![Translation Error](https://github.com/aymericzip/intlayer/blob/main/docs/assets/translation_error.png?raw=true)
-
-Ensure your TypeScript configuration includes the autogenerated types.
-
-```json5 fileName="tsconfig.json"
-{
-  // ... your existing TypeScript configuration
-  "include": [
-    // ... your existing TypeScript configuration
-    ".intlayer/**/*.ts", // Include autogenerated types
-  ],
-}
-```
-
-### Git Configuration
-
-It is recommended to ignore the files generated by Intlayer. This avoids committing them to your Git repository.
-
-To do this, add the following instructions to your `.gitignore` file:
-
-```bash
-# Ignore the files generated by Intlayer
-.intlayer
-```
-
-### VS Code Extension
-
-To improve your development experience with Intlayer, you can install the **official Intlayer VS Code extension**.
-
-[Installation from the VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
-
-This extension provides:
-
-- **Autocompletion** for translation keys.
-- **Real-time error detection** for missing translations.
-- **Inline preview** of translated content.
-- **Quick actions** for easily creating and updating translations.
+</Step>
 
-For more information on using the extension, refer to the [VS Code Extension documentation](https://intlayer.org/doc/vs-code-extension).
-
----
-
-### (Optional) Step 15: Extract the content of your components
+<Step number={15} title="Extract the content of your components" isOptional={true}>
 
 If you have an existing codebase, transforming thousands of files can be time-consuming.
 
@@ -553,6 +559,58 @@ bun run build # Or bun run dev
 
 ---
 
+</Step>
+
+</Steps>
+
+### TypeScript Configuration
+
+Intlayer uses module augmentation to leverage TypeScript, making your codebase more robust.
+
+![Autocompletion](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true)
+
+![Translation Error](https://github.com/aymericzip/intlayer/blob/main/docs/assets/translation_error.png?raw=true)
+
+Ensure your TypeScript configuration includes the autogenerated types.
+
+```json5 fileName="tsconfig.json"
+{
+  // ... your existing TypeScript configuration
+  "include": [
+    // ... your existing TypeScript configuration
+    ".intlayer/**/*.ts", // Include autogenerated types
+  ],
+}
+```
+
+### Git Configuration
+
+It is recommended to ignore the files generated by Intlayer. This avoids committing them to your Git repository.
+
+To do this, add the following instructions to your `.gitignore` file:
+
+```bash
+# Ignore the files generated by Intlayer
+.intlayer
+```
+
+### VS Code Extension
+
+To improve your development experience with Intlayer, you can install the **official Intlayer VS Code extension**.
+
+[Installation from the VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
+
+This extension provides:
+
+- **Autocompletion** for translation keys.
+- **Real-time error detection** for missing translations.
+- **Inline preview** of translated content.
+- **Quick actions** for easily creating and updating translations.
+
+For more information on using the extension, refer to the [VS Code Extension documentation](https://intlayer.org/doc/vs-code-extension).
+
+---
+
 ### Deepen Your Knowledge
 
 If you want to learn more, you can also implement the [Visual Editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_visual_editor.md) or use the [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_CMS.md) to externalise your content.