@intlayer/docs 8.0.0 → 8.0.1-canary.1

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

@@ -0,0 +1,50 @@
+---
+createdAt: 2026-01-30
+updatedAt: 2026-01-30
+title: adonis-intlayer Package Documentation
+description: AdonisJS middleware for Intlayer, providing translation functions and locale detection.
+keywords:
+  - adonis-intlayer
+  - adonisjs
+  - middleware
+  - internationalisation
+  - i18n
+slugs:
+  - doc
+  - packages
+  - adonis-intlayer
+  - exports
+history:
+  - version: 8.0.0
+    date: 2026-01-30
+    changes: Initial documentation
+---
+
+# adonis-intlayer Package
+
+The `adonis-intlayer` package provides a middleware for AdonisJS applications to handle internationalisation. It detects the user's locale and provides translation functions.
+
+## Installation
+
+```bash
+npm install adonis-intlayer
+```
+
+## Exports
+
+### Middleware
+
+The package provides an AdonisJS middleware to handle internationalisation.
+
+| Function             | Description                                                                                                                                                                                                                                                     | Related Doc                                                                                                       |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `IntlayerMiddleware` | AdonisJS middleware that detects the user's locale and populates the request context with Intlayer data. It also sets up a CLS (Async Local Storage) namespace for request lifecycle access, enabling the use of global functions like `t`, `getIntlayer`, etc. | [intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/packages/adonis-intlayer/intlayer.md) |
+
+### Functions
+
+| Function        | Description                                                                                                                                                                                            | Related Doc                                                                                               |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `t`             | Translation function that retrieves content for the current locale. Works within the request lifecycle managed by the `intlayer` middleware. Uses CLS (Async Local Storage) to access request context. | [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 specified locale. Optimised version of `getDictionary`. Uses CLS to access request context.           | -                                                                                                         |
+| `getDictionary` | Processes dictionary objects and returns content for the specified locale. Processes `t()` translations, enumerations, markdown, HTML, etc. Uses CLS to access request context.                        | -                                                                                                         |
+| `getLocale`     | Retrieves the current locale from the request context using CLS.                                                                                                                                       | -                                                                                                         |

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

@@ -0,0 +1,54 @@
+---
+createdAt: 2026-01-30
+updatedAt: 2026-01-30
+title: intlayer AdonisJS Middleware Documentation | adonis-intlayer
+description: See how to use the intlayer middleware for adonis-intlayer package
+keywords:
+  - intlayer
+  - adonisjs
+  - middleware
+  - Intlayer
+  - Internationalisation
+  - Documentation
+slugs:
+  - doc
+  - packages
+  - adonis-intlayer
+  - intlayer
+history:
+  - version: 8.0.0
+    date: 2026-01-30
+    changes: Initial documentation
+---
+
+# intlayer AdonisJS Middleware Documentation
+
+The `intlayer` middleware for AdonisJS detects the user's locale and provides translation functions through the request context. It also enables the use of global translation functions within the request flow.
+
+## Usage
+
+```ts fileName="start/kernel.ts"
+router.use([() => import("adonis-intlayer/middleware")]);
+```
+
+```ts fileName="start/routes.ts"
+import router from "@adonisjs/core/services/router";
+import { t } from "adonis-intlayer";
+
+router.get("/", async () => {
+  return t({
+    en: "Hello",
+    fr: "Bonjour",
+  });
+});
+```
+
+## Description
+
+The middleware performs the following tasks:
+
+1. **Locale Detection**: It analyses the request (headers, cookies, etc.) to determine the user's preferred locale.
+2. **Context Setup**: It populates the request context with locale information.
+3. **Async Local Storage**: It uses `cls-hooked` to manage an asynchronous context, allowing global Intlayer functions like `t`, `getIntlayer`, and `getDictionary` to access the request-specific locale without passing it manually.
+
+> Note: To use cookies for locale detection, ensure `@adonisjs/cookie` is configured and used in your application.

package/docs/en-GB/packages/adonis-intlayer/t.md

@@ -0,0 +1,149 @@
+---
+createdAt: 2026-01-30
+updatedAt: 2026-01-30
+title: t Function Documentation | adonis-intlayer
+description: See how to use the t function for adonis-intlayer package
+keywords:
+  - t
+  - translation
+  - Intlayer
+  - Internationalisation
+  - Documentation
+  - AdonisJS
+  - JavaScript
+slugs:
+  - doc
+  - packages
+  - adonis-intlayer
+  - t
+history:
+  - version: 8.0.0
+    date: 2026-01-30
+    changes: Initial documentation
+---
+
+# Documentation: `t` Function in `adonis-intlayer`
+
+The `t` function in the `adonis-intlayer` package is the core utility for providing localised responses in your AdonisJS application. It simplifies internationalisation (i18n) by dynamically selecting content based on the user's preferred language.
+
+---
+
+## Overview
+
+The `t` function is used to define and retrieve translations for a given set of languages. It automatically determines the appropriate language to return based on the client's request settings, such as the `Accept-Language` header. If the preferred language is unavailable, it gracefully falls back to the default locale specified in your configuration.
+
+---
+
+## Key Features
+
+- **Dynamic Localisation**: Automatically selects the most appropriate translation for the client.
+- **Fallback to Default Locale**: Falls back to a default locale if the client's preferred language isn't available, ensuring continuity in user experience.
+- **Asynchronous Context**: Works seamlessly within the AdonisJS request lifecycle using Async Local Storage.
+- **TypeScript Support**: Enforce type safety for your translations.
+
+---
+
+## Function Signature
+
+```typescript
+t(translations: Record<string, any>): any;
+```
+
+### Parameters
+
+- `translations`: An object where the keys are locale codes (e.g., `en`, `fr`, `es`) and the values are the corresponding translated content.
+
+### Returns
+
+- The content representing the client's preferred language.
+
+---
+
+## Loading the Middleware
+
+To ensure that the `t` function works correctly, you **must** register the `intlayer` middleware in your AdonisJS application.
+
+```typescript fileName="start/kernel.ts"
+router.use([() => import("adonis-intlayer/middleware")]);
+```
+
+---
+
+## Usage Examples
+
+### Basic Example
+
+```typescript fileName="start/routes.ts"
+import router from "@adonisjs/core/services/router";
+import { t } from "adonis-intlayer";
+
+router.get("/", async () => {
+  return t({
+    en: "Welcome!",
+    fr: "Bienvenue!",
+    es: "¡Bienvenido!",
+  });
+});
+```
+
+### Usage in Controllers
+
+```typescript fileName="app/controllers/example_controller.ts"
+import type { HttpContext } from "@adonisjs/core/http";
+import { t } from "adonis-intlayer";
+
+export default class ExampleController {
+  async index({ response }: HttpContext) {
+    return response.send(
+      t({
+        en: "Hello from controller",
+        fr: "Bonjour depuis le contrôleur",
+      })
+    );
+  }
+}
+```
+
+---
+
+## Advanced Topics
+
+### Fallback Mechanism
+
+If a preferred locale is unavailable, the `t` function will fallback to the default locale defined in your `intlayer.config.ts`.
+
+```typescript
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.RUSSIAN,
+      Locales.JAPANESE,
+      Locales.FRENCH,
+      Locales.KOREAN,
+      Locales.CHINESE,
+      Locales.SPANISH,
+      Locales.GERMAN,
+      Locales.ARABIC,
+      Locales.ITALIAN,
+      Locales.ENGLISH_UNITED_KINGDOM,
+      Locales.PORTUGUESE,
+      Locales.HINDI,
+      Locales.TURKISH,
+      Locales.POLISH,
+      Locales.INDONESIAN,
+      Locales.VIETNAMESE,
+      Locales.UKRAINIAN,
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+### TypeScript Integration
+
+The `t` function is type-safe when used with defined dictionaries. For more details, refer to the [TypeScript documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/configuration.md).

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

@@ -0,0 +1,59 @@
+---
+createdAt: 2026-01-29
+updatedAt: 2026-01-29
+title: hono-intlayer Package Documentation
+description: Hono middleware for Intlayer, providing translation functions and locale detection.
+keywords:
+  - hono-intlayer
+  - hono
+  - middleware
+  - internationalization
+  - i18n
+slugs:
+  - doc
+  - packages
+  - hono-intlayer
+  - exports
+history:
+  - version: 8.0.0
+    date: 2026-01-29
+    changes: Unified documentation for all exports
+---
+
+# hono-intlayer Package
+
+The `hono-intlayer` package provides a middleware for Hono applications to handle internationalization. It detects the user's locale and populates the context object.
+
+## Installation
+
+```bash
+npm install hono-intlayer
+```
+
+## Exports
+
+### Middleware
+
+Import:
+
+```tsx
+import { intlayer } from "hono-intlayer";
+```
+
+| Function   | Description                                                                                                                                                                                                                                                                        | Related Doc                                                                                                  |
+| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `intlayer` | Hono middleware that integrates Intlayer into your Hono application. Handles locale detection from storage (cookies, headers), populates the context with `t`, `getIntlayer`, and `getDictionary`, and sets up CLS namespace for programmatic access during the request lifecycle. | [intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/hono-intlayer/intlayer.md) |
+
+### Functions
+
+Import:
+
+```tsx
+import { t, getIntlayer, getDictionary } from "hono-intlayer";
+```
+
+| Function        | Description                                                                                                                                                                                                                             | Related Doc                                                                                            |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `t`             | Global translation function that retrieves content for the current locale in Hono. Utilizes CLS (Async Local Storage) and must be used within a request context managed by the `intlayer` middleware. Can also be accessed via context. | [translation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dictionary/translation.md) |
+| `getIntlayer`   | Retrieves a dictionary by its key from the generated declaration and returns its content for the specified locale. Optimized version of `getDictionary`. Uses CLS to access request context. Can also be accessed via context.          | -                                                                                                      |
+| `getDictionary` | Processes dictionary objects and returns content for the specified locale. Processes `t()` translations, enumerations, markdown, HTML, etc. Uses CLS to access request context. Can also be accessed via context.                       | -                                                                                                      |

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

@@ -0,0 +1,59 @@
+---
+createdAt: 2026-01-29
+updatedAt: 2026-01-29
+title: intlayer Hono Middleware Documentation | hono-intlayer
+description: See how to use the intlayer middleware for hono-intlayer package
+keywords:
+  - intlayer
+  - hono
+  - middleware
+  - Intlayer
+  - Internationalization
+  - Documentation
+slugs:
+  - doc
+  - packages
+  - hono-intlayer
+  - intlayer
+history:
+  - version: 8.0.0
+    date: 2026-01-29
+    changes: Init doc
+---
+
+# intlayer Hono Middleware Documentation
+
+The `intlayer` middleware for Hono detects the user's locale and populates the context object with Intlayer functions. It also enables the use of global translation functions within the request context.
+
+## Usage
+
+```ts
+import { Hono } from "hono";
+import { intlayer } from "hono-intlayer";
+
+const app = new Hono();
+
+app.use("*", intlayer());
+
+app.get("/", async (c) => {
+  const t = c.get("t");
+  const content = t({
+    en: "Hello",
+    fr: "Bonjour",
+  });
+
+  return c.text(content);
+});
+```
+
+## Description
+
+The middleware performs the following tasks:
+
+1. **Locale Detection**: It analyzes the request (headers, cookies, etc.) to determine the user's preferred locale.
+2. **Context Population**: It adds Intlayer data to the Hono context, accessible via `c.get()`. This includes:
+   - `locale`: The detected locale.
+   - `t`: A translation function.
+   - `getIntlayer`: A function to retrieve dictionaries.
+   - `getDictionary`: A function to process dictionary objects.
+3. **Context Management**: It uses `cls-hooked` to manage an asynchronous context, allowing global Intlayer functions (`t`, `getIntlayer`, `getDictionary`) to access the request-specific locale without passing the context object.

package/docs/en-GB/packages/hono-intlayer/t.md

@@ -0,0 +1,316 @@
+---
+createdAt: 2024-12-02
+updatedAt: 2025-06-29
+title: t Function Documentation | hono-intlayer
+description: See how to use the t function for hono-intlayer package
+keywords:
+  - t
+  - translation
+  - Intlayer
+  - Internationalization
+  - Documentation
+  - Hono
+  - JavaScript
+slugs:
+  - doc
+  - packages
+  - hono-intlayer
+  - t
+history:
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Init history
+---
+
+# Documentation: `t` Function in `hono-intlayer`
+
+The `t` function in the `hono-intlayer` package is the core utility for providing localized responses in your Hono application. It simplifies internationalization (i18n) by dynamically selecting content based on the user's preferred language.
+
+---
+
+## Overview
+
+The `t` function is used to define and retrieve translations for a given set of languages. It automatically determines the appropriate language to return based on the client's request settings, such as the `Accept-Language` header. If the preferred language is unavailable, it gracefully falls back to the default locale specified in your configuration.
+
+---
+
+## Key Features
+
+- **Dynamic Localization**: Automatically selects the most appropriate translation for the client.
+- **Fallback to Default Locale**: Falls back to a default locale if the client's preferred language isn't available, ensuring continuity in user experience.
+- **Lightweight and Fast**: Designed for high-performance applications, ensuring minimal overhead.
+- **Strict Mode Support**: Enforce strict adherence to declared locales for reliable behavior.
+
+---
+
+## Function Signature
+
+```typescript
+t(translations: Record<string, string>): string;
+```
+
+### Parameters
+
+- `translations`: An object where the keys are locale codes (e.g., `en`, `fr`, `es-MX`) and the values are the corresponding translated strings.
+
+### Returns
+
+- A string representing the content in the client's preferred language.
+
+---
+
+## Loading the Internationalization Request Handler
+
+To ensure that the internationalization functionality provided by `hono-intlayer` works correctly, you **must** load the internationalization middleware at the beginning of your Hono application. This enables the `t` function and ensures proper handling of locale detection and translation.
+
+Place the `app.use("*", intlayer())` middleware **before any routes** in your application to ensure that all routes benefit from internationalization:
+
+```typescript {6} fileName="src/index.ts" codeFormat="typescript"
+import { Hono } from "hono";
+import { intlayer } from "hono-intlayer";
+
+const app = new Hono();
+
+// Load internationalization request handler
+app.use("*", intlayer());
+
+// Define your routes after loading the middleware
+app.get("/", (c) => {
+  return c.text(
+    t({
+      en: "Hello, World!",
+      fr: "Bonjour le monde!",
+      es: "¡Hola, Mundo!",
+    })
+  );
+});
+```
+
+```javascript {6} fileName="src/index.mjs" codeFormat="esm"
+import { Hono } from "hono";
+import { intlayer } from "hono-intlayer";
+
+const app = new Hono();
+
+// Load internationalization request handler
+app.use("*", intlayer());
+
+// Define your routes after loading the middleware
+app.get("/", (c) => {
+  return c.text(
+    t({
+      en: "Hello, World!",
+      fr: "Bonjour le monde!",
+      es: "¡Hola, Mundo!",
+    })
+  );
+});
+```
+
+```javascript {6} fileName="src/index.cjs" codeFormat="commonjs"
+const { Hono } = require("hono");
+const { intlayer, t } = require("hono-intlayer");
+
+const app = new Hono();
+
+// Load internationalization request handler
+app.use("*", intlayer());
+
+// Define your routes after loading the middleware
+app.get("/", (c) => {
+  return c.text(
+    t({
+      en: "Hello, World!",
+      fr: "Bonjour le monde!",
+      es: "¡Hola, Mundo!",
+    })
+  );
+});
+```
+
+### Why This is Required
+
+- **Locale Detection**: The `intlayer` middleware processes incoming requests to detect the user's preferred locale based on headers, cookies, or other configured methods.
+- **Translation Context**: Sets up the necessary context for the `t` function to operate correctly, ensuring that translations are returned in the correct language.
+- **Error Prevention**: Without this middleware, using the `t` function will result in runtime errors because the necessary locale information won't be available.
+
+---
+
+## Usage Examples
+
+### Basic Example
+
+Serve localized content in different languages:
+
+```typescript fileName="src/index.ts" codeFormat="typescript"
+app.get("/", (c) => {
+  return c.text(
+    t({
+      en: "Welcome!",
+      fr: "Bienvenue!",
+      es: "¡Bienvenido!",
+    })
+  );
+});
+```
+
+```javascript fileName="src/index.mjs" codeFormat="esm"
+app.get("/", (c) => {
+  return c.text(
+    t({
+      en: "Welcome!",
+      fr: "Bienvenue!",
+      es: "¡Bienvenido!",
+    })
+  );
+});
+```
+
+```javascript fileName="src/index.cjs" codeFormat="commonjs"
+app.get("/", (c) => {
+  return c.text(
+    t({
+      en: "Welcome!",
+      fr: "Bienvenue!",
+      es: "¡Bienvenido!",
+    })
+  );
+});
+```
+
+**Client Requests:**
+
+- A client with `Accept-Language: fr` will receive `Bienvenue!`.
+- A client with `Accept-Language: es` will receive `¡Bienvenido!`.
+- A client with `Accept-Language: de` will receive `Welcome!` (default locale).
+
+### Handling Errors
+
+Provide error messages in multiple languages:
+
+```typescript fileName="src/index.ts" codeFormat="typescript"
+app.get("/error", (c) => {
+  return c.text(
+    t({
+      en: "An unexpected error occurred.",
+      fr: "Une erreur inattendue s'est produite.",
+      es: "Ocurrió un error inesperado.",
+    }),
+    500
+  );
+});
+```
+
+```javascript fileName="src/index.mjs" codeFormat="esm"
+app.get("/error", (c) => {
+  return c.text(
+    t({
+      en: "An unexpected error occurred.",
+      fr: "Une erreur inattendue s'est produite.",
+      es: "Ocurrió un error inesperado.",
+    }),
+    500
+  );
+});
+```
+
+```javascript fileName="src/index.cjs" codeFormat="commonjs"
+app.get("/error", (c) => {
+  return c.text(
+    t({
+      en: "An unexpected error occurred.",
+      fr: "Une erreur inattendue s'est produite.",
+      es: "Ocurrió un error inesperado.",
+    }),
+    500
+  );
+});
+```
+
+---
+
+### Using Locale Variants
+
+Specify translations for locale-specific variants:
+
+```typescript fileName="src/index.ts" codeFormat="typescript"
+app.get("/greet", (c) => {
+  return c.text(
+    t({
+      en: "Hello!",
+      "en-GB": "Hello, mate!",
+      fr: "Bonjour!",
+      "es-MX": "¡Hola, amigo!",
+      "es-ES": "¡Hola!",
+    })
+  );
+});
+```
+
+---
+
+## Advanced Topics
+
+### Fallback Mechanism
+
+If a preferred locale is unavailable, the `t` function will fallback to the default locale defined in the configuration:
+
+```typescript {5-6} fileName="intlayer.config.ts" codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+} satisfies IntlayerConfig;
+
+export default config;
+```
+
+---
+
+### Strict Mode Enforcement
+
+Configure the `t` function to enforce strict adherence to declared locales:
+
+| Mode        | Behavior                                                                                    |
+| ----------- | ------------------------------------------------------------------------------------------- |
+| `strict`    | All declared locales must have translations provided. Missing locales will throw errors.    |
+| `inclusive` | Declared locales must have translations. Missing locales trigger warnings but are accepted. |
+| `loose`     | Any existing locale is accepted, even if not declared.                                      |
+
+---
+
+### TypeScript Integration
+
+The `t` function is type-safe when used with TypeScript. Define a type-safe translations object:
+
+```typescript fileName="src/index.ts" codeFormat="typescript"
+import { type LanguageContent } from "hono-intlayer";
+
+const translations: LanguageContent<string> = {
+  en: "Good morning!",
+  fr: "Bonjour!",
+  es: "¡Buenos días!",
+};
+
+app.get("/morning", (c) => {
+  return c.text(t(translations));
+});
+```
+
+---
+
+### Common Errors and Troubleshooting
+
+| Issue                      | Cause                                   | Solution                                                  |
+| -------------------------- | --------------------------------------- | --------------------------------------------------------- |
+| `t` function not working   | Middleware not loaded                   | Ensure `app.use("*", intlayer())` is added before routes. |
+| Missing translations error | Strict mode enabled without all locales | Provide all required translations.                        |
+
+---
+
+## Conclusion
+
+The `t` function is a powerful tool for backend internationalization. By using it effectively, you can create a more inclusive and user-friendly application for a global audience. For advanced usage and detailed configuration options, refer to the [documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md).