@intlayer/docs 8.0.0 → 8.0.1-canary.0

package/docs/en/introduction.md

@@ -204,6 +204,7 @@ We’ve built Intlayer with flexibility in mind, offering seamless integration a
 - **[Intlayer with SvelteKit](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_svelte_kit.md)**
 - **[Intlayer with Express](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_express.md)**
 - **[Intlayer with NestJS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_nestjs.md)**
+- **[Intlayer with Hono](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_hono.md)**
 - **[Intlayer with Angular](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_angular.md)**
 
 Each integration guide includes best practices for using Intlayer’s features, like **server-side rendering**, **dynamic routing**, or **client-side rendering**, so you can maintain a fast, SEO-friendly, and highly scalable application.

package/docs/en/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
+  - internationalization
+  - 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 internationalization. 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 internationalization.
+
+| 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/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/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.           | -                                                                                                      |
+| `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/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
+  - Internationalization
+  - 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 analyzes 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/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
+  - Internationalization
+  - 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 localized responses in your AdonisJS 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.
+- **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/configuration.md).

package/docs/en/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/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.