@intlayer/docs 9.5.4 → 9.5.5

package/docs/en/packages/astro-intlayer/exports.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2026-01-21
-updatedAt: 2026-01-21
+updatedAt: 2026-09-19
 title: astro-intlayer Package Documentation
-description: Astro integration for Intlayer, providing setup for locale-based routing and dictionary management.
+description: Astro integration for Intlayer, providing setup for locale-based routing, middleware, hooks, client store, and dictionary management.
 keywords:
   - astro-intlayer
   - astro
@@ -14,6 +14,9 @@ slugs:
   - astro-intlayer
   - exports
 history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Add useIntlayer, useDictionary, useLocale hooks, middleware, and formatters documentation"
   - version: 8.0.0
     date: 2026-01-21
     changes: "Unified documentation for all exports"
@@ -22,7 +25,7 @@ author: aymericzip
 
 # astro-intlayer Package
 
-The `astro-intlayer` package provides the necessary tools to integrate Intlayer into Astro applications. It configures locale-based routing and dictionary management.
+The `astro-intlayer` package provides the necessary tools to integrate Intlayer into Astro applications. It configures locale-based routing, dictionary management, build-time page rewriting, request middleware, and hooks for accessing multilingual content across both server-rendered `.astro` components and client-side scripts.
 
 ## Installation
 
@@ -34,22 +37,171 @@ npm install astro-intlayer
 
 ### Integration
 
-The `astro-intlayer` package provides an Astro integration to set up Intlayer in your project.
+The `astro-intlayer` package provides an Astro integration that sets up Intlayer in your project.
 
 Import:
 
 ```tsx
-import "astro-intlayer";
+import { intlayer } from "astro-intlayer";
 ```
 
-or adding to `astro.config.mjs`:
+or default import in `astro.config.mjs`:
 
 ```ts
+import { defineConfig } from "astro/config";
+import intlayer from "astro-intlayer";
+
 export default defineConfig({
   integrations: [intlayer()],
 });
 ```
 
-| Function   | Description                                              |
-| ---------- | -------------------------------------------------------- |
-| `intlayer` | Astro integration that sets up Intlayer in your project. |
+| Function   | Description                                                                                                                                                                                                 | Related Doc                                                                                                   |
+| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `intlayer` | Astro integration that prepares dictionaries, configures Vite plugins (aliases, routing proxy, prune), automatically registers request middleware, and emits prerendered pages at localized rewritten URLs. | [intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/astro-intlayer/intlayer.md) |
+
+### Hooks (Server & Client)
+
+Import:
+
+```tsx
+import { useIntlayer, useDictionary, useLocale } from "astro-intlayer";
+```
+
+| Hook            | Description                                                                                                                                                                                        | Related Doc                                                                                                             |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `useIntlayer`   | Picks one dictionary by its key and returns its localized content. In `.astro` frontmatter, it reads the request locale from `Astro.locals`. In client `<script>`, it reads from the client store. | [useIntlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/astro-intlayer/useIntlayer.md)     |
+| `useDictionary` | Transforms a dictionary object and returns content for the resolved locale. Works in frontmatter and client scripts.                                                                               | [useDictionary](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/astro-intlayer/useDictionary.md) |
+| `useLocale`     | Returns the current locale, default locale, available locales, and a function to update the locale.                                                                                                | [useLocale](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/astro-intlayer/useLocale.md)         |
+
+### Middleware (astro-intlayer/middleware)
+
+Import:
+
+```tsx
+import { onRequest } from "astro-intlayer/middleware";
+```
+
+| Export      | Type                | Description                                                                                                                                                       | Related Doc                                                                                                     |
+| ----------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `onRequest` | `MiddlewareHandler` | Astro middleware that detects the request locale and attaches `Astro.locals.intlayer`. Registered automatically by `intlayer()`, or imported manually to compose. | [onRequest](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/astro-intlayer/onRequest.md) |
+
+### Utilities
+
+Import:
+
+```tsx
+import { getIntlayerLocals } from "astro-intlayer";
+```
+
+| Function            | Description                                                                                                             | Related Doc |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------- |
+| `getIntlayerLocals` | Helper function to retrieve the current `IntlayerLocals` object from the request storage scope outside of Astro.locals. | -           |
+
+### Client Utilities (astro-intlayer/client)
+
+Import:
+
+```tsx
+import {
+  useIntlayer,
+  useDictionary,
+  useDictionaryDynamic,
+  useLocale,
+  useLocaleStorage,
+  useLocaleCookie,
+  getIntlayer,
+  getDictionary,
+  installIntlayer,
+  setLocaleInStorage,
+  setLocaleCookie,
+  localeInStorage,
+  localeCookie,
+} from "astro-intlayer/client";
+```
+
+When imported in the browser or inside client `<script>` tags, `astro-intlayer` automatically maps to `astro-intlayer/client` (powered by `vanilla-intlayer`), providing client-side dictionary getters, store subscribers, and locale persistence tools.
+
+### Formatters (astro-intlayer/format)
+
+Import:
+
+```tsx
+import {
+  useIntl,
+  useDate,
+  useNumber,
+  useCurrency,
+  usePercentage,
+  useRelativeTime,
+  useList,
+  useUnit,
+  useCompact,
+} from "astro-intlayer/format";
+```
+
+| Hook              | Description                                                                                                |
+| ----------------- | ---------------------------------------------------------------------------------------------------------- |
+| `useIntl`         | Returns an Intl instance bound to the request or client locale with caching and subscription capabilities. |
+| `useDate`         | Returns a date formatting function pre-bound to the current locale (`Intl.DateTimeFormat`).                |
+| `useNumber`       | Returns a number formatting function pre-bound to the current locale (`Intl.NumberFormat`).                |
+| `useCurrency`     | Returns a currency formatting function pre-bound to the current locale.                                    |
+| `usePercentage`   | Returns a percentage formatting function pre-bound to the current locale.                                  |
+| `useRelativeTime` | Returns a relative time formatting function pre-bound to the current locale (`Intl.RelativeTimeFormat`).   |
+| `useList`         | Returns a list formatting function pre-bound to the current locale (`Intl.ListFormat`).                    |
+| `useUnit`         | Returns a unit formatting function pre-bound to the current locale.                                        |
+| `useCompact`      | Returns a compact number formatting function pre-bound to the current locale (e.g. `1.5K`).                |
+
+### HTML Utilities (astro-intlayer/html)
+
+Import:
+
+```tsx
+import { renderHTML, useHTML, useHTMLRenderer } from "astro-intlayer/html";
+```
+
+| Export            | Type       | Description                                              |
+| ----------------- | ---------- | -------------------------------------------------------- |
+| `renderHTML`      | `Function` | Standalone utility function to render HTML nodes.        |
+| `useHTML`         | `Hook`     | Hook to get the HTML provider context and configuration. |
+| `useHTMLRenderer` | `Hook`     | Hook to obtain a pre-configured HTML renderer function.  |
+
+### Markdown Utilities (astro-intlayer/markdown)
+
+Import:
+
+```tsx
+import {
+  compileMarkdown,
+  renderMarkdown,
+  parseMarkdown,
+  useMarkdown,
+  useMarkdownRenderer,
+} from "astro-intlayer/markdown";
+```
+
+| Export                | Type       | Description                                                 |
+| --------------------- | ---------- | ----------------------------------------------------------- |
+| `compileMarkdown`     | `Function` | Compiles markdown strings into structured representation.   |
+| `renderMarkdown`      | `Function` | Renders markdown content into output nodes.                 |
+| `parseMarkdown`       | `Function` | Parses raw markdown content into an AST.                    |
+| `useMarkdown`         | `Hook`     | Hook to get the markdown provider context.                  |
+| `useMarkdownRenderer` | `Hook`     | Hook to obtain a pre-configured Markdown renderer function. |
+
+### Types
+
+Import:
+
+```tsx
+import type {
+  IntlayerLocals,
+  UseLocaleProps,
+  UseLocaleResult,
+} from "astro-intlayer";
+```
+
+| Type              | Description                                                                                                  |
+| ----------------- | ------------------------------------------------------------------------------------------------------------ |
+| `IntlayerLocals`  | The object attached to `Astro.locals.intlayer` containing `locale`, `defaultLocale`, and `availableLocales`. |
+| `UseLocaleProps`  | Optional configuration properties accepted by `useLocale()`.                                                 |
+| `UseLocaleResult` | The return type of `useLocale()`, providing locale properties and update methods.                            |

package/docs/en/packages/astro-intlayer/intlayer.md

@@ -0,0 +1,76 @@
+---
+createdAt: 2026-01-21
+updatedAt: 2026-09-19
+title: intlayer Integration Documentation | astro-intlayer
+description: See how to configure and use the intlayer Astro integration in astro.config.mjs.
+keywords:
+  - intlayer
+  - astro
+  - astro-intlayer
+  - integration
+  - i18n
+  - Internationalization
+  - Documentation
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - intlayer
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Update integration documentation with middleware and hooks details"
+  - version: 8.0.0
+    date: 2026-01-21
+    changes: "Init doc"
+author: aymericzip
+---
+
+# intlayer Astro Integration Documentation
+
+The `intlayer` integration for Astro configures your project for multilingual internationalization (i18n). It handles build-time dictionary preparation, Vite plugin injection, automatic request middleware registration, and emitting localized prerendered pages.
+
+## Usage
+
+Add `intlayer()` to your `astro.config.mjs`:
+
+```ts fileName="astro.config.mjs"
+import { defineConfig } from "astro/config";
+import { intlayer } from "astro-intlayer";
+
+export default defineConfig({
+  integrations: [intlayer()],
+});
+```
+
+Astro CLI's codemod (`astro add astro-intlayer`) also generates a default import which is supported:
+
+```ts
+import intlayer from "astro-intlayer";
+```
+
+## Description
+
+The integration hooks into Astro's build and runtime lifecycle:
+
+1. **Config Setup (`astro:config:setup`)**:
+   - **Dictionary Preparation**: Prepares Intlayer dictionaries and generated types before the build runs.
+   - **Vite Plugins**: Injects plugins for Vite aliases (enabling seamless dictionary imports), locale routing proxies, and build pruning.
+   - **Middleware Registration**: Automatically injects `astro-intlayer/middleware` into your project's middleware chain, populating `Astro.locals.intlayer` on every incoming request.
+2. **Build Done (`astro:build:done`)**:
+   - **Page Rewrites**: Inspects localized URL rewrite rules and emits prerendered HTML pages at their corresponding localized paths.
+
+## What is Provided Out of the Box
+
+Once configured, your Astro application can immediately use:
+
+- The `useIntlayer`, `useDictionary`, and `useLocale` hooks inside `.astro` component frontmatter.
+- The `Astro.locals.intlayer` object in Astro endpoints and pages.
+- Client-side imports in `<script>` blocks that mirror the same API with reactive updates.
+- Built-in formatters under `astro-intlayer/format` (`useDate`, `useNumber`, `useCurrency`, etc.).
+
+## Related Documentation
+
+- [`useIntlayer` Hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/astro-intlayer/useIntlayer.md)
+- [`useLocale` Hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/astro-intlayer/useLocale.md)
+- [`onRequest` Middleware](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/astro-intlayer/onRequest.md)

package/docs/en/packages/astro-intlayer/onRequest.md

@@ -0,0 +1,76 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: onRequest Middleware Documentation | astro-intlayer
+description: See how to use the onRequest middleware in Astro applications to resolve the request locale and populate Astro.locals.intlayer.
+keywords:
+  - onRequest
+  - middleware
+  - astro
+  - astro-intlayer
+  - Astro.locals
+  - Internationalization
+  - Documentation
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - onRequest
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Init doc"
+author: aymericzip
+---
+
+# onRequest Astro Middleware Documentation
+
+The `onRequest` middleware from `astro-intlayer/middleware` resolves the locale of each incoming HTTP request and populates `Astro.locals.intlayer`.
+
+When you register the `intlayer()` integration in `astro.config.mjs`, this middleware is injected automatically. You only need to import it directly if you are manually composing Astro middleware using `sequence(...)`.
+
+## Usage
+
+```ts fileName="src/middleware.ts"
+import { onRequest as intlayer } from "astro-intlayer/middleware";
+import { sequence } from "astro:middleware";
+
+export const onRequest = sequence(intlayer, async (context, next) => {
+  // Access the resolved locale in your custom middleware
+  const { locale } = context.locals.intlayer;
+  console.log(`Handling request for locale: ${locale}`);
+
+  return next();
+});
+```
+
+## Description
+
+The middleware performs the following:
+
+1. **Locale Detection**:
+   - **URL**: Analyzes the URL path prefix or `?locale=` search parameter (unless `routing.mode` is set to `no-prefix`).
+   - **Cookies / Headers**: Checks persisted locale cookies or custom header values.
+   - **Accept-Language**: Falls back to the browser's preferred language negotiation.
+   - For prerendered pages (`context.isPrerendered`), the locale is extracted strictly from the URL to prevent Astro build warnings.
+2. **Context Population**: Populates `Astro.locals.intlayer` with:
+   - `locale`: The resolved locale.
+   - `defaultLocale`: The default fallback locale.
+   - `availableLocales`: The array of configured locales.
+3. **AsyncLocalStorage Scope**: Wraps the downstream request processing inside an `AsyncLocalStorage` scope, allowing `useIntlayer()`, `useDictionary()`, and `useLocale()` to access request state without passing arguments.
+
+## `IntlayerLocals` Type
+
+```ts
+export type IntlayerLocals = {
+  locale: DeclaredLocales;
+  defaultLocale: DeclaredLocales;
+  availableLocales: DeclaredLocales[];
+};
+```
+
+## Related Documentation
+
+- [`intlayer` Integration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/astro-intlayer/intlayer.md)
+- [`useIntlayer` Hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/astro-intlayer/useIntlayer.md)
+- [`useLocale` Hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/astro-intlayer/useLocale.md)

package/docs/en/packages/astro-intlayer/useDictionary.md

@@ -0,0 +1,94 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: useDictionary Hook Documentation | astro-intlayer
+description: See how to use the useDictionary hook in Astro components and scripts to resolve dictionary objects.
+keywords:
+  - useDictionary
+  - dictionary
+  - astro
+  - astro-intlayer
+  - Intlayer
+  - intlayer
+  - Internationalization
+  - Documentation
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - useDictionary
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Init doc"
+author: aymericzip
+---
+
+# useDictionary Hook Documentation
+
+The `useDictionary` hook resolves an imported or inline dictionary object and returns its content for the current locale in Astro applications.
+
+Unlike `useIntlayer`, which retrieves dictionaries by key from the global dictionary registry, `useDictionary` works directly with a dictionary object.
+
+## Usage
+
+```astro fileName="src/pages/index.astro"
+---
+import { useDictionary } from "astro-intlayer";
+import homeContent from "../content/home.content";
+
+const content = useDictionary(homeContent);
+---
+
+<main>
+  <h1>{content.title}</h1>
+  <p>{content.description}</p>
+</main>
+```
+
+You can also pass inline dictionaries defined with `t()`:
+
+```astro fileName="src/components/Footer.astro"
+---
+import { useDictionary } from "astro-intlayer";
+import { t } from "intlayer";
+
+const footer = useDictionary({
+  key: "footer",
+  content: {
+    copyright: t({
+      en: "All rights reserved.",
+      fr: "Tous droits réservés.",
+      es: "Todos los derechos reservados.",
+    }),
+  },
+});
+---
+
+<footer>
+  <p>{footer.copyright}</p>
+</footer>
+```
+
+## Parameters
+
+```ts
+useDictionary(dictionary, localeOrSelector?)
+```
+
+1. **`dictionary`**: A dictionary object or qualified dictionary group.
+2. **`localeOrSelector`** (optional): A specific locale or selector object (`{ item }`, `{ variant }`, optionally with `locale`).
+
+## Description
+
+The hook performs the following tasks:
+
+1. **Locale Detection**: On the server, it obtains the locale from `Astro.locals.intlayer`. In the browser, it uses the client-side store locale.
+2. **Content Processing**: Resolves translations (`t()`), enumerations, conditions, and nested structures according to the resolved locale.
+3. **Selectors**: Applies any item or variant selectors provided in the arguments.
+
+## Related Documentation
+
+- [`intlayer` Integration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/astro-intlayer/intlayer.md)
+- [`useIntlayer` Hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/astro-intlayer/useIntlayer.md)
+- [`useLocale` Hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/astro-intlayer/useLocale.md)

package/docs/en/packages/astro-intlayer/useIntlayer.md

@@ -0,0 +1,98 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: useIntlayer Hook Documentation | astro-intlayer
+description: See how to use the useIntlayer hook in Astro components and client scripts to access localized content.
+keywords:
+  - useIntlayer
+  - dictionary
+  - astro
+  - astro-intlayer
+  - Intlayer
+  - intlayer
+  - Internationalization
+  - Documentation
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - useIntlayer
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Init doc"
+author: aymericzip
+---
+
+# useIntlayer Hook Documentation
+
+The `useIntlayer` hook allows you to retrieve localized dictionary content by key in Astro applications.
+
+It can be called in two distinct contexts using the same import path:
+
+1. **Server / Frontmatter**: Inside `.astro` files, it automatically resolves content using the request locale stored in `Astro.locals.intlayer`.
+2. **Browser / Client `<script>`**: Inside client scripts or UI framework components, it resolves to the client-side store implementation (`vanilla-intlayer`).
+
+## Usage
+
+### In Astro Component Frontmatter
+
+```astro fileName="src/pages/index.astro"
+---
+import { useIntlayer } from "astro-intlayer";
+
+const content = useIntlayer("home");
+---
+
+<main>
+  <h1>{content.title}</h1>
+  <p>{content.description}</p>
+</main>
+```
+
+### In Client `<script>` Blocks
+
+```astro fileName="src/components/InteractiveWidget.astro"
+---
+import { useIntlayer } from "astro-intlayer";
+
+const content = useIntlayer("home");
+---
+
+<button id="alert-btn">{content.buttonText}</button>
+
+<script>
+  import { useIntlayer } from "astro-intlayer";
+
+  const content = useIntlayer("home");
+
+  document.getElementById("alert-btn")?.addEventListener("click", () => {
+    alert(content.buttonText);
+  });
+</script>
+```
+
+## Parameters
+
+```ts
+useIntlayer(key, localeOrSelector?)
+```
+
+1. **`key`**: The unique key of the dictionary (as defined in your `.content.ts` declaration files).
+2. **`localeOrSelector`** (optional): A specific locale or selector object (`{ item }`, `{ variant }`, optionally with `locale`). When provided, it overrides the locale detected from the request context or client store.
+
+## Description
+
+The hook performs the following tasks:
+
+1. **Locale Resolution**:
+   - On the server, reads the active locale from `Astro.locals.intlayer` via an `AsyncLocalStorage` scope initialized by the `astro-intlayer/middleware`.
+   - In the browser, reads the active locale from the client storage/store.
+2. **Dictionary Retrieval**: Injects the dictionary content matching the specified key.
+3. **Translation Processing**: Resolves translations (`t()`), enumerations, conditions, and markdown into ready-to-render content.
+
+## Related Documentation
+
+- [`intlayer` Integration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/astro-intlayer/intlayer.md)
+- [`useDictionary` Hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/astro-intlayer/useDictionary.md)
+- [`useLocale` Hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/astro-intlayer/useLocale.md)

package/docs/en/packages/astro-intlayer/useLocale.md

@@ -0,0 +1,126 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: useLocale Hook Documentation | astro-intlayer
+description: See how to use the useLocale hook in Astro applications to access and manage the current locale.
+keywords:
+  - useLocale
+  - locale
+  - astro
+  - astro-intlayer
+  - Intlayer
+  - intlayer
+  - Internationalization
+  - Documentation
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - useLocale
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Init doc"
+author: aymericzip
+---
+
+# useLocale Hook Documentation
+
+The `useLocale` hook from `astro-intlayer` provides access to the current request locale, the configured default locale, and all available locales in Astro applications.
+
+It behaves consistently across server-rendered `.astro` frontmatter and client-side `<script>` blocks.
+
+## Usage
+
+### In Component Frontmatter (Server-Rendered)
+
+```astro fileName="src/layouts/Layout.astro"
+---
+import { useLocale } from "astro-intlayer";
+import { getLocalizedUrl, getPathWithoutLocale } from "intlayer";
+
+const { locale, defaultLocale, availableLocales } = useLocale();
+const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);
+---
+
+<!DOCTYPE html>
+<html lang={locale}>
+  <head>
+    <meta charset="utf-8" />
+    <title>Astro + Intlayer</title>
+  </head>
+  <body>
+    <header>
+      <span>Current: {locale}</span>
+      <span>Default: {defaultLocale}</span>
+      <nav>
+        <ul>
+          {availableLocales.map((localeItem) => (
+            <li key={localeItem} className="p-1">
+              <a
+                href={getLocalizedUrl(pathWithoutLocale, localeItem)}
+                aria-current={localeItem === locale ? "page" : undefined}
+              >
+                {localeItem.toUpperCase()}
+              </a>
+            </li>
+          ))}
+        </ul>
+      </nav>
+    </header>
+    <slot />
+  </body>
+</html>
+```
+
+### In Client `<script>` (Interactive)
+
+```astro fileName="src/components/LocaleSwitcher.astro"
+---
+import { useLocale } from "astro-intlayer";
+
+const { locale, availableLocales } = useLocale();
+---
+
+<select id="locale-select">
+  {availableLocales.map((loc) => (
+    <option value={loc} selected={loc === locale}>
+      {loc.toUpperCase()}
+    </option>
+  ))}
+</select>
+
+<script>
+  import { useLocale, setLocaleInStorage } from "astro-intlayer";
+
+  const { setLocale } = useLocale();
+
+  document.getElementById("locale-select")?.addEventListener("change", (e) => {
+    const target = e.target as HTMLSelectElement;
+    setLocale(target.value);
+  });
+</script>
+```
+
+## Return Values
+
+The hook returns an object of type `UseLocaleResult`:
+
+| Property           | Type                                   | Description                                                                          |
+| ------------------ | -------------------------------------- | ------------------------------------------------------------------------------------ |
+| `locale`           | `DeclaredLocales`                      | The active locale.                                                                   |
+| `defaultLocale`    | `DeclaredLocales`                      | The default fallback locale configured in `intlayer.config.ts`.                      |
+| `availableLocales` | `DeclaredLocales[]`                    | Array of all supported locales configured for the project.                           |
+| `setLocale`        | `(locale: LocalesValues) => void`      | Function to update the locale. (Interactive in client `<script>`, warns during SSR). |
+| `subscribe`        | `(callback: () => void) => () => void` | Subscribes to client-side locale changes.                                            |
+
+## Server vs Client Behavior
+
+- **During SSR / Server Rendering**: A request is rendered once with fixed parameters. Calling `setLocale()` during a server render has no effect and emits a warning; locale switching should be performed on the client or by navigating to the target locale URL.
+- **In Client Scripts**: `setLocale` updates the client store and updates persisted cookies or local storage according to your Intlayer configuration.
+
+## Related Documentation
+
+- [`intlayer` Integration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/astro-intlayer/intlayer.md)
+- [`useIntlayer` Hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/astro-intlayer/useIntlayer.md)
+- [`useDictionary` Hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/astro-intlayer/useDictionary.md)