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

package/docs/en-GB/intlayer_with_astro.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-03-07
-updatedAt: 2026-05-31
+updatedAt: 2026-06-23
 title: "Astro i18n - Complete guide to translate your app"
 description: "No more i18next. The 2026 guide to building a multilingual (i18n) Astro app. Translate with AI agents and optimise bundle size, SEO and performances."
 keywords:
@@ -317,7 +317,134 @@ The Astro integration adds a Vite middleware that helps with language-sensitive
 
 </Step>
 
-<Step number={7} title="Continue Using Your Favourite Frameworks">
+<Step number={7} title="Add a Locale Switcher">
+
+To allow users to switch between languages, you can create a `LocaleSwitcher` component. This component should display a list of all supported locales and link to the same page in each language.
+
+```astro fileName="src/components/LocaleSwitcher.astro"
+---
+import {
+  locales,
+  getLocaleName,
+  getLocalizedUrl,
+  getLocaleFromPath,
+  getPathWithoutLocale,
+  type LocalesValues,
+} from "intlayer";
+
+const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;
+const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);
+---
+
+<nav>
+  {
+    locales.map((localeItem) => (
+      <a
+        href={getLocalizedUrl(pathWithoutLocale, localeItem)}
+        data-locale={localeItem}
+        aria-current={localeItem === locale ? "page" : undefined}
+      >
+        {getLocaleName(localeItem)}
+      </a>
+    ))
+  }
+</nav>
+
+<script>
+  import { setLocaleInStorageClient, getLocalizedUrl, type LocalesValues } from "intlayer";
+
+  const localeLinks = document.querySelectorAll("[data-locale]");
+
+  localeLinks.forEach((link) => {
+    link.addEventListener("click", (e) => {
+      const locale = link.getAttribute("data-locale") as LocalesValues;
+
+      // Update the locale cookie
+      setLocaleInStorageClient(locale);
+    });
+  });
+</script>
+
+<style>
+  nav {
+    display: flex;
+    gap: 1rem;
+  }
+  a[aria-current="page"] {
+    font-weight: bold;
+    text-decoration: underline;
+  }
+</style>
+```
+
+> **Note on Persistence:**
+> Using `setLocaleInStorageClient` in the client-side script ensures that the user's language preference is saved in a cookie. This allows the Intlayer middleware to remember the choice and automatically redirect the user to their preferred language on future visits.
+
+</Step>
+
+<Step number={8} title="Sitemap and Robots.txt">
+
+Intlayer offers utilities to dynamically create your localised sitemap and robots.txt files.
+
+#### 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.
+
+> The Intlayer generated sitemap supports the `xhtml:link` namespace (Hreflang XML Extensions). Unlike the default sitemap generators that only list raw URLs, Intlayer automatically creates the required bidirectional links between all language versions of a page (e.g., `/about`, `/about?lang=fr`, and `/about?lang=es`). This ensures search engines correctly index and serve the right language version to the right audience.
+
+Create `src/pages/sitemap.xml.ts` to generate a sitemap including all your localised routes.
+
+```typescript fileName="src/pages/sitemap.xml.ts"
+import type { APIRoute } from "astro";
+import { generateSitemap, type SitemapUrlEntry } from "intlayer";
+
+const pathList: SitemapUrlEntry[] = [
+  { path: "/", changefreq: "daily", priority: 1.0 },
+  { path: "/about", changefreq: "monthly", priority: 0.7 },
+];
+
+const SITE_URL = import.meta.env.SITE ?? "http://localhost:4321";
+
+export const GET: APIRoute = async ({ site }) => {
+  const xmlOutput = generateSitemap(pathList, { siteUrl: SITE_URL });
+
+  return new Response(xmlOutput, {
+    headers: { "Content-Type": "application/xml" },
+  });
+};
+```
+
+#### Robots.txt
+
+Create `src/pages/robots.txt.ts` to control search engine crawling.
+
+```typescript fileName="src/pages/robots.txt.ts"
+import type { APIRoute } from "astro";
+import { getMultilingualUrls } from "intlayer";
+
+const getAllMultilingualUrls = (urls: string[]) =>
+  urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);
+
+const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);
+
+export const GET: APIRoute = ({ site }) => {
+  const robotsTxt = [
+    "User-agent: *",
+    "Allow: /",
+    ...disallowedPaths.map((path) => `Disallow: ${path}`),
+    "",
+    `Sitemap: ${new URL("/sitemap.xml", site).href}`,
+  ].join("\n");
+
+  return new Response(robotsTxt, {
+    headers: { "Content-Type": "text/plain" },
+  });
+};
+```
+
+</Step>
+
+<Step number={9} title="Continue Using Your Favourite Frameworks">
 
 Keep building your application using the framework of your choice.
 

package/docs/en-GB/intlayer_with_astro_lit.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-04-24
-updatedAt: 2026-05-31
+updatedAt: 2026-06-23
 title: "Astro + Lit i18n - Complete guide to translate your app"
 description: "No more i18next. The 2026 guide to building a multilingual (i18n) Astro + Lit app. Translate with AI agents and optimise bundle size, SEO and performances."
 keywords:
@@ -122,27 +122,39 @@ Check out the [application template](https://github.com/aymericzip/intlayer-astr
 Install the necessary packages using your preferred package manager:
 
 ```bash packageManager="npm"
-npm install intlayer astro-intlayer lit lit-intlayer @astrojs/lit
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> the `--interactive` flag is optional. Use `intlayer-cli init` if you're an AI agent.
 
-npx intlayer init
+> This command will detect your environment and install the required packages. For example:
+
+```bash packageManager="npm"
+npm install intlayer astro-intlayer lit lit-intlayer @astrojs/lit
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer astro-intlayer lit lit-intlayer @astrojs/lit
-
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer astro-intlayer lit lit-intlayer @astrojs/lit
-
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer astro-intlayer lit lit-intlayer @astrojs/lit
-
-bun x intlayer init
 ```
 
 - **intlayer**

package/docs/en-GB/intlayer_with_astro_preact.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-04-24
-updatedAt: 2026-05-31
+updatedAt: 2026-06-23
 title: "Astro + Preact i18n - Complete guide to translate your app"
 description: "No more i18next. The 2026 guide to building a multilingual (i18n) Astro + Preact app. Translate with AI agents and optimise bundle size, SEO and performances."
 keywords:
@@ -121,27 +121,39 @@ Check out the [application template](https://github.com/aymericzip/intlayer-astr
 Install the necessary packages using your preferred package manager:
 
 ```bash packageManager="npm"
-npm install intlayer astro-intlayer preact preact-intlayer @astrojs/preact
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> the `--interactive` flag is optional. Use `intlayer-cli init` if you're an AI agent.
 
-npx intlayer init
+> This command will detect your environment and install the required packages. For example:
+
+```bash packageManager="npm"
+npm install intlayer astro-intlayer preact preact-intlayer @astrojs/preact
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer astro-intlayer preact preact-intlayer @astrojs/preact
-
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer astro-intlayer preact preact-intlayer @astrojs/preact
-
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer astro-intlayer preact preact-intlayer @astrojs/preact
-
-bun x intlayer init
 ```
 
 - **intlayer**

package/docs/en-GB/intlayer_with_astro_react.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-03-07
-updatedAt: 2026-05-31
+updatedAt: 2026-06-23
 title: "Astro + React i18n - Complete guide to translate your app"
 description: "No more i18next. The 2026 guide to building a multilingual (i18n) Astro + React app. Translate with AI agents and optimise bundle size, SEO and performances."
 keywords:
@@ -124,27 +124,39 @@ Check out the [application template](https://github.com/aymericzip/intlayer-astr
 Install the necessary packages using your preferred package manager:
 
 ```bash packageManager="npm"
-npm install intlayer astro-intlayer react react-dom react-intlayer @astrojs/react
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> the `--interactive` flag is optional. Use `intlayer-cli init` if you're an AI agent.
 
-npx intlayer init
+> This command will detect your environment and install the required packages. For example:
+
+```bash packageManager="npm"
+npm install intlayer astro-intlayer react react-dom react-intlayer @astrojs/react
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer astro-intlayer react react-dom react-intlayer @astrojs/react
-
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer astro-intlayer react react-dom react-intlayer @astrojs/react
-
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer astro-intlayer react react-dom react-intlayer @astrojs/react
-
-bun x intlayer init
 ```
 
 - **intlayer**

package/docs/en-GB/intlayer_with_astro_solid.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-04-24
-updatedAt: 2026-05-31
+updatedAt: 2026-06-23
 title: "Astro + Solid i18n - Complete guide to translate your app"
 description: "No more i18next. The 2026 guide to building a multilingual (i18n) Astro + Solid app. Translate with AI agents and optimise bundle size, SEO and performances."
 keywords:
@@ -121,27 +121,39 @@ Check out the [application template](https://github.com/aymericzip/intlayer-astr
 Install the necessary packages using your preferred package manager:
 
 ```bash packageManager="npm"
-npm install intlayer astro-intlayer solid-js solid-intlayer @astrojs/solid-js
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> the `--interactive` flag is optional. Use `intlayer-cli init` if you're an AI agent.
 
-npx intlayer init
+> This command will detect your environment and install the required packages. For example:
+
+```bash packageManager="npm"
+npm install intlayer astro-intlayer solid-js solid-intlayer @astrojs/solid-js
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer astro-intlayer solid-js solid-intlayer @astrojs/solid-js
-
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer astro-intlayer solid-js solid-intlayer @astrojs/solid-js
-
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer astro-intlayer solid-js solid-intlayer @astrojs/solid-js
-
-bun x intlayer init
 ```
 
 - **intlayer**

package/docs/en-GB/intlayer_with_astro_svelte.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-04-24
-updatedAt: 2026-05-31
+updatedAt: 2026-06-23
 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:
@@ -121,27 +121,39 @@ Check out the [application template](https://github.com/aymericzip/intlayer-astr
 Install the necessary packages using your preferred package manager:
 
 ```bash packageManager="npm"
-npm install intlayer astro-intlayer svelte svelte-intlayer @astrojs/svelte
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> the `--interactive` flag is optional. Use `intlayer-cli init` if you're an AI agent.
 
-npx intlayer init
+> This command will detect your environment and install the required packages. For example:
+
+```bash packageManager="npm"
+npm install intlayer astro-intlayer svelte svelte-intlayer @astrojs/svelte
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer astro-intlayer svelte svelte-intlayer @astrojs/svelte
-
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer astro-intlayer svelte svelte-intlayer @astrojs/svelte
-
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer astro-intlayer svelte svelte-intlayer @astrojs/svelte
-
-bun x intlayer init
 ```
 
 - **intlayer**

package/docs/en-GB/intlayer_with_astro_vanilla.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-04-24
-updatedAt: 2026-05-31
+updatedAt: 2026-06-23
 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:
@@ -121,27 +121,39 @@ Check out the [application template](https://github.com/aymericzip/intlayer-astr
 Install the necessary packages using your preferred package manager:
 
 ```bash packageManager="npm"
-npm install intlayer astro-intlayer vanilla-intlayer
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> the `--interactive` flag is optional. Use `intlayer-cli init` if you're an AI agent.
 
-npx intlayer init
+> This command will detect your environment and install the required packages. For example:
+
+```bash packageManager="npm"
+npm install intlayer astro-intlayer vanilla-intlayer
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer astro-intlayer vanilla-intlayer
-
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer astro-intlayer vanilla-intlayer
-
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer astro-intlayer vanilla-intlayer
-
-bun x intlayer init
 ```
 
 - **intlayer**

package/docs/en-GB/intlayer_with_astro_vue.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-04-24
-updatedAt: 2026-05-31
+updatedAt: 2026-06-23
 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 optimise bundle size, SEO and performances."
 keywords:
@@ -121,27 +121,39 @@ Check out the [application template](https://github.com/aymericzip/intlayer-astr
 Install the necessary packages using your preferred package manager:
 
 ```bash packageManager="npm"
-npm install intlayer astro-intlayer vue vue-intlayer @astrojs/vue
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> the `--interactive` flag is optional. Use `intlayer-cli init` if you're an AI agent.
 
-npx intlayer init
+> This command will detect your environment and install the required packages. For example:
+
+```bash packageManager="npm"
+npm install intlayer astro-intlayer vue vue-intlayer @astrojs/vue
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer astro-intlayer vue vue-intlayer @astrojs/vue
-
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer astro-intlayer vue vue-intlayer @astrojs/vue
-
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer astro-intlayer vue vue-intlayer @astrojs/vue
-
-bun x intlayer init
 ```
 
 - **intlayer**

package/docs/en-GB/intlayer_with_create_react_app.md

@@ -33,17 +33,6 @@ author: aymericzip
 
 See [Application Template](https://github.com/aymericzip/intlayer-react-cra-template) on GitHub.
 
-## What is Intlayer?
-
-**Intlayer** is an innovative, open-source internationalisation (i18n) library designed to simplify multilingual support in modern web applications.
-
-With Intlayer, you can:
-
-- **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.
-
 ## Step-by-Step Guide to Set Up Intlayer in a React Application
 
 <Steps>
@@ -52,24 +41,40 @@ With Intlayer, you can:
 
 Install the necessary packages using npm:
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> the `--interactive` flag is optional. Use `intlayer-cli init` if you're an AI agent.
+
+> This command will detect your environment and install the required packages. For example:
+
 ```bash packageManager="npm"
 npm install intlayer react-intlayer react-scripts-intlayer
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer react-intlayer react-scripts-intlayer
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer react-intlayer react-scripts-intlayer
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer react-intlayer react-scripts-intlayer
-bun x intlayer init
 ```
 
 - **intlayer**
@@ -82,51 +87,48 @@ bun x intlayer init
 
 - **react-scripts-intlayer**
 
-# Getting Started Internationalising (i18n) with Intlayer and React Create App
-
-See [Application Template](https://github.com/aymericzip/intlayer-react-cra-template) on GitHub.
-
-</Step>
+## Step-by-Step Guide to Set Up Intlayer in a React Application
 
-</Steps>
+<Steps>
 
-## What is Intlayer?
+<Step number={1} title="Install Dependencies">
 
-**Intlayer** is an innovative, open-source internationalisation (i18n) library designed to simplify multilingual support in modern web applications.
+Install the necessary packages using npm:
 
-With Intlayer, you can:
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
 
-- **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.
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
 
-## Step-by-Step Guide to Set Up Intlayer in a React Application
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
 
-<Steps>
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
 
-<Step number={1} title="Install Dependencies">
+> the `--interactive` flag is optional. Use `intlayer-cli init` if you're an AI agent.
 
-Install the necessary packages using npm:
+> This command will detect your environment and install the required packages. For example:
 
 ```bash packageManager="npm"
 npm install intlayer react-intlayer react-scripts-intlayer
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer react-intlayer react-scripts-intlayer
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer react-intlayer react-scripts-intlayer
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer react-intlayer react-scripts-intlayer
-bun x intlayer init
 ```
 
 - **intlayer**
@@ -695,22 +697,6 @@ By applying these changes, your application will:
 
 ### 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)
-
-module.exports = App;
-
-By applying these changes, your application will:
-
-- Ensure the **language** (`lang`) attribute correctly reflects the current locale, which is important for SEO and browser behaviour.
-- Adjust the **text direction** (`dir`) according to the locale, enhancing readability and usability for languages with different reading orders.
-- Provide a more **accessible** experience, as assistive technologies depend on these attributes to function optimally.
-
-### Configure TypeScript
-
 Intlayer uses module augmentation to get the benefits of TypeScript and make your codebase stronger.
 
 ![Autocompletion](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true)