@intlayer/docs 5.5.8

package/en-GB/intlayer_with_vite+vue.md

@@ -0,0 +1,993 @@
+# Getting Started Internationalising (i18n) with Intlayer and Vite and Vue
+
+> This package is in development. See the [issue](https://github.com/aymericzip/intlayer/issues/113) for more information. Show your interest in Intlayer for Vue by liking the issue
+
+<!-- See [Application Template](https://github.com/aymericzip/intlayer-vue-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 Vite and Vue Application
+
+### Step 1: Install Dependencies
+
+Install the necessary packages using npm:
+
+```bash packageManager="npm"
+npm install intlayer vue-intlayer vite-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer vue-intlayer vite-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add intlayer vue-intlayer vite-intlayer
+```
+
+- **intlayer**
+
+  The core package that provides internationalisation tools for configuration management, translation, [content declaration](https://github.com/aymericzip/intlayer/blob/main/docs/en-GB/dictionary/get_started.md), transpilation, and [CLI commands](https://github.com/aymericzip/intlayer/blob/main/docs/en-GB/intlayer_cli.md).
+
+- **vue-intlayer**
+  The package that integrates Intlayer with Vue application. It provides context providers and composables for Vue internationalisation.
+
+- **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
+
+Create a config file to configure the languages of your application:
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalisation: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // Your other locales
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+import { Locales } from "intlayer";
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalisation: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // Your other locales
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+const { Locales } = require("intlayer");
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalisation: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // Your other locales
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+module.exports = 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/en-GB/configuration.md).
+
+### Step 3: Integrate Intlayer in Your Vite Configuration
+
+Add the intlayer plugin into your configuration.
+
+```typescript fileName="vite.config.ts" codeFormat="typescript"
+import { defineConfig } from "vite";
+import vue from "@vitejs/plugin-vue";
+import { intlayerPlugin } from "vite-intlayer";
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [vue(), intlayerPlugin()],
+});
+```
+
+```javascript fileName="vite.config.mjs" codeFormat="esm"
+import { defineConfig } from "vite";
+import vue from "@vitejs/plugin-vue";
+import { intlayerPlugin } from "vite-intlayer";
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [vue(), intlayerPlugin()],
+});
+```
+
+```javascript fileName="vite.config.cjs" codeFormat="commonjs"
+const { defineConfig } = require("vite");
+const vue = require("@vitejs/plugin-vue");
+const { intlayerPlugin } = require("vite-intlayer");
+
+// https://vitejs.dev/config/
+module.exports = defineConfig({
+  plugins: [vue(), intlayerPlugin()],
+});
+```
+
+> The `intlayerPlugin()` 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: Declare Your Content
+
+Create and manage your content declarations to store translations:
+
+```tsx fileName="src/helloWorld.content.ts" contentDeclarationFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const helloWorldContent = {
+  key: "helloworld",
+  content: {
+    count: t({
+      "en-GB": "count is ",
+      en: "count is ",
+      fr: "le compte est ",
+      es: "el recuento es ",
+    }),
+    edit: t({
+      "en-GB":
+        "Edit <code>components/HelloWorld.vue</code> and save to test HMR",
+      en: "Edit <code>components/HelloWorld.vue</code> and save to test HMR",
+      fr: "Éditez <code>components/HelloWorld.vue</code> et enregistrez pour tester HMR",
+      es: "Edita <code>components/HelloWorld.vue</code> y guarda para probar HMR",
+    }),
+    checkOut: t({
+      "en-GB": "Check out ",
+      en: "Check out ",
+      fr: "Vérifiez ",
+      es: "Compruebe ",
+    }),
+    officialStarter: t({
+      "en-GB": ", the official Vue + Vite starter",
+      en: ", the official Vue + Vite starter",
+      fr: ", le starter officiel Vue + Vite",
+      es: ", el starter oficial Vue + Vite",
+    }),
+    learnMore: t({
+      "en-GB": "Learn more about IDE Support for Vue in the ",
+      en: "Learn more about IDE Support for Vue in the ",
+      fr: "En savoir plus sur le support IDE pour Vue dans le ",
+      es: "Aprenda más sobre el soporte IDE para Vue en el ",
+    }),
+    vueDocs: t({
+      "en-GB": "Vue Docs Scaling up Guide",
+      en: "Vue Docs Scaling up Guide",
+      fr: "Vue Docs Scaling up Guide",
+      es: "Vue Docs Scaling up Guide",
+    }),
+    readTheDocs: t({
+      "en-GB": "Click on the Vite and Vue logos to learn more",
+      en: "Click on the Vite and Vue logos to learn more",
+      fr: "Cliquez sur les logos Vite et Vue pour en savoir plus",
+      es: "Haga clic en los logotipos de Vite y Vue para obtener más información",
+    }),
+  },
+} satisfies Dictionary;
+
+export default helloWorldContent;
+```
+
+```javascript fileName="src/helloWorld.content.mjs" contentDeclarationFormat="esm"
+import { t } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const helloWorldContent = {
+  key: "helloworld",
+  content: {
+    count: t({
+      "en-GB": "count is ",
+      en: "count is ",
+      fr: "le compte est ",
+      es: "el recuento es ",
+    }),
+    edit: t({
+      "en-GB":
+        "Edit <code>components/HelloWorld.vue</code> and save to test HMR",
+      en: "Edit <code>components/HelloWorld.vue</code> and save to test HMR",
+      fr: "Éditez <code>components/HelloWorld.vue</code> et enregistrez pour tester HMR",
+      es: "Edita <code>components/HelloWorld.vue</code> y guarda para probar HMR",
+    }),
+    checkOut: t({
+      "en-GB": "Check out ",
+      en: "Check out ",
+      fr: "Vérifiez ",
+      es: "Compruebe ",
+    }),
+    officialStarter: t({
+      "en-GB": "the official Vue + Vite starter",
+      en: "the official Vue + Vite starter",
+      fr: "le starter officiel Vue + Vite",
+      es: "el starter oficial Vue + Vite",
+    }),
+    learnMore: t({
+      "en-GB": "Learn more about IDE Support for Vue in the ",
+      en: "Learn more about IDE Support for Vue in the ",
+      fr: "En savoir plus sur le support IDE pour Vue dans le ",
+      es: "Aprenda más sobre el soporte IDE para Vue en el ",
+    }),
+    vueDocs: t({
+      "en-GB": "Vue Docs Scaling up Guide",
+      en: "Vue Docs Scaling up Guide",
+      fr: "Vue Docs Scaling up Guide",
+      es: "Vue Docs Scaling up Guide",
+    }),
+    readTheDocs: t({
+      "en-GB": "Click on the Vite and Vue logos to learn more",
+      en: "Click on the Vite and Vue logos to learn more",
+      fr: "Cliquez sur les logos Vite et Vue pour en savoir plus",
+      es: "Haga clic en los logotipos de Vite y Vue para obtener más información",
+    }),
+  },
+};
+
+export default helloWorldContent;
+```
+
+---
+
+const { t } = require("intlayer");
+
+/\*_ @type {import('intlayer').Dictionary} _/
+const appContent = {
+key: "helloworld",
+content: {
+count: t({ 'en-GB': "count is ", en: "count is ", fr: "le compte est ", es: "el recuento es " }),
+edit: t({
+'en-GB': "Edit <code>components/HelloWorld.vue</code> and save to test HMR",
+en: "Edit <code>components/HelloWorld.vue</code> and save to test HMR",
+fr: "Éditez <code>components/HelloWorld.vue</code> et enregistrez pour tester HMR",
+es: "Edita <code>components/HelloWorld.vue</code> y guarda para probar HMR",
+}),
+checkOut: t({ 'en-GB': "Check out ", en: "Check out ", fr: "Vérifiez ", es: "Compruebe " }),
+officialStarter: t({
+'en-GB': "the official Vue + Vite starter",
+en: "the official Vue + Vite starter",
+fr: "le starter officiel Vue + Vite",
+es: "el starter oficial Vue + Vite",
+}),
+learnMore: t({
+'en-GB': "Learn more about IDE Support for Vue in the ",
+en: "Learn more about IDE Support for Vue in the ",
+fr: "En savoir plus sur le support IDE pour Vue dans le ",
+es: "Aprenda más sobre el soporte IDE para Vue en el ",
+}),
+vueDocs: t({
+'en-GB': "Vue Docs Scaling up Guide",
+en: "Vue Docs Scaling up Guide",
+fr: "Vue Docs Scaling up Guide",
+es: "Vue Docs Scaling up Guide",
+}),
+readTheDocs: t({
+'en-GB': "Click on the Vite and Vue logos to learn more",
+en: "Click on the Vite and Vue logos to learn more",
+fr: "Cliquez sur les logos Vite et Vue pour en savoir plus",
+es: "Haga clic en los logotipos de Vite y Vue para obtener más información",
+}),
+},
+};
+
+module.exports = appContent;
+
+````
+
+```json fileName="src/helloWorld.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "helloworld",
+  "content": {
+    "count": {
+      "nodeType": "translation",
+      "translation": {
+        "en-GB": "count is ",
+        "en": "count is ",
+        "fr": "le compte est ",
+        "es": "el recuento es "
+      }
+    },
+    "edit": {
+      "nodeType": "translation",
+      "translation": {
+        "en-GB": "Edit <code>components/HelloWorld.vue</code> and save to test HMR",
+        "en": "Edit <code>components/HelloWorld.vue</code> and save to test HMR",
+        "fr": "Éditez <code>components/HelloWorld.vue</code> et enregistrez pour tester HMR",
+        "es": "Edita <code>components/HelloWorld.vue</code> y guarda para probar HMR"
+      }
+    },
+    "checkOut": {
+      "nodeType": "translation",
+      "translation": {
+        "en-GB": "Check out ",
+        "en": "Check out ",
+        "fr": "Vérifiez ",
+        "es": "Compruebe "
+      }
+    },
+    "officialStarter": {
+      "nodeType": "translation",
+      "translation": {
+        "en-GB": "the official Vue + Vite starter",
+        "en": "the official Vue + Vite starter",
+        "fr": "le starter officiel Vue + Vite",
+        "es": "el starter oficial Vue + Vite"
+      }
+    },
+    "learnMore": {
+      "nodeType": "translation",
+      "translation": {
+        "en-GB": "Learn more about IDE Support for Vue in the ",
+        "en": "Learn more about IDE Support for Vue in the ",
+        "fr": "En savoir plus sur le support IDE pour Vue dans le ",
+        "es": "Aprenda más sobre el soporte IDE para Vue en el "
+      }
+    },
+    "vueDocs": {
+      "nodeType": "translation",
+      "translation": {
+        "en-GB": "Vue Docs Scaling up Guide",
+        "en": "Vue Docs Scaling up Guide",
+        "fr": "Vue Docs Scaling up Guide",
+        "es": "Vue Docs Scaling up Guide"
+      }
+    },
+    "readTheDocs": {
+      "nodeType": "translation",
+      "translation": {
+        "en-GB": "Click on the Vite and Vue logos to learn more",
+        "en": "Click on the Vite and Vue logos to learn more",
+        "fr": "Cliquez sur les logos Vite et Vue pour en savoir plus",
+        "es": "Haga clic en los logotipos de Vite y Vue para obtener más información"
+      }
+    }
+  }
+}
+````
+
+> Your content declarations can be defined anywhere in your application as long as they are included in the `contentDir` directory (by default, `./src`). They must also match the content declaration file extension (by default, `.content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}`).
+
+> For more details, refer to the [content declaration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en-GB/dictionary/get_started.md).
+
+### Step 5: Utilise Intlayer in Your Code
+
+To utilise Intlayer's internationalisation features throughout your Vue application, you first need to register the Intlayer singleton instance in your main file. This step is crucial as it provides the internationalisation context to all components in your application, making translations accessible anywhere in your component tree.
+
+```javascript fileName=main.js
+import { createApp } from "vue";
+import { installIntlayer } from "vue-intlayer";
+import App from "./App.vue";
+import "./style.css";
+
+const app = createApp(App);
+
+// Inject the provider at the top level
+installIntlayer(app);
+
+// Mount the app
+app.mount("#app");
+```
+
+Access your content dictionaries throughout your application by creating a main Vue component and using the `useIntlayer` composables:
+
+```vue fileName="src/HelloWord.vue"
+<script setup lang="ts">
+import { ref } from "vue";
+import { useIntlayer } from "vue-intlayer";
+
+defineProps({
+  msg: String,
+});
+
+const content = useIntlayer("helloworld");
+const count = ref(0);
+</script>
+
+<template>
+  <h1>{{ msg }}</h1>
+
+  <div class="card">
+    <button type="button" @click="count++">
+      {{ content.count }}{{ count }}
+    </button>
+    <p v-html="content.edit.value"></p>
+  </div>
+
+  <p>
+    {{ content.checkOut }}
+    <a href="https://vuejs.org/guide/quick-start.html#local" target="_blank"
+      >create-vue</a
+    >, {{ content.officialStarter }}
+  </p>
+  <p>
+    {{ content.learnMore }}
+    <a
+      href="https://vuejs.org/guide/scaling-up/tooling.html#ide-support"
+      target="_blank"
+      >{{ content.vueDocs }}</a
+    >.
+  </p>
+  <p class="read-the-docs">{{ content.readTheDocs }}</p>
+</template>
+```
+
+> If you want to use your content in an attribute, such as `alt`, `title`, `href`, `aria-label`, etc., you must call the value of the function with `.value`, like:
+
+> ```html
+>
+> ```
+
+> <img src="./logo.svg" :alt="content.image.value" />
+
+> ```
+>
+> ```
+
+### (Optional) Step 6: Change the language of your content
+
+To change the language of your content, you can use the `setLocale` function provided by the `useLocale` composable. This function allows you to set the locale of the application and update the content accordingly.
+
+Create a component to switch between languages:
+
+```vue fileName="src/components/LocaleSwitcher.vue"
+<template>
+  <div class="locale-switcher">
+    <select v-model="selectedLocale" @change="changeLocale">
+      <option v-for="loc in availableLocales" :key="loc" :value="loc">
+        {{ getLocaleName(loc) }}
+      </option>
+    </select>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, watch } from "vue";
+import { getLocaleName } from "intlayer";
+import { useLocale } from "vue-intlayer";
+
+// Get locale information and setLocale function
+const { locale, availableLocales, setLocale } = useLocale();
+
+// Track the selected locale with a ref
+const selectedLocale = ref(locale.value);
+
+// Update the locale when the selection changes
+const changeLocale = () => setLocale(selectedLocale.value);
+
+// Keep the selectedLocale in sync with the global locale
+watch(
+  () => locale.value,
+  (newLocale) => {
+    selectedLocale.value = newLocale;
+  }
+);
+</script>
+```
+
+Then, use this component in your App.vue:
+
+```vue fileName="src/App.vue"
+<script setup lang="ts">
+import { useIntlayer } from "vue-intlayer";
+import HelloWorld from "@components/HelloWorld.vue";
+import LocaleSwitcher from "@components/LocaleSwitcher.vue";
+import { ref, watch } from "vue";
+
+const content = useIntlayer("app"); // Create related intlayer declaration file
+</script>
+
+<template>
+  <div>
+    <LocaleSwitcher />
+    <a href="https://vite.dev" target="_blank">
+      <img src="/vite.svg" class="logo" :alt="content.viteLogo" />
+    </a>
+    <a href="https://vuejs.org/" target="_blank">
+      <img src="./assets/vue.svg" class="logo vue" :alt="content.vueLogo" />
+    </a>
+  </div>
+  <HelloWorld :msg="content.title" />
+</template>
+```
+
+### (Optional) Step 7: Add localised Routing to your application
+
+Adding localised routing in a Vue application typically involves using Vue Router with locale prefixes. This makes unique routes for each language, which is useful for SEO and SEO-friendly URLs.
+
+Example:
+
+```plaintext
+- https://example.com/about
+
+- https://example.com/en-GB/about
+- https://example.com/fr/about
+```
+
+First, install Vue Router:
+
+```bash packageManager="npm"
+npm install intlayer vue-router
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer vue-router
+```
+
+```bash packageManager="yarn"
+yarn add intlayer vue-router
+```
+
+Then, create a router configuration that handles locale-based routing:
+
+```js fileName="src/router/index.ts"
+import {
+  configuration,
+  getPathWithoutLocale,
+  localeFlatMap,
+  type Locales,
+} from 'intlayer';
+import { createIntlayerClient } from 'vue-intlayer';
+import { createRouter, createWebHistory } from 'vue-router';
+import HomeView from './views/home/HomeView.vue';
+import RootView from './views/root/Root.vue';
+
+// Get internationalisation configuration
+const { internationalisation, middleware } = configuration;
+const { defaultLocale } = internationalisation;
+
+/**
+ * Declare the routes with locale-specific paths and metadata.
+ */
+const routes = localeFlatMap((localisedData) => [
+  {
+    path: `${localisedData.urlPrefix}/`,
+    name: `Root-${localisedData.locale}`,
+    component: RootView,
+    meta: {
+      locale: localisedData.locale,
+    },
+  },
+  {
+    path: `${localisedData.urlPrefix}/home`,
+    name: `Home-${localisedData.locale}`,
+    component: HomeView,
+    meta: {
+      locale: localisedData.locale,
+    },
+  },
+]);
+
+// Create the router instance
+export const router = createRouter({
+  history: createWebHistory(),
+  routes,
+});
+
+// Add navigation guard for locale handling
+router.beforeEach((to, _from, next) => {
+  const client = createIntlayerClient();
+
+  const metaLocale = to.meta.locale as Locales | undefined;
+
+  if (metaLocale) {
+    // Reuse the locale defined in the route meta
+    client.setLocale(metaLocale);
+    next();
+  } else {
+    // Fallback: no locale in meta, possibly unmatched route
+    // Optional: handle 404 or redirect to default locale
+    client.setLocale(defaultLocale);
+
+    if (middleware.prefixDefault) {
+      next(`/${defaultLocale}${getPathWithoutLocale(to.path)}`);
+    } else {
+      next(getPathWithoutLocale(to.path));
+    }
+  }
+});
+```
+
+> The name is used to identify the route in the router. It should be unique across all routes to avoid conflicts and ensure proper navigation and linking.
+
+Then, register the router in your main.js file:
+
+```js fileName="src/main.ts"
+import { createApp } from "vue";
+import App from "./App.vue";
+import { router } from "./router";
+import "./style.css";
+
+const app = createApp(App);
+
+// Add the router to the app
+app.use(router);
+
+// Mount the app
+app.mount("#app");
+```
+
+Then update your `App.vue` file to render the RouterView component. This component will display the matched component for the current route.
+
+```vue fileName="src/App.vue"
+<script setup lang="ts">
+import LocaleSwitcher from "@components/LocaleSwitcher.vue";
+</script>
+
+<template>
+  <nav>
+    <LocaleSwitcher />
+  </nav>
+  <RouterView />
+</template>
+```
+
+In parallel, you can also use the `intLayerMiddlewarePlugin` 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.
+
+```typescript {3,7} fileName="vite.config.ts" codeFormat="typescript"
+import { defineConfig } from "vite";
+import vue from "@vitejs/plugin-vue";
+import { intlayerPlugin, intLayerMiddlewarePlugin } from "vite-intlayer";
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [vue(), intlayerPlugin(), intLayerMiddlewarePlugin()],
+});
+```
+
+```javascript {3,7} fileName="vite.config.mjs" codeFormat="esm"
+import { defineConfig } from "vite";
+import vue from "@vitejs/plugin-vue";
+import { intlayerPlugin, intLayerMiddlewarePlugin } from "vite-intlayer";
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [vue(), intlayerPlugin(), intLayerMiddlewarePlugin()],
+});
+```
+
+```javascript {3,7} fileName="vite.config.cjs" codeFormat="commonjs"
+const { defineConfig } = require("vite");
+const vue = require("@vitejs/plugin-vue");
+const { intlayerPlugin, intLayerMiddlewarePlugin } = require("vite-intlayer");
+
+// https://vitejs.dev/config/
+module.exports = defineConfig({
+  plugins: [vue(), intlayerPlugin(), intLayerMiddlewarePlugin()],
+});
+```
+
+### (Optional) Step 8: Change the URL when the locale changes
+
+To automatically update the URL when the user changes the language, you can modify the `LocaleSwitcher` component to use Vue Router:
+
+```vue fileName="src/components/LocaleSwitcher.vue"
+<template>
+  <div class="locale-switcher">
+    <select v-model="selectedLocale" @change="changeLocale">
+      <option v-for="loc in availableLocales" :key="loc" :value="loc">
+        {{ getLocaleName(loc) }}
+      </option>
+    </select>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, watch } from "vue";
+import { useRouter } from "vue-router";
+import { Locales, getLocaleName, getLocalizedUrl } from "intlayer";
+import { useLocale } from "vue-intlayer";
+
+// Get Vue Router
+const router = useRouter();
+
+// Get locale information and setLocale function
+const { locale, availableLocales, setLocale } = useLocale({
+  onLocaleChange: (newLocale) => {
+    // Get current route and create a localised URL
+    const currentPath = router.currentRoute.value.fullPath;
+    const localisedPath = getLocalizedUrl(currentPath, newLocale);
+
+    // Navigate to the localised route without reloading the page
+    router.push(localisedPath);
+  },
+});
+
+// Track the selected locale with a ref
+const selectedLocale = ref(locale.value);
+
+// Update the locale when the selection changes
+const changeLocale = () => {
+  setLocale(selectedLocale.value);
+};
+
+// Keep the selectedLocale in sync with the global locale
+watch(
+  () => locale.value,
+  (newLocale) => {
+    selectedLocale.value = newLocale;
+  }
+);
+</script>
+```
+
+Tip: For better SEO and accessibility, use tags as `<a href="/en-GB/home" hreflang="en-GB">` to link to localised pages, as shown in Step 10. This allows search engines to discover and index language-specific URLs properly. To preserve SPA behaviour, you can prevent the default navigation with @click.prevent, change the locale using useLocale, and programmatically navigate using Vue Router.
+
+```html
+<ol class="divide-text/20 divide-y divide-dashed overflow-y-auto p-1">
+  <li>
+    <a
+      hreflang="x-default"
+      aria-label="Switch to English"
+      target="_self"
+      aria-current="page"
+      href="/en-GB/doc/get-started"
+    >
+      <div>
+        <div>
+          <span dir="ltr" lang="en-GB">English</span><span>English</span>
+        </div>
+        <span>EN</span>
+      </div>
+    </a>
+  </li>
+  <li>
+    <a
+      hreflang="es"
+      aria-label="Switch to Spanish"
+      target="_self"
+      href="/es/doc/get-started"
+    >
+      <div>
+        <span dir="ltr" lang="es">Español</span><span>Spanish</span>
+        <span>ES</span>
+      </div>
+    </a>
+  </li>
+</ol>
+```
+
+### (Optional) Step 9: Switch the HTML Language and Direction Attributes
+
+When your application supports multiple languages, it's crucial to update the `<html>` tag's `lang` and `dir` attributes to match the current locale. Doing so ensures:
+
+- **Accessibility**: Screen readers and assistive technologies rely on the correct `lang` attribute to pronounce and interpret content accurately.
+- **Text Rendering**: The `dir` (direction) attribute ensures that text is rendered in the proper order (e.g., left-to-right for English, right-to-left for Arabic or Hebrew), which is essential for readability.
+- **SEO**: Search engines use the `lang` attribute to determine the language of your page, helping to serve the right localised content in search results.
+
+By updating these attributes dynamically when the locale changes, you guarantee a consistent and accessible experience for users across all supported languages.
+
+```js fileName="src/composables/useI18nHTMLAttributes.ts"
+import { watch } from "vue";
+import { useLocale } from "vue-intlayer";
+import { getHTMLTextDir } from "intlayer";
+
+/**
+ * Composable that updates the HTML <html> element's `lang` and `dir` attributes
+ * based on the current locale.
+ *
+ * @example
+ * // In your App.vue or a global component
+ * import { useI18nHTMLAttributes } from './composables/useI18nHTMLAttributes'
+ *
+ * useI18nHTMLAttributes()
+ */
+export function useI18nHTMLAttributes() {
+  const { locale } = useLocale();
+
+  // Update the HTML attributes whenever the locale changes
+  watch(
+    () => locale.value,
+    (newLocale) => {
+      if (!newLocale) return;
+
+      // Update the language attribute
+      document.documentElement.lang = newLocale;
+
+      // Set the text direction (ltr for most languages, rtl for Arabic, Hebrew, etc.)
+      document.documentElement.dir = getHTMLTextDir(newLocale);
+    },
+    { immediate: true }
+  );
+}
+```
+
+Use this composable in your `App.vue` or a global component:
+
+```vue fileName="src/App.vue"
+<script setup lang="ts">
+import { useI18nHTMLAttributes } from "@composables/useI18nHTMLAttributes";
+
+// Apply the HTML attributes based on the current locale
+useI18nHTMLAttributes();
+</script>
+
+<template>
+  <!-- Your app template -->
+</template>
+```
+
+### (Optional) Step 10: Creating a Localised Link Component
+
+To ensure that your application’s navigation respects the current locale, you can create a custom `Link` component. This component automatically prefixes internal URLs with the current language, so that, for example, when a French-speaking user clicks on a link to the "About" page, they are redirected to `/fr/about` instead of `/about`.
+
+This behaviour is useful for several reasons:
+
+- **SEO and User Experience**: Localised URLs help search engines index language-specific pages correctly and provide users with content in their preferred language.
+- **Consistency**: By using a localised link throughout your application, you guarantee that navigation stays within the current locale, preventing unexpected language switches.
+- **Maintainability**: Centralising the localisation logic in a single component simplifies the management of URLs, making your codebase easier to maintain and extend as your application grows.
+
+```vue fileName="src/components/Link.vue"
+<template>
+  <a :href="localisedHref" v-bind="$attrs">
+    <slot />
+  </a>
+</template>
+
+<script setup lang="ts">
+import { computed } from "vue";
+import { getLocalisedUrl } from "intlayer";
+import { useLocale } from "vue-intlayer";
+
+const props = defineProps({
+  href: {
+    type: String,
+    required: true,
+  },
+});
+
+const { locale } = useLocale();
+
+// Check if the link is external
+const isExternalLink = computed(() => /^https?:\/\//.test(props.href || ""));
+
+// Create a localised href for internal links
+const localisedHref = computed(() =>
+  isExternalLink.value ? props.href : getLocalisedUrl(props.href, locale.value)
+);
+</script>
+```
+
+For use with Vue Router, create a router-specific version:
+
+```vue fileName="src/components/RouterLink.vue"
+<template>
+  <router-link :to="localisedTo" v-bind="$attrs">
+    <slot />
+  </router-link>
+</template>
+
+<script setup lang="ts">
+import { computed } from "vue";
+import { getLocalisedUrl } from "intlayer";
+import { useLocale } from "vue-intlayer";
+
+const props = defineProps({
+  to: {
+    type: [String, Object],
+    required: true,
+  },
+});
+
+const { locale } = useLocale();
+
+// Create localised to-prop for router-link
+const localisedTo = computed(() => {
+  if (typeof props.to === "string") {
+    return getLocalisedUrl(props.to, locale.value);
+  } else {
+    // If 'to' is an object, localise the path property
+    return {
+      ...props.to,
+      path: getLocalisedUrl(props.to.path ?? "/", locale.value),
+    };
+  }
+});
+</script>
+```
+
+Use these components in your application:
+
+```vue fileName="src/App.vue"
+<template>
+  <div>
+    <!-- Vue router  -->
+    <RouterLink to="/">Root</RouterLink>
+    <RouterLink to="/home">Home</RouterLink>
+    <!-- Other -->
+    <Link href="/">Root</Link>
+    <Link href="/home">Home</Link>
+  </div>
+</template>
+
+<script setup lang="ts">
+import Link from "@components/Link.vue";
+import RouterLink from "@components/RouterLink.vue";
+</script>
+```
+
+### Configure TypeScript
+
+Intlayer uses module augmentation to get the benefits of TypeScript and make your codebase stronger.
+
+![alt text](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png)
+
+![alt text](https://github.com/aymericzip/intlayer/blob/main/docs/assets/translation_error.png)
+
+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:
+
+```plaintext
+# 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/en-GB/intlayer_visual_editor.md) or externalise your content using the [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/en-GB/intlayer_CMS.md).