@intlayer/docs 5.5.8

package/en-GB/packages/@intlayer/webpack/index.md

@@ -0,0 +1,35 @@
+# @intlayer/webpack: NPM Package to use the Intlayer Webpack Plugin into your application
+
+**Intlayer** is a suite of packages designed specifically for JavaScript developers. It is compatible with frameworks like React, React, and Express.js.
+
+The **`@intlayer/webpack`** package is used to provide a Webpack configuration to make working a Webpack based application with Intlayer. The package also provides a plugin to add into an existing Webpack application.
+
+## Usage
+
+```ts
+import { IntlayerPlugin } from "@intlayer/webpack";
+
+export default {
+  plugins: [
+    new IntlayerPlugin({
+      // Options
+    }),
+  ],
+};
+```
+
+## Installation
+
+Install the necessary package using your preferred package manager:
+
+```bash packageManager="npm"
+npm install @intlayer/webpack
+```
+
+```bash packageManager="pnpm"
+pnpm add @intlayer/webpack
+```
+
+```bash packageManager="yarn"
+yarn add @intlayer/webpack
+```

package/en-GB/packages/angular-intlayer/index.md

@@ -0,0 +1,3 @@
+this doc will be automatically generated translated from the english doc
+
+see /docs/en/packages/angular-intlayer/index.md

package/en-GB/packages/express-intlayer/index.md

@@ -0,0 +1,229 @@
+# express-intlayer: JavaScript Package to internationalise (i18n) an Express.js application
+
+**Intlayer** is a suite of packages designed specifically for JavaScript developers. It is compatible with frameworks like React, Next.js, and Express.js.
+
+**The `express-intlayer` package** allows you to internationalise your Express.js application. It provides a middleware to detect the user's preferred locale, and returns the appropriate dictionary for the user.
+
+## Why Internationalise Your Backend?
+
+Internationalising your backend is essential for serving a global audience effectively. It allows your application to deliver content and messages in the preferred language of each user. This capability enhances user experience and broadens your application's reach by making it more accessible and relevant to people from different linguistic backgrounds.
+
+### Practical Use Cases
+
+- **Displaying Backend Errors in User's Language**: When an error occurs, displaying messages in the user's native language improves understanding and reduces frustration. This is especially useful for dynamic error messages that might be shown in front-end components like toasts or modals.
+
+- **Retrieving Multilingual Content**: For applications pulling content from a database, internationalisation ensures that you can serve this content in multiple languages. This is crucial for platforms like e-commerce sites or content management systems that need to display product descriptions, articles, and other content in the language preferred by the user.
+
+- **Sending Multilingual Emails**: Whether it's transactional emails, marketing campaigns, or notifications, sending emails in the recipient’s language can significantly increase engagement and effectiveness.
+
+- **Multilingual Push Notifications**: For mobile applications, sending push notifications in a user's preferred language can enhance interaction and retention. This personal touch can make notifications feel more relevant and actionable.
+
+- **Other Communications**: Any form of communication from the backend, such as SMS messages, system alerts, or user interface updates, benefits from being in the user's language, ensuring clarity and enhancing the overall user experience.
+
+By internationalising the backend, your application not only respects cultural differences but also aligns better with global market needs, making it a key step in scaling your services worldwide.
+
+## Why to integrate Intlayer?
+
+- **Type-Safe Environment**: Leverage TypeScript to ensure all your content definitions are precise and error-free.
+
+## Installation
+
+Install the necessary package using your preferred package manager:
+
+```bash
+npm install express-intlayer
+```
+
+```bash
+yarn add express-intlayer
+```
+
+```bash
+pnpm add express-intlayer
+```
+
+### Configure Intlayer
+
+Intlayer provides a configuration file to set up your project. Place this file in the root of your project.
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalisation: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+import { Locales } from "intlayer";
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalisation: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+const { Locales } = require("intlayer");
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalisation: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+module.exports = config;
+```
+
+> For a complete list of available parameters, refer to the [configuration documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en-GB/configuration.md).
+
+## Example of usage
+
+Setup your Express application to use `express-intlayer`:
+
+```typescript fileName="src/index.ts" codeFormat="typescript"
+import express, { type Express } from "express";
+import { intlayer, t } from "express-intlayer";
+
+const app: Express = express();
+
+// Load internationalisation request handler
+app.use(intlayer());
+
+// Routes
+app.get("/", (_req, res) => {
+  res.send(
+    t({
+      en: "Example of returned content in English",
+      fr: "Exemple de contenu renvoyé en français",
+      "es-ES": "Ejemplo de contenido devuelto en español (España)",
+      "es-MX": "Ejemplo de contenido devuelto en español (México)",
+    })
+  );
+});
+
+// Start server
+app.listen(3000, () => console.log(`Listening on port 3000`));
+```
+
+```javascript fileName="src/index.mjs" codeFormat="esm"
+import express from "express";
+import { intlayer, t } from "express-intlayer";
+
+const app = express();
+
+// Load internationalisation request handler
+app.use(intlayer());
+
+// Routes
+app.get("/", (_req, res) => {
+  res.send(
+    t({
+      en: "Example of returned content in English",
+      fr: "Exemple de contenu renvoyé en français",
+      "es-MX": "Ejemplo de contenido devuelto en español (México)",
+      "es-ES": "Ejemplo de contenido devuelto en español (España)",
+    })
+  );
+});
+
+// Start server
+app.listen(3000, () => console.log(`Listening on port 3000`));
+```
+
+```javascript fileName="src/index.cjs" codeFormat="commonjs"
+const express = require("express");
+const { intlayer, t } = require("express-intlayer");
+
+const app = express();
+
+// Load internationalisation request handler
+app.use(intlayer());
+
+// Routes
+app.get("/", (_req, res) => {
+  res.send(
+    t({
+      en: "Example of returned content in English",
+      fr: "Exemple de contenu renvoyé en français",
+      "es-MX": "Ejemplo de contenido devuelto en español (México)",
+      "es-ES": "Ejemplo de contenido devuelto en español (España)",
+    })
+  );
+});
+
+// Start server
+app.listen(3000, () => console.log(`Listening on port 3000`));
+```
+
+### Compatibility
+
+`express-intlayer` is fully compatible with:
+
+- [`react-intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/en-GB/packages/react-intlayer/index.md) for React applications
+- [`next-intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/en-GB/packages/next-intlayer/index.md) for Next.js applications
+- [`vite-intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/en-GB/packages/vite-intlayer/index.md) for Vite applications
+
+It also works seamlessly with any internationalisation solution across various environments, including browsers and API requests. You can customise the middleware to detect locale through headers or cookies:
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  // ... Other configuration options
+  middleware: {
+    headerName: "my-locale-header",
+    cookieName: "my-locale-cookie",
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+import { Locales } from "intlayer";
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  // ... Other configuration options
+  middleware: {
+    headerName: "my-locale-header",
+    cookieName: "my-locale-cookie",
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+const { Locales } = require("intlayer");
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  // ... Other configuration options
+  middleware: {
+    headerName: "my-locale-header",
+    cookieName: "my-locale-cookie",
+  },
+};
+
+module.exports = config;
+```
+
+By default, `express-intlayer` will interpret the `Accept-Language` header to determine the client's preferred language.
+
+## Functions provided by `express-intlayer` package
+
+- [`t()`](https://github.com/aymericzip/intlayer/blob/main/docs/en-GB/packages/express-intlayer/t.md)

package/en-GB/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 localised responses in your Express 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.
+- **Lightweight and Fast**: Designed for high-performance applications, ensuring minimal overhead.
+- **Strict Mode Support**: Enforce strict adherence to declared locales for reliable behaviour.
+
+---
+
+## 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 Internationalisation Request Handler
+
+To ensure that the internationalisation functionality provided by `express-intlayer` works correctly, you **must** load the internationalisation 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 internationalisation:
+
+```typescript {7} fileName="src/index.ts" codeFormat="typescript"
+import express, { type Express } from "express";
+import { intlayer } from "express-intlayer";
+
+const app: Express = express();
+
+// Load internationalisation 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 internationalisation 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 internationalisation 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 localised 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 = {
+  internationalisation: {
+    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 = {
+  internationalisation: {
+    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 = {
+  internationalisation: {
+    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        | Behaviour                                                                                   |
+| ----------- | ------------------------------------------------------------------------------------------- |
+| `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
+  internationalisation: {
+    // ... Your existing internationalisation 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
+  internationalisation: {
+    // ... Your existing internationalisation 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
+  internationalisation: {
+    // ... Your existing internationalisation 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. **Centralise Translations**: Use a centralised 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**: Synchronise with frontend internationalisation 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 internationalisation. 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-GB/configuration.md).