@intlayer/docs 5.5.8

package/it/packages/intlayer/getConfiguration.md

@@ -0,0 +1,120 @@
+# Documentazione: Funzione `getConfiguration` in `intlayer`
+
+## Descrizione
+
+La funzione `getConfiguration` recupera l'intera configurazione per l'applicazione `intlayer` estraendo le variabili di ambiente. Questa funzione offre la flessibilità di utilizzare la stessa configurazione sia sul lato client che sul lato server, garantendo coerenza in tutta l'applicazione.
+
+---
+
+## Parametri
+
+La funzione non accetta parametri. Invece, utilizza le variabili di ambiente per la configurazione.
+
+### Restituisce
+
+- **Tipo**: `IntlayerConfig`
+- **Descrizione**: Un oggetto contenente la configurazione completa per `intlayer`. La configurazione include le seguenti sezioni:
+
+  - `internationalization`: Impostazioni relative ai locali e alla modalità rigorosa.
+  - `middleware`: Impostazioni relative alla gestione degli URL e dei cookie.
+  - `content`: Impostazioni relative ai file di contenuto, directory e pattern.
+  - `editor`: Configurazioni specifiche per l'editor.
+
+Consulta la [documentazione della configurazione di Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/it/configuration.md) per maggiori dettagli.
+
+---
+
+## Esempio di utilizzo
+
+### Recupero della configurazione completa
+
+```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: { ... }
+// }
+```
+
+### Estrazione di `availableLocales` e `defaultLocale`
+
+La sezione `internationalization` della configurazione fornisce impostazioni relative ai locali come `locales` (locali disponibili) e `defaultLocale` (lingua di fallback).
+
+```typescript codeFormat="typescript"
+import { getConfiguration } from "intlayer";
+
+const { internationalization, middleware } = getConfiguration();
+const { locales: availableLocales, defaultLocale } = internationalization;
+const { cookieName } = middleware;
+
+console.log(availableLocales); // Esempio di output: ["en", "fr", "es"]
+console.log(defaultLocale); // Esempio di output: "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); // Esempio di output: ["en", "fr", "es"]
+console.log(defaultLocale); // Esempio di output: "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); // Esempio di output: ["en", "fr", "es"]
+console.log(defaultLocale); // Esempio di output: "en"
+console.log(cookieName); // Output: "INTLAYER_LOCALE"
+```
+
+## Note
+
+- Assicurati che tutte le variabili di ambiente richieste siano correttamente impostate prima di chiamare questa funzione. Le variabili mancanti causeranno errori durante l'inizializzazione.
+- Questa funzione può essere utilizzata sia sul lato client che sul lato server, rendendola uno strumento versatile per gestire le configurazioni in modo unificato.
+
+## Utilizzo nelle applicazioni
+
+La funzione `getConfiguration` è un'utilità fondamentale per inizializzare e gestire la configurazione di un'applicazione `intlayer`. Fornendo accesso a impostazioni come locali, middleware e directory di contenuto, garantisce coerenza e scalabilità nelle applicazioni multilingue e basate sui contenuti.

package/it/packages/intlayer/getEnumeration.md

@@ -0,0 +1,138 @@
+# Documentazione: Funzione `getEnumeration` in `intlayer`
+
+## Descrizione
+
+La funzione `getEnumeration` recupera il contenuto corrispondente a una quantità specifica basandosi su condizioni predefinite in un oggetto enumerazione. Le condizioni sono definite come chiavi, e la loro priorità è determinata dall'ordine nell'oggetto.
+
+## Parametri
+
+- `enumerationContent: QuantityContent<Content>`
+
+  - **Descrizione**: Un oggetto in cui le chiavi rappresentano condizioni (ad esempio, `<=`, `<`, `>=`, `=`) e i valori rappresentano il contenuto corrispondente. L'ordine delle chiavi definisce la priorità di corrispondenza.
+  - **Tipo**: `QuantityContent<Content>`
+    - `Content` può essere di qualsiasi tipo.
+
+- `quantity: number`
+
+  - **Descrizione**: Il valore numerico utilizzato per confrontarsi con le condizioni in `enumerationContent`.
+  - **Tipo**: `number`
+
+## Restituisce
+
+- **Tipo**: `Content`
+- **Descrizione**: Il contenuto corrispondente alla prima condizione che corrisponde in `enumerationContent`. Se non viene trovata alcuna corrispondenza, si prevede un comportamento predefinito basato sull'implementazione (ad esempio, errore o contenuto di fallback).
+
+## Esempio di Utilizzo
+
+### Utilizzo Base
+
+```typescript codeFormat="typescript"
+import { getEnumeration } from "intlayer";
+
+const content = getEnumeration(
+  {
+    "<=-2.3": "Hai meno di -2.3",
+    "<1": "Hai meno di uno",
+    "2": "Hai due",
+    ">=3": "Hai tre o più",
+  },
+  2
+);
+
+console.log(content); // Output: "Hai due"
+```
+
+```javascript codeFormat="esm"
+import { getEnumeration } from "intlayer";
+
+const content = getEnumeration(
+  {
+    "<1": "Hai meno di uno",
+    "2": "Hai due",
+    ">=3": "Hai tre o più",
+  },
+  2
+);
+
+console.log(content); // Output: "Hai due"
+```
+
+```javascript codeFormat="commonjs"
+const { getEnumeration } = require("intlayer");
+
+const content = getEnumeration(
+  {
+    "<1": "Hai meno di uno",
+    "2": "Hai due",
+    ">=3": "Hai tre o più",
+  },
+  2
+);
+
+console.log(content); // Output: "Hai due"
+```
+
+### Priorità delle Condizioni
+
+```typescript codeFormat="typescript"
+import { getEnumeration } from "intlayer";
+
+const content = getEnumeration(
+  {
+    "<4": "Hai meno di quattro",
+    "2": "Hai due",
+  },
+  2
+);
+
+console.log(content); // Output: "Hai meno di quattro"
+```
+
+```javascript codeFormat="esm"
+import { getEnumeration } from "intlayer";
+
+const content = getEnumeration(
+  {
+    "<4": "Hai meno di quattro",
+    "2": "Hai due",
+  },
+  2
+);
+
+console.log(content); // Output: "Hai meno di quattro"
+```
+
+```javascript codeFormat="commonjs"
+const { getEnumeration } = require("intlayer");
+
+const content = getEnumeration(
+  {
+    "<4": "Hai meno di quattro",
+    "2": "Hai due",
+  },
+  2
+);
+
+console.log(content); // Output: "Hai meno di quattro"
+```
+
+## Casi Limite
+
+- **Nessuna Condizione Corrispondente:**
+
+  - Se nessuna condizione corrisponde alla quantità fornita, la funzione restituirà `undefined` o gestirà esplicitamente lo scenario predefinito/fallback.
+
+- **Condizioni Ambigue:**
+
+  - Se le condizioni si sovrappongono, la prima condizione corrispondente (basata sull'ordine dell'oggetto) ha la precedenza.
+
+- **Chiavi Non Valide:**
+
+  - La funzione presume che tutte le chiavi in `enumerationContent` siano valide e analizzabili come condizioni. Chiavi non valide o formattate in modo errato possono portare a comportamenti inaspettati.
+
+- **Enforcement di TypeScript:**
+  - La funzione garantisce che il tipo `Content` sia coerente su tutte le chiavi, permettendo la sicurezza del tipo nel contenuto recuperato.
+
+## Note
+
+- L'utilità `findMatchingCondition` è utilizzata per determinare la condizione appropriata basandosi sulla quantità fornita.

package/it/packages/intlayer/getHTMLTextDir.md

@@ -0,0 +1,97 @@
+# Documentazione: Funzione `getHTMLTextDir` in `intlayer`
+
+## Descrizione
+
+La funzione `getHTMLTextDir` determina la direzione del testo (`ltr`, `rtl` o `auto`) in base alla locale fornita. È progettata per aiutare gli sviluppatori a impostare l'attributo `dir` in HTML per una corretta visualizzazione del testo.
+
+## Parametri
+
+- `locale?: Locales`
+
+  - **Descrizione**: La stringa della locale (ad esempio, `Locales.ENGLISH`, `Locales.ARABIC`) utilizzata per determinare la direzione del testo.
+  - **Tipo**: `Locales` (opzionale)
+
+## Restituisce
+
+- **Tipo**: `Dir` (`'ltr' | 'rtl' | 'auto'`)
+- **Descrizione**: La direzione del testo corrispondente alla locale:
+  - `'ltr'` per le lingue da sinistra a destra.
+  - `'rtl'` per le lingue da destra a sinistra.
+  - `'auto'` se la locale non è riconosciuta.
+
+## Esempio di Utilizzo
+
+### Determinare la Direzione del Testo
+
+```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"
+```
+
+## Casi Limite
+
+- **Locale Non Fornita:**
+
+  - La funzione restituisce `'auto'` quando `locale` è `undefined`.
+
+- **Locale Non Riconosciuta:**
+  - Per le locali non riconosciute, la funzione predefinisce `'auto'`.
+
+## Utilizzo nei Componenti:
+
+La funzione `getHTMLTextDir` può essere utilizzata per impostare dinamicamente l'attributo `dir` in un documento HTML per una corretta visualizzazione del testo in base alla 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>
+);
+```
+
+Nell'esempio sopra, l'attributo `dir` è impostato dinamicamente in base alla locale.

package/it/packages/intlayer/getLocaleLang.md

@@ -0,0 +1,57 @@
+# Documentazione: Funzione `getLocaleLang` in `intlayer`
+
+## Descrizione
+
+La funzione `getLocaleLang` estrae il codice della lingua da una stringa locale. Supporta locali con o senza codici paese. Se non viene fornito alcun locale, restituisce una stringa vuota per impostazione predefinita.
+
+## Parametri
+
+- `locale?: Locales`
+
+  - **Descrizione**: La stringa locale (ad esempio, `Locales.ENGLISH_UNITED_STATES`, `Locales.FRENCH_CANADA`) da cui viene estratto il codice della lingua.
+  - **Tipo**: `Locales` (opzionale)
+
+## Restituisce
+
+- **Tipo**: `string`
+- **Descrizione**: Il codice della lingua estratto dal locale. Se il locale non è fornito, restituisce una stringa vuota (`''`).
+
+## Esempio di Utilizzo
+
+### Estrazione dei Codici Lingua:
+
+```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"
+```
+
+## Casi Limite
+
+- **Nessun Locale Fornito:**
+
+  - La funzione restituisce una stringa vuota quando `locale` è `undefined`.
+
+- **Stringhe Locale Malformate:**
+  - Se il `locale` non segue il formato `lingua-paese` (ad esempio, `Locales.ENGLISH-US`), la funzione restituisce in modo sicuro la parte prima di `'-'` o l'intera stringa se non è presente `'-'`.

package/it/packages/intlayer/getLocaleName.md

@@ -0,0 +1,93 @@
+# Documentazione: Funzione `getLocaleName` in `intlayer`
+
+## Descrizione
+
+La funzione `getLocaleName` restituisce il nome localizzato di una determinata lingua (`targetLocale`) nella lingua di visualizzazione (`displayLocale`). Se non viene fornito un `targetLocale`, restituisce il nome del `displayLocale` nella sua lingua.
+
+## Parametri
+
+- `displayLocale: Locales`
+
+  - **Descrizione**: La lingua in cui verrà visualizzato il nome della lingua di destinazione.
+  - **Tipo**: Enum o stringa che rappresenta lingue valide.
+
+- `targetLocale?: Locales`
+  - **Descrizione**: La lingua di cui si desidera localizzare il nome.
+  - **Tipo**: Opzionale. Enum o stringa che rappresenta lingue valide.
+
+## Restituisce
+
+- **Tipo**: `string`
+- **Descrizione**: Il nome localizzato del `targetLocale` nel `displayLocale`, o il nome del `displayLocale` se `targetLocale` non è fornito. Se non viene trovata alcuna traduzione, restituisce `"Unknown locale"`.
+
+## Esempio di utilizzo
+
+```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"
+```
+
+## Casi limite
+
+- **Nessun `targetLocale` fornito:**
+  - La funzione restituisce di default il nome del `displayLocale`.
+- **Traduzioni mancanti:**
+  - Se `localeNameTranslations` non contiene una voce per il `targetLocale` o il `displayLocale` specifico, la funzione utilizza il `ownLocalesName` o restituisce `"Unknown locale"`.