@intlayer/docs 5.5.8

package/en/packages/express-intlayer/t.md

@@ -0,0 +1,432 @@
+# Documentation: `t` Function in `express-intlayer`
+
+The `t` function in the `express-intlayer` package is the core utility for providing localized responses in your Express 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 `express-intlayer` works correctly, you **must** load the internationalization middleware at the beginning of your Express 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 {7} fileName="src/index.ts" codeFormat="typescript"
+import express, { type Express } from "express";
+import { intlayer } from "express-intlayer";
+
+const app: Express = express();
+
+// Load internationalization request handler
+app.use(intlayer());
+
+// Define your routes after loading the middleware
+app.get("/", (_req, res) => {
+  res.send(
+    t({
+      en: "Hello, World!",
+      fr: "Bonjour le monde!",
+      es: "¡Hola, Mundo!",
+    })
+  );
+});
+```
+
+```javascript {7} fileName="src/index.mjs" codeFormat="esm"
+import express from "express";
+import { intlayer } from "express-intlayer";
+
+const app = express();
+
+// Load internationalization request handler
+app.use(intlayer());
+
+// Define your routes after loading the middleware
+app.get("/", (_req, res) => {
+  res.send(
+    t({
+      en: "Hello, World!",
+      fr: "Bonjour le monde!",
+      es: "¡Hola, Mundo!",
+    })
+  );
+});
+```
+
+```javascript {7} fileName="src/index.cjs" codeFormat="commonjs"
+const express = require("express");
+const { intlayer } = require("express-intlayer");
+
+const app = express();
+
+// Load internationalization request handler
+app.use(intlayer());
+
+// Define your routes after loading the middleware
+app.get("/", (_req, res) => {
+  res.send(
+    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("/", (_req, res) => {
+  res.send(
+    t({
+      en: "Welcome!",
+      fr: "Bienvenue!",
+      es: "¡Bienvenido!",
+    })
+  );
+});
+```
+
+```javascript fileName="src/index.mjs" codeFormat="esm"
+app.get("/", (_req, res) => {
+  res.send(
+    t({
+      en: "Welcome!",
+      fr: "Bienvenue!",
+      es: "¡Bienvenido!",
+    })
+  );
+});
+```
+
+```javascript fileName="src/index.cjs" codeFormat="commonjs"
+app.get("/", (_req, res) => {
+  res.send(
+    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", (_req, res) => {
+  res.status(500).send(
+    t({
+      en: "An unexpected error occurred.",
+      fr: "Une erreur inattendue s'est produite.",
+      es: "Ocurrió un error inesperado.",
+    })
+  );
+});
+```
+
+```javascript fileName="src/index.mjs" codeFormat="esm"
+app.get("/error", (_req, res) => {
+  res.status(500).send(
+    t({
+      en: "An unexpected error occurred.",
+      fr: "Une erreur inattendue s'est produite.",
+      es: "Ocurrió un error inesperado.",
+    })
+  );
+});
+```
+
+```javascript fileName="src/index.cjs" codeFormat="commonjs"
+app.get("/error", (_req, res) => {
+  res.status(500).send(
+    t({
+      en: "An unexpected error occurred.",
+      fr: "Une erreur inattendue s'est produite.",
+      es: "Ocurrió un error inesperado.",
+    })
+  );
+});
+```
+
+---
+
+### Using Locale Variants
+
+Specify translations for locale-specific variants:
+
+```typescript fileName="src/index.ts" codeFormat="typescript"
+app.get("/greet", (_req, res) => {
+  res.send(
+    t({
+      en: "Hello!",
+      "en-GB": "Hello, mate!",
+      fr: "Bonjour!",
+      "es-MX": "¡Hola, amigo!",
+      "es-ES": "¡Hola!",
+    })
+  );
+});
+```
+
+```javascript fileName="src/index.cjs" codeFormat="commonjs"
+app.get("/greet", (_req, res) => {
+  res.send(
+    t({
+      en: "Hello!",
+      "en-GB": "Hello, mate!",
+      fr: "Bonjour!",
+      "es-MX": "¡Hola, amigo!",
+      "es-ES": "¡Hola!",
+    })
+  );
+});
+```
+
+```javascript fileName="src/index.mjs" codeFormat="esm"
+app.get("/greet", (_req, res) => {
+  res.send(
+    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;
+```
+
+```javascript {5-6} fileName="intlayer.config.mjs" codeFormat="esm"
+import { Locales } from "intlayer";
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+```javascript {5-6} fileName="intlayer.config.cjs" codeFormat="commonjs"
+const { Locales } = require("intlayer");
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+module.exports = config;
+```
+
+For example:
+
+- If `defaultLocale` is `Locales.CHINESE` and a client requests `Locales.DUTCH`, the returned translation will default to the `Locales.CHINESE` value.
+- If `defaultLocale` is not defined, the `t` function will fallback to the `Locales.ENGLISH` value.
+
+---
+
+### 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.                                      |
+
+Configuration Example:
+
+```typescript {7} fileName="intlayer.config.ts" codeFormat="typescript"
+import { type IntlayerConfig } from "intlayer";
+
+const config = {
+  // ... Your existing configuration
+  internationalization: {
+    // ... Your existing internationalization configuration
+    strictMode: "strict", // Enforce strict mode
+  },
+} satisfies IntlayerConfig;
+
+export default config;
+```
+
+```javascript {7} fileName="intlayer.config.mjs" codeFormat="esm"
+import { type IntlayerConfig } from "intlayer";
+
+const config = {
+  // ... Your existing configuration
+  internationalization: {
+    // ... Your existing internationalization configuration
+    strictMode: "strict", // Enforce strict mode
+  },
+};
+
+export default config;
+```
+
+```javascript {7} fileName="intlayer.config.cjs" codeFormat="commonjs"
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  // ... Your existing configuration
+  internationalization: {
+    // ... Your existing internationalization configuration
+    strictMode: "strict", // Enforce strict mode
+  },
+};
+
+module.exports = config;
+```
+
+---
+
+### 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 "express-intlayer";
+
+const translations: LanguageContent<string> = {
+  en: "Good morning!",
+  fr: "Bonjour!",
+  es: "¡Buenos días!",
+};
+
+app.get("/morning", (_req, res) => {
+  res.send(t(translations));
+});
+```
+
+```javascript fileName="src/index.mjs" codeFormat="esm"
+import { type LanguageContent } from "express-intlayer";
+
+/** @type {import('express-intlayer').LanguageContent<string>} */
+const translations = {
+  en: "Good morning!",
+  fr: "Bonjour!",
+  es: "¡Buenos días!",
+};
+
+app.get("/morning", (_req, res) => {
+  res.send(t(translations));
+});
+```
+
+```javascript fileName="src/index.cjs" codeFormat="commonjs"
+const { type LanguageContent } = require("express-intlayer");
+
+/** @type {import('express-intlayer').LanguageContent<string>} */
+const translations = {
+  en: "Good morning!",
+  fr: "Bonjour!",
+  es: "¡Buenos días!",
+};
+
+app.get("/morning", (_req, res) => {
+  res.send(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.                   |
+
+---
+
+## Tips for Effective Usage
+
+1. **Centralize Translations**: Use a centralized module or JSON files for managing translations to improve maintainability.
+2. **Validate Translations**: Ensure every language variant has a corresponding translation to prevent falling back unnecessarily.
+3. **Combine with Frontend i18n**: Synchronize with frontend internationalization for a seamless user experience across the app.
+4. **Benchmark Performance**: Test your app's response times when adding translations to ensure minimal impact.
+
+---
+
+## 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/en/configuration.md).

package/en/packages/intlayer/getConfiguration.md

@@ -0,0 +1,120 @@
+# Documentation: `getConfiguration` Function in `intlayer`
+
+## Description
+
+The `getConfiguration` function retrieves the entire configuration for the `intlayer` application by extracting environment variables. This function provides the flexibility to use the same configuration on both the client and server sides, ensuring consistency across the application.
+
+---
+
+## Parameters
+
+The function does not take any parameters. Instead, it uses environment variables for configuration.
+
+### Returns
+
+- **Type**: `IntlayerConfig`
+- **Description**: An object containing the complete configuration for `intlayer`. The configuration includes the following sections:
+
+  - `internationalization`: Settings related to locales and strict mode.
+  - `middleware`: Settings related to URL and cookie management.
+  - `content`: Settings related to content files, directories, and patterns.
+  - `editor`: Editor-specific configurations.
+
+See [Intlayer configuration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en/configuration.md) for more details.
+
+---
+
+## Example Usage
+
+### Retrieving the Full Configuration
+
+```typescript codeFormat="typescript"
+import { getConfiguration } from "intlayer";
+
+const config = getConfiguration();
+console.log(config);
+// Output:
+// {
+//   internationalization: { ... },
+//   middleware: { ... },
+//   content: { ... },
+//   editor: { ... }
+// }
+```
+
+```javascript codeFormat="esm"
+import { getConfiguration } from "intlayer";
+
+const config = getConfiguration();
+console.log(config);
+// Output:
+// {
+//   internationalization: { ... },
+//   middleware: { ... },
+//   content: { ... },
+//   editor: { ... }
+// }
+```
+
+```javascript codeFormat="commonjs"
+const { getConfiguration } = require("intlayer");
+
+const config = getConfiguration();
+console.log(config);
+// Output:
+// {
+//   internationalization: { ... },
+//   middleware: { ... },
+//   content: { ... },
+//   editor: { ... }
+// }
+```
+
+### Extracting `availableLocales` and `defaultLocale`
+
+The `internationalization` section of the configuration provides locale-related settings such as `locales` (available locales) and `defaultLocale` (fallback language).
+
+```typescript codeFormat="typescript"
+import { getConfiguration } from "intlayer";
+
+const { internationalization, middleware } = getConfiguration();
+const { locales: availableLocales, defaultLocale } = internationalization;
+const { cookieName } = middleware;
+
+console.log(availableLocales); // Output example: ["en", "fr", "es"]
+console.log(defaultLocale); // Output example: "en"
+console.log(cookieName); // Output: "INTLAYER_LOCALE"
+```
+
+```javascript codeFormat="esm"
+import { getConfiguration } from "intlayer";
+
+const { internationalization, middleware } = getConfiguration();
+const { locales: availableLocales, defaultLocale } = internationalization;
+const { cookieName } = middleware;
+
+console.log(availableLocales); // Output example: ["en", "fr", "es"]
+console.log(defaultLocale); // Output example: "en"
+console.log(cookieName); // Output: "INTLAYER_LOCALE"
+```
+
+```javascript codeFormat="commonjs"
+const { getConfiguration } = require("intlayer");
+
+const { internationalization, middleware } = getConfiguration();
+const { locales: availableLocales, defaultLocale } = internationalization;
+const { cookieName } = middleware;
+
+console.log(availableLocales); // Output example: ["en", "fr", "es"]
+console.log(defaultLocale); // Output example: "en"
+console.log(cookieName); // Output: "INTLAYER_LOCALE"
+```
+
+## Notes
+
+- Ensure that all required environment variables are correctly set before calling this function. Missing variables will cause errors during initialization.
+- This function can be used on both client and server sides, making it a versatile tool for managing configurations in a unified manner.
+
+## Usage in Applications
+
+The `getConfiguration` function is a cornerstone utility for initializing and managing the configuration of an `intlayer` application. By providing access to settings like locales, middleware, and content directories, it ensures consistency and scalability across multilingual and content-driven applications.

package/en/packages/intlayer/getEnumeration.md

@@ -0,0 +1,138 @@
+# Documentation: `getEnumeration` Function in `intlayer`
+
+## Description
+
+The `getEnumeration` function retrieves content corresponding to a specific quantity based on predefined conditions in an enumeration object. The conditions are defined as keys, and their priority is determined by their order in the object.
+
+## Parameters
+
+- `enumerationContent: QuantityContent<Content>`
+
+  - **Description**: An object where keys represent conditions (e.g., `<=`, `<`, `>=`, `=`) and values represent the corresponding content. The order of keys defines their matching priority.
+  - **Type**: `QuantityContent<Content>`
+    - `Content` can be any type.
+
+- `quantity: number`
+
+  - **Description**: The numeric value used to match against the conditions in `enumerationContent`.
+  - **Type**: `number`
+
+## Returns
+
+- **Type**: `Content`
+- **Description**: The content corresponding to the first matching condition in the `enumerationContent`. If no match is found, it defaults to handling based on the implementation (e.g., error or fallback content).
+
+## Example Usage
+
+### Basic Usage
+
+```typescript codeFormat="typescript"
+import { getEnumeration } from "intlayer";
+
+const content = getEnumeration(
+  {
+    "<=-2.3": "You have less than -2.3",
+    "<1": "You have less than one",
+    "2": "You have two",
+    ">=3": "You have three or more",
+  },
+  2
+);
+
+console.log(content); // Output: "You have two"
+```
+
+```javascript codeFormat="esm"
+import { getEnumeration } from "intlayer";
+
+const content = getEnumeration(
+  {
+    "<1": "You have less than one",
+    "2": "You have two",
+    ">=3": "You have three or more",
+  },
+  2
+);
+
+console.log(content); // Output: "You have two"
+```
+
+```javascript codeFormat="commonjs"
+const { getEnumeration } = require("intlayer");
+
+const content = getEnumeration(
+  {
+    "<1": "You have less than one",
+    "2": "You have two",
+    ">=3": "You have three or more",
+  },
+  2
+);
+
+console.log(content); // Output: "You have two"
+```
+
+### Priority of Conditions
+
+```typescript codeFormat="typescript"
+import { getEnumeration } from "intlayer";
+
+const content = getEnumeration(
+  {
+    "<4": "You have less than four",
+    "2": "You have two",
+  },
+  2
+);
+
+console.log(content); // Output: "You have less than four"
+```
+
+```javascript codeFormat="esm"
+import { getEnumeration } from "intlayer";
+
+const content = getEnumeration(
+  {
+    "<4": "You have less than four",
+    "2": "You have two",
+  },
+  2
+);
+
+console.log(content); // Output: "You have less than four"
+```
+
+```javascript codeFormat="commonjs"
+const { getEnumeration } = require("intlayer");
+
+const content = getEnumeration(
+  {
+    "<4": "You have less than four",
+    "2": "You have two",
+  },
+  2
+);
+
+console.log(content); // Output: "You have less than four"
+```
+
+## Edge Cases
+
+- **No Matching Condition:**
+
+  - If no condition matches the provided quantity, the function will either return `undefined` or handle the default/fallback scenario explicitly.
+
+- **Ambiguous Conditions:**
+
+  - If conditions overlap, the first matching condition (based on object order) takes precedence.
+
+- **Invalid Keys:**
+
+  - The function assumes that all keys in `enumerationContent` are valid and parsable as conditions. Invalid or improperly formatted keys may lead to unexpected behavior.
+
+- **TypeScript Enforcement:**
+  - The function ensures that the `Content` type is consistent across all keys, allowing for type safety in the retrieved content.
+
+## Notes
+
+- The `findMatchingCondition` utility is used to determine the appropriate condition based on the given quantity.