@intlayer/docs 8.11.2 → 8.12.0-canary.0

package/docs/en/intlayer_with_astro_vanilla.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2026-04-24
 updatedAt: 2026-05-31
-title: Astro + Vanilla JS i18n - Complete guide to translate an Astro + Vanilla JS app
-description: Optimized solution for bundle size, SEO, performances & maintainability. Make your Astro + Vanilla JS website multilingual in 2026, LLM translation, Agent Skills & MCP.
+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 optimize bundle size, SEO and performances."
 keywords:
   - Internationalization
   - Documentation
@@ -58,16 +58,54 @@ history:
 
 <TOC/>
 
-## What is Intlayer?
+## Why Intlayer over alternatives?
 
-**Intlayer** is an innovative, open-source internationalization (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>
 
-- **Easily manage translations** using declarative dictionaries at the component level.
-- **Dynamically localize 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 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:
 
 See [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 package manager:
 
@@ -112,7 +152,9 @@ bun x intlayer init
 - **vanilla-intlayer**
   The package that integrates Intlayer with plain JavaScript / TypeScript applications. It provides a pub/sub singleton (`IntlayerClient`) and callback-based helpers (`useIntlayer`, `useLocale`, etc.) so any part of your Astro `<script>` blocks can react to locale changes without a UI framework.
 
-### 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 localized 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/configuration.md).
 
-### Step 3: Integrate Intlayer in Your Astro Configuration
+</Step>
+
+<Step number={3} title="Integrate Intlayer in Your Astro Configuration">
 
 Add the intlayer plugin into your configuration. No extra UI-framework integration is needed for Vanilla JS.
 
@@ -154,7 +198,9 @@ export default defineConfig({
 
 > The `intlayer()` Astro integration plugin is used to integrate Intlayer with Astro. It ensures the building of content declaration files and monitors them in development mode. It defines Intlayer environment variables within the Astro application. Additionally, it provides aliases to optimize performance.
 
-### Step 4: Declare Your Content
+</Step>
+
+<Step number={4} title="Declare Your Content">
 
 Create and manage your content declarations to store translations:
 
@@ -189,7 +235,9 @@ export default appContent;
 
 > For more details, refer to the [content declaration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/content_file.md).
 
-### Step 5: Use your content in Astro
+</Step>
+
+<Step number={5} title="Use your content in Astro">
 
 With Vanilla JS, all rendering is done directly in the `.astro` file using `getIntlayer` for the initial server render. A `<script>` block then bootstraps `vanilla-intlayer` on the client side for locale switching.
 
@@ -299,7 +347,9 @@ const { greeting, description, switchLocale } = getIntlayer("app", locale);
 > - **`prefix-all`:** All URLs are prefixed with the locale. You can use standard `[locale]` if you don't need to handle the root separately.
 > - **`search-param` or `no-prefix`:** No locale folder is needed. The locale is handled via search parameters or cookies.
 
-### Step 6: Add a Locale Switcher
+</Step>
+
+<Step number={6} title="Add a Locale Switcher">
 
 With Vanilla JS in Astro, the locale switcher is rendered server-side as anchor links and hydrated on the client via a `<script>` block. When the user clicks a locale link, `vanilla-intlayer` sets the locale cookie via `setLocale` before navigating to the localized URL.
 
@@ -340,7 +390,9 @@ With Vanilla JS in Astro, the locale switcher is rendered server-side as anchor
 > **Note on Progressive Enhancement:**
 > The locale links work as standard `<a>` tags even without JavaScript. When JS is available, the `setLocale` call updates the cookie before the navigation so the middleware can redirect correctly.
 
-### Step 7: Sitemap and Robots.txt
+</Step>
+
+<Step number={7} title="Sitemap and Robots.txt">
 
 Intlayer provides utilities to generate localized sitemaps and robots.txt files dynamically.
 
@@ -400,55 +452,9 @@ export const GET: APIRoute = ({ site }) => {
 };
 ```
 
-### Configure TypeScript
-
-Intlayer use module augmentation to get benefits of TypeScript and make your codebase stronger.
-
-![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 configurations
-  include: [
-    // ... Your existing TypeScript configurations
-    ".intlayer/**/*.ts", // Include the auto-generated types
-  ],
-}
-```
-
-### Git Configuration
-
-It is recommended to ignore the files generated by Intlayer. This allows you to avoid committing them to your Git repository.
-
-To do this, you can 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**.
-
-[Install 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 previews** of translated content.
-- **Quick actions** to easily create and update translations.
+</Step>
 
-For more details on how to use the extension, refer to the [Intlayer 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.
 
@@ -550,6 +556,58 @@ bun run build # Or bun run dev
 
 ---
 
+</Step>
+
+</Steps>
+
+### Configure TypeScript
+
+Intlayer use module augmentation to get benefits of TypeScript and make your codebase stronger.
+
+![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 configurations
+  include: [
+    // ... Your existing TypeScript configurations
+    ".intlayer/**/*.ts", // Include the auto-generated types
+  ],
+}
+```
+
+### Git Configuration
+
+It is recommended to ignore the files generated by Intlayer. This allows you to avoid committing them to your Git repository.
+
+To do this, you can 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**.
+
+[Install 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 previews** of translated content.
+- **Quick actions** to easily create and update translations.
+
+For more details on how to use the extension, refer to the [Intlayer VS Code Extension documentation](https://intlayer.org/doc/vs-code-extension).
+
+---
+
 ### Go Further
 
 To go further, you can implement the [visual editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md) or externalize your content using the [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md).

package/docs/en/intlayer_with_astro_vue.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2026-04-24
 updatedAt: 2026-05-31
-title: Astro + Vue i18n - Complete guide to translate an Astro + Vue app
-description: Optimized solution for bundle size, SEO, performances & maintainability. Make your Astro + Vue website multilingual in 2026, LLM translation, Agent Skills & MCP.
+title: "Astro + Vue i18n - Complete guide to translate your app"
+description: "No more i18next. The 2026 guide to building a multilingual (i18n) Astro + Vue app. Translate with AI agents and optimize bundle size, SEO and performances."
 keywords:
   - Internationalization
   - Documentation
@@ -58,16 +58,54 @@ history:
 
 <TOC/>
 
-## What is Intlayer?
+## Why Intlayer over alternatives?
 
-**Intlayer** is an innovative, open-source internationalization (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>
 
-- **Easily manage translations** using declarative dictionaries at the component level.
-- **Dynamically localize 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 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:
 
 See [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 package manager:
 
@@ -118,7 +158,9 @@ bun x intlayer init
 - **@astrojs/vue**
   The official Astro integration that enables Vue component islands.
 
-### 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:
 
@@ -142,7 +184,9 @@ export default config;
 
 > Through this configuration file, you can set up localized 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/configuration.md).
 
-### Step 3: Integrate Intlayer in Your Astro Configuration
+</Step>
+
+<Step number={3} title="Integrate Intlayer in Your Astro Configuration">
 
 Add the intlayer plugin and the Vue integration into your configuration.
 
@@ -163,7 +207,9 @@ export default defineConfig({
 
 > The `vue()` integration enables Vue component islands via `client:only="vue"`.
 
-### Step 4: Declare Your Content
+</Step>
+
+<Step number={4} title="Declare Your Content">
 
 Create and manage your content declarations to store translations:
 
@@ -188,7 +234,9 @@ export default appContent;
 
 > For more details, refer to the [content declaration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/content_file.md).
 
-### Step 5: Use your content in Astro
+</Step>
+
+<Step number={5} title="Use your content in Astro">
 
 You can consume dictionaries directly in `.astro` files using the core helpers exported by `intlayer`. You should also add SEO metadata like hreflang and canonical links to each page, and embed the Vue island for interactive client-side content.
 
@@ -268,7 +316,9 @@ const { title } = getIntlayer("app", locale);
 > - **`prefix-all`:** All URLs are prefixed with the locale. You can use standard `[locale]` if you don't need to handle the root separately.
 > - **`search-param` or `no-prefix`:** No locale folder is needed. The locale is handled via search parameters or cookies.
 
-### Step 6: Create the Vue Island component
+</Step>
+
+<Step number={6} title="Create the Vue Island component">
 
 Create the island component that wraps your Vue app and receives the server-detected locale. `installIntlayer` must be called to register the Intlayer plugin on the Vue instance before any composable is used.
 
@@ -327,7 +377,9 @@ const { title } = useIntlayer("app");
 
 > The `locale` prop is passed from the Astro page (server-detected) and used to initialise `installIntlayer`, which makes it the initial locale for all composables in the component tree.
 
-### Step 7: Add a Locale Switcher
+</Step>
+
+<Step number={7} title="Add a Locale Switcher">
 
 The locale switcher is embedded directly in the Vue island template (shown in Step 6). It uses `useLocale` from `vue-intlayer` and navigates to the localized URL when the user picks a new language:
 
@@ -375,7 +427,9 @@ const {
 > **Note on Persistence:**
 > Using `onLocaleChange` to redirect via `window.location.href` ensures that the new locale URL is visited, allowing Intlayer middleware to set the locale cookie and remember the user's preference on future visits.
 
-### Step 8: Sitemap and Robots.txt
+</Step>
+
+<Step number={8} title="Sitemap and Robots.txt">
 
 Intlayer provides utilities to generate localized sitemaps and robots.txt files dynamically.
 
@@ -435,55 +489,9 @@ export const GET: APIRoute = ({ site }) => {
 };
 ```
 
-### Configure TypeScript
-
-Intlayer use module augmentation to get benefits of TypeScript and make your codebase stronger.
+</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 configurations
-  include: [
-    // ... Your existing TypeScript configurations
-    ".intlayer/**/*.ts", // Include the auto-generated types
-  ],
-}
-```
-
-### Git Configuration
-
-It is recommended to ignore the files generated by Intlayer. This allows you to avoid committing them to your Git repository.
-
-To do this, you can 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**.
-
-[Install 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 previews** of translated content.
-- **Quick actions** to easily create and update translations.
-
-For more details on how to use the extension, refer to the [Intlayer 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.
 
@@ -585,6 +593,58 @@ bun run build # Or bun run dev
 
 ---
 
+</Step>
+
+</Steps>
+
+### Configure TypeScript
+
+Intlayer use module augmentation to get benefits of TypeScript and make your codebase stronger.
+
+![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 configurations
+  include: [
+    // ... Your existing TypeScript configurations
+    ".intlayer/**/*.ts", // Include the auto-generated types
+  ],
+}
+```
+
+### Git Configuration
+
+It is recommended to ignore the files generated by Intlayer. This allows you to avoid committing them to your Git repository.
+
+To do this, you can 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**.
+
+[Install 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 previews** of translated content.
+- **Quick actions** to easily create and update translations.
+
+For more details on how to use the extension, refer to the [Intlayer VS Code Extension documentation](https://intlayer.org/doc/vs-code-extension).
+
+---
+
 ### Go Further
 
 To go further, you can implement the [visual editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md) or externalize your content using the [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md).