@intlayer/docs 5.5.8

package/en-GB/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/{{locale}}/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 } = configuration;
+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 } = configuration;
+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 } = configuration;
+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-GB/packages/intlayer/getEnumeration.md

@@ -0,0 +1,140 @@
+# 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 behaviour.
+
+- **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.
+
+[Documentation in English (United Kingdom)](https://github.com/aymericzip/intlayer/blob/main/docs/en-GB/getEnumeration.md)

package/en-GB/packages/intlayer/getHTMLTextDir.md

@@ -0,0 +1,97 @@
+# Documentation: `getHTMLTextDir` Function in `intlayer`
+
+## Description
+
+The `getHTMLTextDir` function determines the text direction (`ltr`, `rtl`, or `auto`) based on the provided locale. It is designed to help developers set the `dir` attribute in HTML for proper text rendering.
+
+## Parameters
+
+- `locale?: Locales`
+
+  - **Description**: The locale string (e.g., `Locales.ENGLISH`, `Locales.ARABIC`) used to determine the text direction.
+  - **Type**: `Locales` (optional)
+
+## Returns
+
+- **Type**: `Dir` (`'ltr' | 'rtl' | 'auto'`)
+- **Description**: The text direction corresponding to the locale:
+  - `'ltr'` for left-to-right languages.
+  - `'rtl'` for right-to-left languages.
+  - `'auto'` if the locale is not recognized.
+
+## Example Usage
+
+### Determining Text Direction
+
+```typescript codeFormat="typescript"
+import { getHTMLTextDir } from "intlayer";
+
+getHTMLTextDir(Locales.ENGLISH); // Output: "ltr"
+getHTMLTextDir(Locales.FRENCH); // Output: "ltr"
+getHTMLTextDir(Locales.ARABIC); // Output: "rtl"
+```
+
+```javascript codeFormat="esm"
+import { getHTMLTextDir } from "intlayer";
+
+getHTMLTextDir(Locales.ENGLISH); // Output: "ltr"
+getHTMLTextDir(Locales.FRENCH); // Output: "ltr"
+getHTMLTextDir(Locales.ARABIC); // Output: "rtl"
+```
+
+```javascript codeFormat="commonjs"
+const { getHTMLTextDir } = require("intlayer");
+
+getHTMLTextDir(Locales.ENGLISH); // Output: "ltr"
+getHTMLTextDir(Locales.FRENCH); // Output: "ltr"
+getHTMLTextDir(Locales.ARABIC); // Output: "rtl"
+```
+
+## Edge Cases
+
+- **No Locale Provided:**
+
+  - The function returns `'auto'` when `locale` is `undefined`.
+
+- **Unrecognized Locale:**
+  - For unrecognized locales, the function defaults to `'auto'`.
+
+## Usage in Components:
+
+The `getHTMLTextDir` function can be used to dynamically set the `dir` attribute in an HTML document for proper text rendering based on the locale.
+
+```tsx codeFormat="typescript"
+import type { FC } from "react";
+import { getHTMLTextDir, type Locales } from "intlayer";
+
+export const HTMLLayout: FC<PropsWithChildren<{ locale: Locales }>> = ({
+  children,
+  locale,
+}) => (
+  <html dir={getHTMLTextDir(locale)} locale={locale}>
+    <body>{children}</body>
+  </html>
+);
+```
+
+```jsx codeFormat="esm"
+import { getHTMLTextDir } from "intlayer";
+
+const HTMLLayout = ({ children, locale }) => (
+  <html dir={getHTMLTextDir(locale)} locale={locale}>
+    <body>{children}</body>
+  </html>
+);
+```
+
+```jsx codeFormat="commonjs"
+const { getHTMLTextDir } = require("intlayer");
+
+const HTMLLayout = ({ children, locale }) => (
+  <html dir={getHTMLTextDir(locale)} locale={locale}>
+    <body>{children}</body>
+  </html>
+);
+```
+
+In the example above, the `dir` attribute is dynamically set based on the locale.

package/en-GB/packages/intlayer/getLocaleLang.md

@@ -0,0 +1,57 @@
+# Documentation: `getLocaleLang` Function in `intlayer`
+
+## Description
+
+The `getLocaleLang` function extracts the language code from a locale string. It supports locales with or without country codes. If no locale is provided, it defaults to returning an empty string.
+
+## Parameters
+
+- `locale?: Locales`
+
+  - **Description**: The locale string (e.g., `Locales.ENGLISH_UNITED_STATES`, `Locales.FRENCH_CANADA`) from which the language code is extracted.
+  - **Type**: `Locales` (optional)
+
+## Returns
+
+- **Type**: `string`
+- **Description**: The language code extracted from the locale. If the locale is not provided, it returns an empty string (`''`).
+
+## Example Usage
+
+### Extracting Language Codes:
+
+```typescript codeFormat="typescript"
+import { getLocaleLang, Locales } from "intlayer";
+
+getLocaleLang(Locales.ENGLISH_UNITED_STATES); // Output: "en"
+getLocaleLang(Locales.ENGLISH); // Output: "en"
+getLocaleLang(Locales.FRENCH_CANADA); // Output: "fr"
+getLocaleLang(Locales.FRENCH); // Output: "fr"
+```
+
+```javascript codeFormat="esm"
+import { getLocaleLang } from "intlayer";
+
+getLocaleLang(Locales.ENGLISH_UNITED_STATES); // Output: "en"
+getLocaleLang(Locales.ENGLISH); // Output: "en"
+getLocaleLang(Locales.FRENCH_CANADA); // Output: "fr"
+getLocaleLang(Locales.FRENCH); // Output: "fr"
+```
+
+```javascript codeFormat="commonjs"
+const { getLocaleLang } = require("intlayer");
+
+getLocaleLang(Locales.ENGLISH_UNITED_STATES); // Output: "en"
+getLocaleLang(Locales.ENGLISH); // Output: "en"
+getLocaleLang(Locales.FRENCH_CANADA); // Output: "fr"
+getLocaleLang(Locales.FRENCH); // Output: "fr"
+```
+
+## Edge Cases
+
+- **No Locale Provided:**
+
+  - The function returns an empty string when `locale` is `undefined`.
+
+- **Malformed Locale Strings:**
+  - If the `locale` does not follow the `language-country` format (e.g., `Locales.ENGLISH-US`), the function safely returns the part before `'-'` or the entire string if no `'-'` is present.

package/en-GB/packages/intlayer/getLocaleName.md

@@ -0,0 +1,93 @@
+# Documentation: `getLocaleName` Function in `intlayer`
+
+## Description
+
+The `getLocaleName` function returns the localized name of a given locale (`targetLocale`) in the display locale (`displayLocale`). If no `targetLocale` is provided, it returns the name of the `displayLocale` in its own language.
+
+## Parameters
+
+- `displayLocale: Locales`
+
+  - **Description**: The locale in which the name of the target locale will be displayed.
+  - **Type**: Enum or string representing valid locales.
+
+- `targetLocale?: Locales`
+  - **Description**: The locale whose name is to be localized.
+  - **Type**: Optional. Enum or string representing valid locales.
+
+## Returns
+
+- **Type**: `string`
+- **Description**: The localized name of the `targetLocale` in the `displayLocale`, or the `displayLocale`'s own name if `targetLocale` is not provided. If no translation is found, it returns `"Unknown locale"`.
+
+## Example Usage
+
+```typescript codeFormat="typescript"
+import { Locales, getLocaleName } from "intlayer";
+
+getLocaleName(Locales.ENGLISH); // Output: "English"
+getLocaleName(Locales.ENGLISH, Locales.FRENCH); // Output: "Anglais"
+getLocaleName(Locales.ENGLISH, Locales.ESPANOL); // Output: "Inglés"
+getLocaleName(Locales.ENGLISH, Locales.ENGLISH); // Output: "English"
+
+getLocaleName(Locales.FRENCH); // Output: "Français"
+getLocaleName(Locales.FRENCH, Locales.FRENCH); // Output: "Français"
+getLocaleName(Locales.FRENCH, Locales.ESPANOL); // Output: "Francés"
+getLocaleName(Locales.FRENCH, Locales.ENGLISH); // Output: "French"
+
+getLocaleName(Locales.CHINESE); // Output: "中文"
+getLocaleName(Locales.CHINESE, Locales.FRENCH); // Output: "Chinois"
+getLocaleName(Locales.CHINESE, Locales.ESPANOL); // Output: "Chino"
+getLocaleName(Locales.CHINESE, Locales.ENGLISH); // Output: "Chinese"
+
+getLocaleName("unknown-locale"); // Output: "Unknown locale"
+```
+
+```javascript codeFormat="esm"
+import { Locales, getLocaleName } from "intlayer";
+
+getLocaleName(Locales.ENGLISH); // Output: "English"
+getLocaleName(Locales.ENGLISH, Locales.FRENCH); // Output: "Anglais"
+getLocaleName(Locales.ENGLISH, Locales.ESPANOL); // Output: "Inglés"
+getLocaleName(Locales.ENGLISH, Locales.ENGLISH); // Output: "English"
+
+getLocaleName(Locales.FRENCH); // Output: "Français"
+getLocaleName(Locales.FRENCH, Locales.FRENCH); // Output: "Français"
+getLocaleName(Locales.FRENCH, Locales.ESPANOL); // Output: "Francés"
+getLocaleName(Locales.FRENCH, Locales.ENGLISH); // Output: "French"
+
+getLocaleName(Locales.CHINESE); // Output: "中文"
+getLocaleName(Locales.CHINESE, Locales.FRENCH); // Output: "Chinois"
+getLocaleName(Locales.CHINESE, Locales.ESPANOL); // Output: "Chino"
+getLocaleName(Locales.CHINESE, Locales.ENGLISH); // Output: "Chinese"
+
+getLocaleName("unknown-locale"); // Output: "Unknown locale"
+```
+
+```javascript codeFormat="commonjs"
+const { Locales, getLocaleName } = require("intlayer");
+
+getLocaleName(Locales.ENGLISH); // Output: "English"
+getLocaleName(Locales.ENGLISH, Locales.FRENCH); // Output: "Anglais"
+getLocaleName(Locales.ENGLISH, Locales.ESPANOL); // Output: "Inglés"
+getLocaleName(Locales.ENGLISH, Locales.ENGLISH); // Output: "English"
+
+getLocaleName(Locales.FRENCH); // Output: "Français"
+getLocaleName(Locales.FRENCH, Locales.FRENCH); // Output: "Français"
+getLocaleName(Locales.FRENCH, Locales.ESPANOL); // Output: "Francés"
+getLocaleName(Locales.FRENCH, Locales.ENGLISH); // Output: "French"
+
+getLocaleName(Locales.CHINESE); // Output: "中文"
+getLocaleName(Locales.CHINESE, Locales.FRENCH); // Output: "Chinois"
+getLocaleName(Locales.CHINESE, Locales.ESPANOL); // Output: "Chino"
+getLocaleName(Locales.CHINESE, Locales.ENGLISH); // Output: "Chinese"
+
+getLocaleName("unknown-locale"); // Output: "Unknown locale"
+```
+
+## Edge Cases
+
+- **No `targetLocale` provided:**
+  - The function defaults to returning the `displayLocale`'s own name.
+- **Missing translations:**
+  - If `localeNameTranslations` does not contain an entry for the `targetLocale` or the specific `displayLocale`, the function falls back to the `ownLocalesName` or returns `"Unknown locale"`.