@intlayer/docs 9.5.4-canary.0 → 9.5.5

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

@@ -0,0 +1,176 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: remix-intlayer Package Documentation
+description: Remix 3 integration for Intlayer, providing middleware, context, hooks, and formatters for locale-based routing and content management.
+keywords:
+  - remix-intlayer
+  - remix
+  - remix-3
+  - internationalisation
+  - i18n
+slugs:
+  - doc
+  - packages
+  - remix-intlayer
+  - exports
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Unified documentation for all exports"
+author: aymericzip
+---
+
+# remix-intlayer Package
+
+The `remix-intlayer` package provides the necessary tools to integrate Intlayer into Remix 3 applications. Built entirely on web standards (`Request`, `Response`, `Headers`, and `URL`), it offers a router middleware for locale-based routing and internal rewrites, context storage, hooks, and formatting utilities for seamless multilingual content management.
+
+## Installation
+
+```bash
+npm install remix-intlayer
+```
+
+## Exports
+
+### Middleware
+
+Import:
+
+```tsx
+import { intlayer } from "remix-intlayer";
+```
+
+| Function   | Description                                                                                                                                                                                            | Related Doc                                                                                                                |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| `intlayer` | Remix 3 router middleware that handles locale-based routing (redirects and internal rewrites), resolves the request locale, persists it in cookies/headers, and establishes the request context scope. | [intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/remix-intlayer/intlayerMiddleware.md) |
+
+### Context
+
+Import:
+
+```tsx
+import { Intlayer, INTLAYER_CONTEXT_PROPERTY } from "remix-intlayer";
+```
+
+| Export                      | Type         | Description                                                                                                                                        | Related Doc                                                                                                      |
+| --------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `Intlayer`                  | `ContextKey` | RequestContext key holding the `IntlayerState` (`locale`, `defaultLocale`, `availableLocales`) for the current request.                            | [Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/remix-intlayer/Intlayer.md) |
+| `INTLAYER_CONTEXT_PROPERTY` | `string`     | Property name (`'intlayer'`) installed directly on the request context, allowing access via `context.intlayer` as well as `context.get(Intlayer)`. | -                                                                                                                |
+
+### Hooks
+
+Import:
+
+```tsx
+import { useIntlayer, useDictionary, useLocale } from "remix-intlayer";
+```
+
+| Hook            | Description                                                                                                                                        | Related Doc                                                                                                                |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `useIntlayer`   | Picks one dictionary by its key and returns its content for the locale of the request being handled. Automatically reads from the request context. | [useIntlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/remix-intlayer/useIntlayer.md)     |
+| `useDictionary` | Transforms an imported dictionary object and returns its content for the current request locale. Supports selector overrides.                      | [useDictionary](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/remix-intlayer/useDictionary.md) |
+| `useLocale`     | Returns the resolved locale of the current request, along with the configured `defaultLocale` and `availableLocales`.                              | [useLocale](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/remix-intlayer/useLocale.md)         |
+
+### Utilities
+
+Import:
+
+```tsx
+import { createLocaleRouting, getIntlayerState } from "remix-intlayer";
+```
+
+| Function              | Description                                                                                                                          | Related Doc |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
+| `createLocaleRouting` | Pure function that computes locale routing decisions (`redirect`, `rewrite`, or `pass`) given a request, configuration, and options. | -           |
+| `getIntlayerState`    | Reads the current `IntlayerState` (`locale`, `defaultLocale`, `availableLocales`) from the `AsyncLocalStorage` request scope.        | -           |
+
+### Formatters (remix-intlayer/format)
+
+Import:
+
+```tsx
+import {
+  useIntl,
+  useDate,
+  useNumber,
+  useCurrency,
+  usePercentage,
+  useRelativeTime,
+  useList,
+  useUnit,
+  useCompact,
+} from "remix-intlayer/format";
+```
+
+| Hook              | Description                                                                                              |
+| ----------------- | -------------------------------------------------------------------------------------------------------- |
+| `useIntl`         | Returns an Intl instance bound to the request locale with caching and subscription capabilities.         |
+| `useDate`         | Returns a date formatting function pre-bound to the request locale (`Intl.DateTimeFormat`).              |
+| `useNumber`       | Returns a number formatting function pre-bound to the request locale (`Intl.NumberFormat`).              |
+| `useCurrency`     | Returns a currency formatting function pre-bound to the request locale.                                  |
+| `usePercentage`   | Returns a percentage formatting function pre-bound to the request locale.                                |
+| `useRelativeTime` | Returns a relative time formatting function pre-bound to the request locale (`Intl.RelativeTimeFormat`). |
+| `useList`         | Returns a list formatting function pre-bound to the request locale (`Intl.ListFormat`).                  |
+| `useUnit`         | Returns a unit formatting function pre-bound to the request locale.                                      |
+| `useCompact`      | Returns a compact number formatting function pre-bound to the request locale (e.g. `1.5K`).              |
+
+### HTML Utilities (remix-intlayer/html)
+
+Import:
+
+```tsx
+import { renderHTML, useHTML, useHTMLRenderer } from "remix-intlayer/html";
+```
+
+| Export            | Type       | Description                                                     |
+| ----------------- | ---------- | --------------------------------------------------------------- |
+| `renderHTML`      | `Function` | Standalone utility function to render HTML nodes outside of UI. |
+| `useHTML`         | `Hook`     | Hook to get the HTML provider context and configuration.        |
+| `useHTMLRenderer` | `Hook`     | Hook to obtain a pre-configured HTML renderer function.         |
+
+### Markdown Utilities (remix-intlayer/markdown)
+
+Import:
+
+```tsx
+import {
+  compileMarkdown,
+  renderMarkdown,
+  parseMarkdown,
+  useMarkdown,
+  useMarkdownRenderer,
+} from "remix-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 {
+  IntlayerState,
+  IntlayerMiddlewareOptions,
+  LocaleRoutingOptions,
+  LocaleRoutingAction,
+  LocaleRoutingRequest,
+  UseLocaleResult,
+} from "remix-intlayer";
+```
+
+| Type                        | Description                                                                                                     |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `IntlayerState`             | The state object holding `locale`, `defaultLocale`, and `availableLocales` stored in the Remix request context. |
+| `IntlayerMiddlewareOptions` | Configuration options passed to the `intlayer()` middleware.                                                    |
+| `LocaleRoutingOptions`      | Options customising locale prefixing, detection, and redirects.                                                 |
+| `LocaleRoutingAction`       | Discriminated union representing the routing decision: `redirect`, `rewrite`, or `pass`.                        |
+| `LocaleRoutingRequest`      | Minimal request representation required by `createLocaleRouting`.                                               |
+| `UseLocaleResult`           | Return type of `useLocale()`, containing `locale`, `defaultLocale`, and `availableLocales`.                     |

package/docs/en-GB/packages/remix-intlayer/intlayerMiddleware.md

@@ -0,0 +1,101 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: intlayer Middleware Documentation | remix-intlayer
+description: See how to use the intlayer middleware in Remix 3 applications for locale-based routing and request context management.
+keywords:
+  - intlayer
+  - intlayerMiddleware
+  - remix
+  - remix-3
+  - middleware
+  - routing
+  - Internationalisation
+  - Documentation
+slugs:
+  - doc
+  - packages
+  - remix-intlayer
+  - intlayerMiddleware
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Init doc"
+author: aymericzip
+---
+
+# intlayer Remix 3 Middleware Documentation
+
+The `intlayer` middleware for Remix 3 manages the internationalisation layer across your application. Built on web standards (`Request` and `Response`), it handles locale routing (redirects and internal rewrites), detects the request locale, persists it to cookies and headers, and establishes an `AsyncLocalStorage` scope so that downstream handlers and components can access translations without prop drilling.
+
+## Usage
+
+Register the `intlayer` middleware when initialising your Remix 3 router:
+
+```ts fileName="src/server.ts"
+import { createRouter } from "remix/router";
+import { intlayer, useIntlayer, useLocale } from "remix-intlayer";
+
+const router = createRouter({
+  middleware: [intlayer()],
+});
+
+// Serves `/`, `/fr`, `/es`, the locale is resolved from the request
+router.get("/", () => {
+  const { title } = useIntlayer("home");
+  return new Response(title);
+});
+```
+
+## Description
+
+The `intlayer` middleware performs the following tasks:
+
+1. **Dictionary Preparation**: Runs `prepareIntlayer` on startup to ensure all generated dictionaries are built and available.
+2. **Locale Routing**: Evaluates the request against the configured routing strategy (`prefix_always`, `prefix_as_needed`, `no_prefix`):
+   - **Redirects**: If a user visits `/about` and should be routed to a locale prefix (e.g. `/fr/about`), the middleware issues a redirect response with appropriate `location` and `Set-Cookie` headers.
+   - **Internal Rewrites**: When a user accesses `/fr/about`, the URL is rewritten internally so your route handler matches `/about`, whilst the resolved locale is captured as `fr`.
+   - **Localized URL Aliases**: Respects URL rewrite rules defined in `intlayer.config.ts` (e.g., rewriting `/fr/about` to `/fr/a-propos`).
+3. **Locale Resolution**: Detects the active locale based on URL prefix, persisted cookies, custom headers, or `Accept-Language` browser preferences.
+4. **Context Injection**:
+   - Attaches `IntlayerState` (`locale`, `defaultLocale`, `availableLocales`) to the Remix `RequestContext` under the `Intlayer` key and `context.intlayer`.
+   - Runs the rest of the request inside an `AsyncLocalStorage` scope (`requestStorage`), enabling `useIntlayer`, `useDictionary`, and `useLocale` to be invoked cleanly in handlers, views, and components.
+5. **Persistence**: Attaches outgoing locale headers and cookies to the final HTTP response to persist the user's preference.
+
+## Parameters
+
+The `intlayer` function accepts optional `IntlayerMiddlewareOptions`:
+
+```ts
+import { intlayer, type IntlayerMiddlewareOptions } from "remix-intlayer";
+
+const options: IntlayerMiddlewareOptions = {
+  // Custom routing configuration overrides
+};
+
+const middleware = intlayer(options);
+```
+
+## Accessing Context Directly
+
+In addition to using hooks, you can access the resolved `IntlayerState` directly from the Remix request context:
+
+```ts
+import { Intlayer } from "remix-intlayer";
+
+router.get("/api/locale", (context) => {
+  // Via context.get()
+  const state = context.get(Intlayer);
+
+  // Or via direct context.intlayer property
+  const { locale } = context.intlayer;
+
+  return Response.json({ locale });
+});
+```
+
+## Related Documentation
+
+- [`Intlayer` Context](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/remix-intlayer/Intlayer.md)
+- [`useIntlayer` Hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/remix-intlayer/useIntlayer.md)
+- [`useLocale` Hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/remix-intlayer/useLocale.md)

package/docs/en-GB/packages/remix-intlayer/useDictionary.md

@@ -0,0 +1,94 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: useDictionary Hook Documentation | remix-intlayer
+description: See how to use the useDictionary hook in Remix 3 applications to resolve dictionary objects for the current request locale.
+keywords:
+  - useDictionary
+  - dictionary
+  - remix
+  - remix-3
+  - Intlayer
+  - intlayer
+  - Internationalisation
+  - Documentation
+slugs:
+  - doc
+  - packages
+  - remix-intlayer
+  - useDictionary
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Init doc"
+author: aymericzip
+---
+
+# useDictionary Hook Documentation
+
+The `useDictionary` hook transforms an imported or inline dictionary object and returns its content resolved for the current request's locale in Remix 3 applications.
+
+Unlike `useIntlayer`, which resolves dictionaries by their string key from the global dictionary registry, `useDictionary` accepts a dictionary object directly.
+
+## Usage
+
+```ts fileName="src/views/home.ts"
+import { useDictionary } from "remix-intlayer";
+import homeContent from "./home.content";
+
+export const HomeView = () => {
+  const content = useDictionary(homeContent);
+
+  return `
+    <div>
+      <h1>${content.title}</h1>
+      <p>${content.subtitle}</p>
+    </div>
+  `;
+};
+```
+
+You can also pass inline dictionaries defined with `t()`:
+
+```ts
+import { useDictionary } from "remix-intlayer";
+import { t } from "intlayer";
+
+export const FooterView = () => {
+  const content = useDictionary({
+    key: "footer",
+    content: {
+      copyright: t({
+        "en-GB": "All rights reserved.",
+        en: "All rights reserved.",
+        fr: "Tous droits réservés.",
+      }),
+    },
+  });
+
+  return `<footer>${content.copyright}</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**: Reads the active request locale from the `AsyncLocalStorage` store created by the `intlayer()` middleware.
+2. **Content Resolution**: Evaluates translations (`t()`), enumerations, conditions, and nested structures according to the resolved locale.
+3. **Selector Processing**: Applies any item or variant selectors specified in the arguments.
+
+## Related Documentation
+
+- [`intlayer` Middleware](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/remix-intlayer/intlayerMiddleware.md)
+- [`useIntlayer` Hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/remix-intlayer/useIntlayer.md)
+- [`useLocale` Hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/remix-intlayer/useLocale.md)

package/docs/en-GB/packages/remix-intlayer/useIntlayer.md

@@ -0,0 +1,94 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: useIntlayer Hook Documentation | remix-intlayer
+description: See how to use the useIntlayer hook in Remix 3 applications to access localised content by key.
+keywords:
+  - useIntlayer
+  - dictionary
+  - remix
+  - remix-3
+  - Intlayer
+  - intlayer
+  - Internationalisation
+  - Documentation
+slugs:
+  - doc
+  - packages
+  - remix-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 localised content from an Intlayer dictionary by key in Remix 3 applications.
+
+It automatically reads the active locale from the current request context (via `AsyncLocalStorage`), so you do not need to pass the locale through route handlers, view templates, or components.
+
+## Usage
+
+### In Route Handlers
+
+```ts fileName="src/server.ts"
+import { createRouter } from "remix/router";
+import { intlayer, useIntlayer } from "remix-intlayer";
+
+const router = createRouter({
+  middleware: [intlayer()],
+});
+
+router.get("/api/welcome", () => {
+  const content = useIntlayer("home");
+
+  return Response.json({
+    title: content.title,
+    subtitle: content.subtitle,
+  });
+});
+```
+
+### In View Templates / Components
+
+```tsx fileName="src/views/home.ts"
+import { useIntlayer } from "remix-intlayer";
+
+export const HomeView = () => {
+  const content = useIntlayer("home");
+
+  return `
+    <main>
+      <h1>${content.title}</h1>
+      <p>${content.subtitle}</p>
+    </main>
+  `;
+};
+```
+
+## 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.
+
+## Description
+
+The hook performs the following tasks:
+
+1. **Context Locale Retrieval**: Detects the current locale from the request-bound `AsyncLocalStorage` scope established by the `intlayer()` middleware.
+2. **Dictionary Retrieval**: Retrieves the pre-compiled dictionary corresponding to the provided key.
+3. **Translation Processing**: Resolves translations, enumerations, markdown, and conditional content for the resolved locale.
+4. **Fallback Handling**: If called outside of an active HTTP request context, it gracefully falls back to the configured `defaultLocale`.
+
+## Related Documentation
+
+- [`intlayer` Middleware](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/remix-intlayer/intlayerMiddleware.md)
+- [`useDictionary` Hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/remix-intlayer/useDictionary.md)
+- [`useLocale` Hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/remix-intlayer/useLocale.md)

package/docs/en-GB/packages/remix-intlayer/useLocale.md

@@ -0,0 +1,104 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: useLocale Hook Documentation | remix-intlayer
+description: See how to use the useLocale hook in Remix 3 applications to get the current request locale, default locale, and available locales.
+keywords:
+  - useLocale
+  - locale
+  - remix
+  - remix-3
+  - Intlayer
+  - intlayer
+  - Internationalisation
+  - Documentation
+slugs:
+  - doc
+  - packages
+  - remix-intlayer
+  - useLocale
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Init doc"
+author: aymericzip
+---
+
+# useLocale Hook Documentation
+
+The `useLocale` hook from `remix-intlayer` provides access to the locale of the HTTP request currently being processed, along with the project's configured default and available locales.
+
+## Usage
+
+In a Remix component (for example a language switcher):
+
+```tsx fileName="src/components/LocaleSwitcher.tsx"
+import { type FC } from "react";
+import { Link } from "@remix-run/react";
+import { useLocale } from "remix-intlayer";
+import { getLocalizedUrl, getPathWithoutLocale } from "intlayer";
+
+export const LocaleSwitcher: FC = () => {
+  const { locale, availableLocales } = useLocale();
+  const pathWithoutLocale = getPathWithoutLocale();
+
+  return (
+    <nav>
+      <ul>
+        {availableLocales.map((localeItem) => (
+          <li key={localeItem} className="p-1">
+            <Link
+              href={getLocalizedUrl(pathWithoutLocale, localeItem)}
+              aria-current={localeItem === locale ? "page" : undefined}
+            >
+              {localeItem.toUpperCase()}
+            </Link>
+          </li>
+        ))}
+      </ul>
+    </nav>
+  );
+};
+```
+
+In a route handler:
+
+```ts fileName="src/server.ts"
+import { createRouter } from "remix/router";
+import { intlayer, useLocale } from "remix-intlayer";
+
+const router = createRouter({
+  middleware: [intlayer()],
+});
+
+router.get("/api/locale-info", () => {
+  const { locale, defaultLocale, availableLocales } = useLocale();
+
+  return Response.json({
+    locale,
+    defaultLocale,
+    availableLocales,
+  });
+});
+```
+
+## Return Values
+
+The hook returns an object of type `UseLocaleResult`:
+
+| Property           | Type                | Description                                                        |
+| ------------------ | ------------------- | ------------------------------------------------------------------ |
+| `locale`           | `DeclaredLocales`   | The locale resolved for the current request.                       |
+| `defaultLocale`    | `DeclaredLocales`   | The default fallback locale configured in `intlayer.config.ts`.    |
+| `availableLocales` | `DeclaredLocales[]` | Array of all available locales configured in `intlayer.config.ts`. |
+
+## Description
+
+1. **Request-Scoped Resolution**: In an active request handled by the `intlayer()` middleware, `useLocale` reads the resolved locale from the request storage.
+2. **Graceful Fallback**: If called outside of a request context, it defaults to the configured `defaultLocale`.
+
+## Related Documentation
+
+- [`intlayer` Middleware](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/remix-intlayer/intlayerMiddleware.md)
+- [`useIntlayer` Hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/remix-intlayer/useIntlayer.md)
+- [`useDictionary` Hook](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/remix-intlayer/useDictionary.md)

package/docs/en-GB/readme.md

@@ -199,7 +199,8 @@ Explore our comprehensive documentation to get started with Intlayer and learn h
   <li><a href="https://intlayer.org/doc/environment/create-react-app" rel=''>React CRA</a></li>
   <li><a href="https://intlayer.org/doc/environment/vite-and-react" rel=''>Vite + React</a></li>
   <li><a href="https://intlayer.org/doc/environment/vite-and-react" rel=''>Vite + React using Compiler</a></li>
-  <li><a href="https://intlayer.org/doc/environment/vite-and-react/compiler" rel=''>React-router-v7</a></li>
+  <li><a href="https://intlayer.org/doc/environment/vite-and-react/react-router-v7" rel=''>React-router-v7</a></li>
+  <li><a href="https://intlayer.org/doc/environment/remix-3" rel=''>Remix 3</a></li>
   <li><a href="https://intlayer.org/doc/environment/tanstack-start" rel=''>Tanstack start</a>
     <ul>
       <li><a href="https://intlayer.org/doc/environment/tanstack-start/solid" rel=''>Solid</a></li>