@intlayer/docs 9.4.0-canary.0 → 9.4.1

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

@@ -364,6 +364,13 @@ app.use(intlayer);
 app.mount("#app");
 ```
 
+> You can also call `installIntlayer(app)` directly as a function if you prefer:
+>
+> ```javascript
+> import { intlayer } from "vue-intlayer";
+> app.use(intlayer);
+> ```
+
 Access your content dictionaries throughout your application by creating a main Vue component and using the `useIntlayer` composables:
 
 ```vue fileName="src/HelloWord.vue"
@@ -417,6 +424,8 @@ const countRef = ref(0);
 </template>
 ```
 
+> If your app already exists, you can use the [Intlayer Compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/compiler.md), as well as the [extract command](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/extract.md), to transform thousands of components in a second.
+
 #### Accessing Content in Intlayer
 
 Intlayer offers different APIs to access your content:
@@ -622,26 +631,6 @@ import LocaleSwitcher from "@components/LocaleSwitcher.vue";
 
 In parallel, you can also use the `intlayerProxy` to add server-side routing to your application. This plugin will automatically detect the current locale based on the URL and set the appropriate locale cookie. If no locale is specified, the plugin will determine the most appropriate locale based on the user's browser language preferences. If no locale is detected, it will redirect to the default locale.
 
-```typescript {3,7} fileName="vite.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
-import { defineConfig } from "vite";
-import vue from "@vitejs/plugin-vue";
-import { intlayer } from "vite-intlayer";
-
-// https://vitejs.dev/config/
-export default defineConfig({
-  plugins: [
-    vue(),
-    intlayer({
-      proxy: {
-        ignore: (req) => req.url?.startsWith("/api"),
-      },
-    }),
-  ],
-});
-```
-
-</Step>
-
 <Step number={8} title="Change the URL when the locale changes" isOptional={true}>
 
 To automatically update the URL when the user changes the language, you can modify the `LocaleSwitcher` component to use Vue Router:
@@ -801,27 +790,160 @@ export const useI18nHTMLAttributes = () => {
       // Update the language attribute
       document.documentElement.lang = newLocale;
 
+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:
+
       // Set the text direction (ltr for most languages, rtl for Arabic, Hebrew, etc.)
       document.documentElement.dir = getHTMLTextDir(newLocale);
     },
     { immediate: true }
   );
 };
+
+```vue fileName="src/components/Link.vue"
+<script setup lang="ts">
+import { getLocalizedUrl } from "intlayer";
+import { computed } from "vue";
+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 localizedHref = computed(() =>
+  isExternalLink.value ? props.href : getLocalizedUrl(props.href, locale.value)
+);
+</script>
+
+<template>
+  <a :href="localizedHref" v-bind="$attrs">
+    <slot />
+  </a>
+</template>
+```
+
+For use with Vue Router, create a router-specific version:
+
+```vue fileName="src/components/RouterLink.vue"
+<script setup lang="ts">
+import { getLocalizedUrl } from "intlayer";
+import { computed } from "vue";
+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 localizedTo = computed(() => {
+  if (typeof props.to === "string") {
+    return getLocalizedUrl(props.to, locale.value);
+  } else {
+    // If 'to' is an object, localise the path property
+    return {
+      ...props.to,
+      path: getLocalizedUrl(props.to.path ?? "/", locale.value),
+    };
+  }
+});
+</script>
+
+<template>
+  <router-link :to="localizedTo" v-bind="$attrs">
+    <slot />
+  </router-link>
+</template>
+```
+
+Use these components in your application:
+
 ````
 
 Use this composable in your `App.vue` or a global component:
 
-```vue fileName="src/App.vue"
+````vue fileName="src/App.vue"
+
+</Step>
+
 <script setup lang="ts">
 import { useI18nHTMLAttributes } from "@composables/useI18nHTMLAttributes";
 
+If you have an existing codebase, transforming thousands of files can be time-consuming.
+
+To ease this process, Intlayer propose a [compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/compiler.md) / [extractor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/cli/extract.md) to transform your components and extract the content.
+
 // Apply the HTML attributes based on the current locale
 useI18nHTMLAttributes();
 </script>
 
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import { type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  // ... Rest of your config
+  compiler: {
+    /**
+     * Indicates if the compiler should be enabled.
+     */
+    enabled: true,
+
+    /**
+     * Defines the output files path
+     */
+    output: ({ fileName, extension }) => `./${fileName}${extension}`,
+
+    /**
+     * Indicates if the components should be saved after being transformed.
+     *
+     * - If `true`, the compiler will rewrite the component file in the disk. So the transformation will be permanent, and the compiler will skip the transformation for the next process. That way, the compiler can transform the app, and then it can be removed.
+     *
+     * - If `false`, the compiler will inject the `useIntlayer()` function call into the code in the build output only, and keep the base codebase intact. The transformation will be done only in memory.
+     */
+    saveComponents: false,
+
+    /**
+     * Dictionary key prefix
+     */
+    dictionaryKeyPrefix: "",
+  },
+};
+
+export default config;
+````
+
 <template>
   <!-- Your app template -->
 </template>
+
+Run the extractor to transform your components and extract the content
+
+```bash packageManager="npm"
+npx intlayer extract
+```
+
+```bash packageManager="pnpm"
+pnpm intlayer extract
+```
+
+```bash packageManager="yarn"
+yarn intlayer extract
+```
+
 ```
 
 </Step>
@@ -835,7 +957,12 @@ useI18nHTMLAttributes();
 );
 };
 
-````
+```
+
+ </Tab>
+ <Tab value='Babel compiler'>
+
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
 
 Use this composable in your `App.vue` or a global component:
 
@@ -850,7 +977,23 @@ useI18nHTMLAttributes();
 <template>
   <!-- Your app template -->
 </template>
-````
+```
+
+```bash packageManager="npm"
+npm run build # Or npm run dev
+```
+
+```bash packageManager="pnpm"
+pnpm run build # Or pnpm run dev
+```
+
+```bash packageManager="yarn"
+yarn build # Or yarn dev
+```
+
+```bash packageManager="bun"
+bun run build # Or bun run dev
+```
 
 </Step>
 
@@ -981,3 +1124,5 @@ For more details on how to use the extension, refer to the [Intlayer VS Code Ext
 ### Go Further
 
 To go further, you can implement the [visual editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_visual_editor.md) or externalise your content using the [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_CMS.md).
+
+---

package/docs/en-GB/live-sync.md

@@ -41,8 +41,6 @@ Live Sync allows your app to reflect CMS content changes at runtime. No rebuild
 
 ## Enabling Live Sync
 
-> Live Sync requires a continuous server connection and is available on the enterprise plan.
-
 Enable Live Sync by updating your Intlayer configuration:
 
 ```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
@@ -84,6 +82,19 @@ export default config;
 
 Start the Live Sync server to wrap your application:
 
+Example using standalone server:
+
+```json5 fileName="package.json"
+{
+  "scripts": {
+    // ... other scripts
+    "live:start": "npx intlayer live",
+  },
+}
+```
+
+You can also use your application server in parallel using the `--process` argument.
+
 Example using Next.js:
 
 ```json5 fileName="package.json"

package/docs/en-GB/packages/elysia-intlayer/exports.md

@@ -0,0 +1,134 @@
+---
+createdAt: 2026-08-24
+updatedAt: 2026-08-24
+title: elysia-intlayer Package Documentation
+description: Elysia plugin for Intlayer, providing translation functions and locale detection.
+keywords:
+  - elysia-intlayer
+  - elysia
+  - plugin
+  - internationalisation
+  - i18n
+slugs:
+  - doc
+  - packages
+  - elysia-intlayer
+  - exports
+history:
+  - version: 9.4.0
+    date: 2026-08-24
+    changes: "Unified documentation for all exports"
+author: aymericzip
+---
+
+# elysia-intlayer Package
+
+The `elysia-intlayer` package provides a plugin for Elysia applications to handle internationalisation. It detects the user's locale and injects an `intlayer` object into the route context.
+
+## Installation
+
+```bash packageManager="npm"
+npm install intlayer elysia-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer elysia-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add intlayer elysia-intlayer
+```
+
+```bash packageManager="bun"
+bun add intlayer elysia-intlayer
+```
+
+> `elysia` is a peer dependency (`>=1.0.0`). Elysia targets the **Bun** runtime.
+
+## Exports
+
+### Plugin
+
+Import:
+
+```ts
+import { intlayer } from "elysia-intlayer";
+```
+
+| Function   | Description                                                                                                                                                                                                                                                                                                                    | Related documentation                                                                                             |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
+| `intlayer` | Elysia plugin that integrates Intlayer into your Elysia application. Handles locale detection from storage (cookies, headers) then from `Accept-Language`, injects an `intlayer` object exposing `locale`, `t`, `getIntlayer` and `getDictionary` into the route context, and sets up the `AsyncLocalStorage` request context. | [intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/elysia-intlayer/intlayer.md) |
+
+### Functions
+
+Import:
+
+```ts
+import { t, getIntlayer, getDictionary } from "elysia-intlayer";
+```
+
+| Function        | Description                                                                                                                                                                                                                                                             | Related documentation                                                                                     |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `t`             | Global translation function that retrieves content for the current locale in Elysia. Uses `AsyncLocalStorage` to access the request context set up by the `intlayer` plugin, and falls back to the default locale outside of it. Can also be accessed via `intlayer.t`. | [translation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/translation.md) |
+| `getIntlayer`   | Retrieves a dictionary by its key from the generated declaration and returns its content for the current locale. Optimised version of `getDictionary`. Uses `AsyncLocalStorage` to access the request context. Can also be accessed via `intlayer.getIntlayer`.         | -                                                                                                         |
+| `getDictionary` | Processes dictionary objects and returns content for the current locale. Processes `t()` translations, enumerations, markdown, HTML, etc. Uses `AsyncLocalStorage` to access the request context. Can also be accessed via `intlayer.getDictionary`.                    | -                                                                                                         |
+
+### Types
+
+Import:
+
+```ts
+import type { IntlayerContext, TranslateFunction } from "elysia-intlayer";
+```
+
+| Type                | Description                                                                                                                                                            |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `IntlayerContext`   | Shape of the `intlayer` object injected into every route context: `locale`, `locale_storage`, `locale_detected`, `defaultLocale`, `t`, `getIntlayer`, `getDictionary`. |
+| `TranslateFunction` | Signature of the translation function, translating a locale map into the content matching the current request locale.                                                  |
+
+## Usage
+
+```ts fileName="src/index.ts"
+import { Elysia } from "elysia";
+import { getDictionary, getIntlayer, intlayer, t } from "elysia-intlayer";
+import dictionaryExample from "./index.content";
+
+const app = new Elysia()
+  // Load the internationalisation plugin
+  .use(intlayer())
+  // Read the locale and the helpers from the route context
+  .get("/", ({ intlayer }) => ({
+    locale: intlayer!.locale,
+    greeting: intlayer!.t({
+      en: "Hello",
+      fr: "Bonjour",
+      es: "Hola",
+    }),
+    content: intlayer!.getIntlayer("index").exampleOfContent,
+  }))
+  // Or use the standalone helpers, bound to the current request
+  .get("/t_example", () =>
+    t({
+      en: "Example of returned content in English",
+      fr: "Exemple de contenu renvoyé en français",
+      es: "Ejemplo de contenido devuelto en español",
+    })
+  )
+  .get("/getIntlayer_example", () => getIntlayer("index").exampleOfContent)
+  .get(
+    "/getDictionary_example",
+    () => getDictionary(dictionaryExample).exampleOfContent
+  )
+  .listen(3000);
+
+console.log(
+  `🦊 Elysia is running at ${app.server?.hostname}:${app.server?.port}`
+);
+```
+
+> The plugin registers its context through a **global** `derive`, which Elysia types as `Partial<{ intlayer: IntlayerContext }>`. The value is always present at runtime for routes registered after `.use(intlayer())`, so use the non-null assertion (`intlayer!.locale`) — or optional chaining — to satisfy TypeScript in `strict` mode.
+
+## Related Doc
+
+- [Elysia i18n - Complete guide to translate your app](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_with_elysia.md)
+- [Configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md)

package/docs/en-GB/packages/elysia-intlayer/intlayer.md

@@ -0,0 +1,137 @@
+---
+createdAt: 2026-08-24
+updatedAt: 2026-08-24
+title: intlayer Elysia Plugin Documentation | elysia-intlayer
+description: See how to use the intlayer plugin for elysia-intlayer package
+keywords:
+  - intlayer
+  - elysia
+  - plugin
+  - Intlayer
+  - Internationalisation
+  - Documentation
+slugs:
+  - doc
+  - packages
+  - elysia-intlayer
+  - intlayer
+history:
+  - version: 9.4.0
+    date: 2026-08-24
+    changes: "Init doc"
+author: aymericzip
+---
+
+# intlayer Elysia Plugin Documentation
+
+The `intlayer` plugin for Elysia detects the user's locale and injects an `intlayer` object into the route context. It also enables the use of global translation functions within the request context.
+
+## Usage
+
+```ts fileName="src/index.ts"
+import { Elysia } from "elysia";
+import { intlayer } from "elysia-intlayer";
+
+const app = new Elysia().use(intlayer()).get("/", ({ intlayer }) =>
+  intlayer!.t({
+    en: "Hello",
+    fr: "Bonjour",
+    es: "Hola",
+  })
+);
+```
+
+> The plugin registers its context through a **global** `derive`, which Elysia types as `Partial<{ intlayer: IntlayerContext }>`. The value is always present at runtime for routes registered after `.use(intlayer())`, so use the non-null assertion (`intlayer!.t`) — or optional chaining — to satisfy TypeScript in `strict` mode.
+
+The same helpers are available as standalone exports, so you can call them without destructuring the route context:
+
+```ts fileName="src/index.ts"
+import { Elysia } from "elysia";
+import { intlayer, t } from "elysia-intlayer";
+
+const app = new Elysia().use(intlayer()).get("/", () =>
+  t({
+    en: "Hello",
+    fr: "Bonjour",
+    es: "Hola",
+  })
+);
+```
+
+## Description
+
+The plugin performs the following tasks:
+
+1. **Locale Detection**: It reads the locale explicitly set by the client from storage (cookie, header), then falls back to the locale negotiated from the `Accept-Language` header.
+2. **Context Injection**: It adds an `intlayer` property to the Elysia route context (see the Route Context table below).
+3. **Context Management**: It uses `AsyncLocalStorage` to manage an asynchronous context, allowing the global Intlayer functions (`t`, `getIntlayer`, `getDictionary`) to access the request-specific locale without passing the context object around.
+4. **Dictionary Preparation**: It calls `prepareIntlayer` when the plugin is created, so the dictionaries are built when the app boots.
+
+### Route Context
+
+| Property          | Type                   | Description                                                                                    |
+| ----------------- | ---------------------- | ---------------------------------------------------------------------------------------------- |
+| `locale`          | `Locale`               | The locale to use for this request, `locale_storage` taking precedence over `locale_detected`. |
+| `locale_storage`  | `Locale` (optional)    | The locale explicitly requested by the client through a cookie or a header.                    |
+| `locale_detected` | `Locale`               | The locale negotiated from the request headers.                                                |
+| `defaultLocale`   | `Locale`               | The locale configured as fallback in `intlayer.config.ts`.                                     |
+| `t`               | `TranslateFunction`    | A translation function.                                                                        |
+| `getIntlayer`     | `typeof getIntlayer`   | A function to retrieve dictionaries by key.                                                    |
+| `getDictionary`   | `typeof getDictionary` | A function to process dictionary objects.                                                      |
+
+> Unlike the Node-based Intlayer plugins, `elysia-intlayer` relies on `AsyncLocalStorage` instead of `cls-hooked`, because `cls-hooked` depends on `async_hooks.createHook`, which Bun does not implement.
+
+The request context is released once the response is mapped, so the standalone helpers never resolve against an already terminated request. When called outside of a request handled by the plugin, they fall back to the configured default locale.
+
+## Locale Resolution Order
+
+By default, the plugin resolves the locale in this order:
+
+1. The `INTLAYER_LOCALE` cookie.
+2. The `x-intlayer-locale` header.
+3. The `Accept-Language` header negotiation.
+4. The configured `defaultLocale`.
+
+```bash
+# Negotiated from `Accept-Language`
+curl -H "Accept-Language: fr" http://localhost:3000/
+# Bonjour
+
+# The cookie takes precedence over `Accept-Language`
+curl -H "Accept-Language: fr" -H "Cookie: INTLAYER_LOCALE=es" http://localhost:3000/
+# Hola
+
+# The header takes precedence over `Accept-Language`
+curl -H "Accept-Language: fr" -H "x-intlayer-locale: es" http://localhost:3000/
+# Hola
+```
+
+## Configuration
+
+The plugin reads your `intlayer.config.ts` file. You can customise the cookie and header used for locale detection:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  routing: {
+    storage: [
+      { type: "header", name: "my-locale-header" },
+      { type: "cookie", name: "my-locale-cookie" },
+    ],
+  },
+};
+
+export default config;
+```
+
+> For more information on configuration, visit the [configuration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md).
+
+## Related Doc
+
+- [elysia-intlayer Package Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/elysia-intlayer/exports.md)
+- [Elysia i18n - Complete guide to translate your app](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/intlayer_with_elysia.md)