@intlayer/docs 9.5.4 → 9.5.5

package/docs/it/packages/astro-intlayer/intlayer.md

@@ -0,0 +1,76 @@
+---
+createdAt: 2026-01-21
+updatedAt: 2026-09-19
+title: Documentazione dell'integrazione intlayer | astro-intlayer
+description: Scopri come configurare e utilizzare l'integrazione Astro intlayer in astro.config.mjs.
+keywords:
+  - intlayer
+  - astro
+  - astro-intlayer
+  - integrazione
+  - i18n
+  - internazionalizzazione
+  - documentazione
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - intlayer
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Aggiornata documentazione dell'integrazione con dettagli su middleware e hook"
+  - version: 8.0.0
+    date: 2026-01-21
+    changes: "Doc iniziale"
+author: aymericzip
+---
+
+# Documentazione dell'integrazione Astro intlayer
+
+L'integrazione `intlayer` per Astro configura il tuo progetto per l'internazionalizzazione (i18n) multilingue. Gestisce la preparazione dei dizionari in fase di compilazione, l'inserimento dei plugin Vite, la registrazione automatica del middleware di richiesta e l'emissione di pagine pre-renderizzate localizzate.
+
+## Utilizzo
+
+Aggiungi `intlayer()` a `astro.config.mjs`:
+
+```ts fileName="astro.config.mjs"
+import { defineConfig } from "astro/config";
+import { intlayer } from "astro-intlayer";
+
+export default defineConfig({
+  integrations: [intlayer()],
+});
+```
+
+Il codemod dell'Astro CLI (`astro add astro-intlayer`) genera anche un'importazione predefinita supportata:
+
+```ts
+import intlayer from "astro-intlayer";
+```
+
+## Descrizione
+
+L'integrazione si inserisce nel ciclo di vita di compilazione ed esecuzione di Astro:
+
+1. **Configurazione iniziale (`astro:config:setup`)**:
+   - **Preparazione dizionari**: Prepara i dizionari Intlayer e i tipi generati prima dell'esecuzione della compilazione.
+   - **Plugin Vite**: Inserisce i plugin per gli alias Vite (abilitando importazioni dirette dei dizionari), proxy di routing dei locale e rimozione degli elementi superflui della compilazione.
+   - **Registrazione middleware**: Inserisce automaticamente `astro-intlayer/middleware` nella catena di middleware del progetto, popolando `Astro.locals.intlayer` a ogni richiesta in arrivo.
+2. **Compilazione completata (`astro:build:done`)**:
+   - **Riscritture di pagina**: Ispeziona le regole di riscrittura degli URL localizzati ed emette pagine HTML pre-renderizzate nei rispettivi percorsi localizzati.
+
+## Cosa viene fornito out-of-the-box
+
+Una volta configurata, la tua applicazione Astro può utilizzare immediatamente:
+
+- Gli hook `useIntlayer`, `useDictionary` e `useLocale` nel frontmatter dei componenti `.astro`.
+- L'oggetto `Astro.locals.intlayer` negli endpoint e nelle pagine Astro.
+- Importazioni lato client nei blocchi `<script>` che rispecchiano la stessa API con aggiornamenti reattivi.
+- Formattatori integrati sotto `astro-intlayer/format` (`useDate`, `useNumber`, `useCurrency`, ecc.).
+
+## Documentazione correlata
+
+- [Hook `useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/astro-intlayer/useIntlayer.md)
+- [Hook `useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/astro-intlayer/useLocale.md)
+- [Middleware `onRequest`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/astro-intlayer/onRequest.md)

package/docs/it/packages/astro-intlayer/onRequest.md

@@ -0,0 +1,76 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: Documentazione del middleware onRequest | astro-intlayer
+description: Scopri come utilizzare il middleware onRequest nelle applicazioni Astro per risolvere il locale della richiesta e popolare Astro.locals.intlayer.
+keywords:
+  - onRequest
+  - middleware
+  - astro
+  - astro-intlayer
+  - Astro.locals
+  - internazionalizzazione
+  - documentazione
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - onRequest
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Doc iniziale"
+author: aymericzip
+---
+
+# Documentazione del middleware Astro onRequest
+
+Il middleware `onRequest` di `astro-intlayer/middleware` risolve il locale di ciascuna richiesta HTTP in arrivo e popola `Astro.locals.intlayer`.
+
+Quando registri l'integrazione `intlayer()` in `astro.config.mjs`, questo middleware viene inserito automaticamente. È necessario importarlo direttamente solo se stai componendo manualmente il middleware Astro utilizzando `sequence(...)`.
+
+## Utilizzo
+
+```ts fileName="src/middleware.ts"
+import { onRequest as intlayer } from "astro-intlayer/middleware";
+import { sequence } from "astro:middleware";
+
+export const onRequest = sequence(intlayer, async (context, next) => {
+  // Accedi al locale risolto nel tuo middleware personalizzato
+  const { locale } = context.locals.intlayer;
+  console.log(`Gestione richiesta per il locale: ${locale}`);
+
+  return next();
+});
+```
+
+## Descrizione
+
+Il middleware esegue le seguenti operazioni:
+
+1. **Rilevamento del locale**:
+   - **URL**: Analizza il prefisso del percorso URL o il parametro di ricerca `?locale=` (a meno che `routing.mode` non sia impostato su `no-prefix`).
+   - **Cookie / Intestazioni**: Verifica i cookie di locale persistenti o i valori di intestazione personalizzati.
+   - **Accept-Language**: Utilizza come fallback la negoziazione della lingua preferita del browser.
+   - Per le pagine pre-renderizzate (`context.isPrerendered`), il locale viene estratto rigorosamente dall'URL per evitare avvisi di build di Astro.
+2. **Popolamento del contesto**: Popola `Astro.locals.intlayer` con:
+   - `locale`: Il locale risolto.
+   - `defaultLocale`: Il locale di fallback predefinito.
+   - `availableLocales`: L'array dei locale configurati.
+3. **Ambito AsyncLocalStorage**: Avvolge l'elaborazione downstream della richiesta all'interno di un ambito `AsyncLocalStorage`, consentendo a `useIntlayer()`, `useDictionary()` e `useLocale()` di accedere allo stato della richiesta senza passare argomenti.
+
+## Tipo `IntlayerLocals`
+
+```ts
+export type IntlayerLocals = {
+  locale: DeclaredLocales;
+  defaultLocale: DeclaredLocales;
+  availableLocales: DeclaredLocales[];
+};
+```
+
+## Documentazione correlata
+
+- [Integrazione `intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/astro-intlayer/intlayer.md)
+- [Hook `useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/astro-intlayer/useIntlayer.md)
+- [Hook `useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/astro-intlayer/useLocale.md)

package/docs/it/packages/astro-intlayer/useDictionary.md

@@ -0,0 +1,95 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: Documentazione dell'hook useDictionary | astro-intlayer
+description: Scopri come utilizzare l'hook useDictionary nei componenti e negli script Astro per risolvere oggetti dizionario.
+keywords:
+  - useDictionary
+  - dictionary
+  - astro
+  - astro-intlayer
+  - Intlayer
+  - intlayer
+  - internazionalizzazione
+  - documentazione
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - useDictionary
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Doc iniziale"
+author: aymericzip
+---
+
+# Documentazione dell'hook useDictionary
+
+L'hook `useDictionary` risolve un oggetto dizionario importato o inline e restituisce il suo contenuto per il locale corrente nelle applicazioni Astro.
+
+A differenza di `useIntlayer`, che recupera i dizionari tramite chiave dal registro globale dei dizionari, `useDictionary` lavora direttamente con un oggetto dizionario.
+
+## Utilizzo
+
+```astro fileName="src/pages/index.astro"
+---
+import { useDictionary } from "astro-intlayer";
+import homeContent from "../content/home.content";
+
+const content = useDictionary(homeContent);
+---
+
+<main>
+  <h1>{content.title}</h1>
+  <p>{content.description}</p>
+</main>
+```
+
+Puoi anche passare dizionari inline definiti con `t()`:
+
+```astro fileName="src/components/Footer.astro"
+---
+import { useDictionary } from "astro-intlayer";
+import { t } from "intlayer";
+
+const footer = useDictionary({
+  key: "footer",
+  content: {
+    copyright: t({
+      it: "Tutti i diritti riservati.",
+      en: "All rights reserved.",
+      fr: "Tous droits réservés.",
+      es: "Todos los derechos reservados.",
+    }),
+  },
+});
+---
+
+<footer>
+  <p>{footer.copyright}</p>
+</footer>
+```
+
+## Parametri
+
+```ts
+useDictionary(dictionary, localeOrSelector?)
+```
+
+1. **`dictionary`**: Un oggetto dizionario o un gruppo di dizionari qualificato.
+2. **`localeOrSelector`** (opzionale): Un locale specifico o un oggetto selettore (`{ item }`, `{ variant }`, facoltativamente con `locale`).
+
+## Descrizione
+
+L'hook esegue i seguenti compiti:
+
+1. **Rilevamento del locale**: Sul server, ottiene il locale da `Astro.locals.intlayer`. Nel browser, utilizza il locale dello store lato client.
+2. **Elaborazione del contenuto**: Risolve traduzioni (`t()`), enumerazioni, condizioni e strutture nidificate in base al locale risolto.
+3. **Selettori**: Applica qualsiasi selettore di elemento o variante fornito negli argomenti.
+
+## Documentazione correlata
+
+- [Integrazione `intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/astro-intlayer/intlayer.md)
+- [Hook `useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/astro-intlayer/useIntlayer.md)
+- [Hook `useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/astro-intlayer/useLocale.md)

package/docs/it/packages/astro-intlayer/useIntlayer.md

@@ -0,0 +1,98 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: Documentazione dell'hook useIntlayer | astro-intlayer
+description: Scopri come utilizzare l'hook useIntlayer nei componenti Astro e negli script client per accedere a contenuti localizzati.
+keywords:
+  - useIntlayer
+  - dictionary
+  - astro
+  - astro-intlayer
+  - Intlayer
+  - intlayer
+  - internazionalizzazione
+  - documentazione
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - useIntlayer
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Doc iniziale"
+author: aymericzip
+---
+
+# Documentazione dell'hook useIntlayer
+
+L'hook `useIntlayer` ti consente di recuperare contenuti di dizionario localizzati tramite chiave nelle applicazioni Astro.
+
+Può essere chiamato in due contesti distinti utilizzando lo stesso percorso di importazione:
+
+1. **Server / Frontmatter**: All'interno dei file `.astro`, risolve automaticamente il contenuto utilizzando il locale della richiesta memorizzato in `Astro.locals.intlayer`.
+2. **Browser / Tag `<script>` client**: Negli script client o nei componenti dei framework UI, risolve all'implementazione dello store lato client (`vanilla-intlayer`).
+
+## Utilizzo
+
+### Nel Frontmatter dei componenti Astro
+
+```astro fileName="src/pages/index.astro"
+---
+import { useIntlayer } from "astro-intlayer";
+
+const content = useIntlayer("home");
+---
+
+<main>
+  <h1>{content.title}</h1>
+  <p>{content.description}</p>
+</main>
+```
+
+### Nei blocchi `<script>` client
+
+```astro fileName="src/components/InteractiveWidget.astro"
+---
+import { useIntlayer } from "astro-intlayer";
+
+const content = useIntlayer("home");
+---
+
+<button id="alert-btn">{content.buttonText}</button>
+
+<script>
+  import { useIntlayer } from "astro-intlayer";
+
+  const content = useIntlayer("home");
+
+  document.getElementById("alert-btn")?.addEventListener("click", () => {
+    alert(content.buttonText);
+  });
+</script>
+```
+
+## Parametri
+
+```ts
+useIntlayer(key, localeOrSelector?)
+```
+
+1. **`key`**: La chiave univoca del dizionario (definita nei tuoi file di dichiarazione `.content.ts`).
+2. **`localeOrSelector`** (opzionale): Un locale specifico o un oggetto selettore (`{ item }`, `{ variant }`, facoltativamente con `locale`). Se fornito, sovrascrive il locale rilevato dal contesto della richiesta o dallo store client.
+
+## Descrizione
+
+L'hook esegue i seguenti compiti:
+
+1. **Risoluzione del locale**:
+   - Sul server, legge il locale attivo da `Astro.locals.intlayer` tramite un ambito `AsyncLocalStorage` inizializzato da `astro-intlayer/middleware`.
+   - Nel browser, legge il locale attivo dallo storage/store client.
+2. **Recupero del dizionario**: Inietta il contenuto del dizionario corrispondente alla chiave specificata.
+3. **Elaborazione della traduzione**: Risolve traduzioni (`t()`), enumerazioni, condizioni e markdown in contenuti pronti per il rendering.
+
+## Documentazione correlata
+
+- [Integrazione `intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/astro-intlayer/intlayer.md)
+- [Hook `useDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/astro-intlayer/useDictionary.md)
+- [Hook `useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/astro-intlayer/useLocale.md)

package/docs/it/packages/astro-intlayer/useLocale.md

@@ -0,0 +1,126 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: Documentazione dell'hook useLocale | astro-intlayer
+description: Scopri come utilizzare l'hook useLocale nelle applicazioni Astro per accedere e gestire il locale corrente.
+keywords:
+  - useLocale
+  - locale
+  - astro
+  - astro-intlayer
+  - Intlayer
+  - intlayer
+  - internazionalizzazione
+  - documentazione
+slugs:
+  - doc
+  - packages
+  - astro-intlayer
+  - useLocale
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Doc iniziale"
+author: aymericzip
+---
+
+# Documentazione dell'hook useLocale
+
+L'hook `useLocale` di `astro-intlayer` fornisce l'accesso al locale della richiesta corrente, al locale predefinito configurato e a tutti i locale disponibili nelle applicazioni Astro.
+
+Si comporta in modo coerente nel frontmatter `.astro` renderizzato dal server e nei blocchi `<script>` lato client.
+
+## Utilizzo
+
+### Nel Frontmatter dei componenti (Renderizzato dal server)
+
+```astro fileName="src/layouts/Layout.astro"
+---
+import { useLocale } from "astro-intlayer";
+import { getLocalizedUrl, getPathWithoutLocale } from "intlayer";
+
+const { locale, defaultLocale, availableLocales } = useLocale();
+const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);
+---
+
+<!DOCTYPE html>
+<html lang={locale}>
+  <head>
+    <meta charset="utf-8" />
+    <title>Astro + Intlayer</title>
+  </head>
+  <body>
+    <header>
+      <span>Corrente: {locale}</span>
+      <span>Predefinito: {defaultLocale}</span>
+      <nav>
+        <ul>
+          {availableLocales.map((localeItem) => (
+            <li key={localeItem} className="p-1">
+              <a
+                href={getLocalizedUrl(pathWithoutLocale, localeItem)}
+                aria-current={localeItem === locale ? "page" : undefined}
+              >
+                {localeItem.toUpperCase()}
+              </a>
+            </li>
+          ))}
+        </ul>
+      </nav>
+    </header>
+    <slot />
+  </body>
+</html>
+```
+
+### In `<script>` client (Interattivo)
+
+```astro fileName="src/components/LocaleSwitcher.astro"
+---
+import { useLocale } from "astro-intlayer";
+
+const { locale, availableLocales } = useLocale();
+---
+
+<select id="locale-select">
+  {availableLocales.map((loc) => (
+    <option value={loc} selected={loc === locale}>
+      {loc.toUpperCase()}
+    </option>
+  ))}
+</select>
+
+<script>
+  import { useLocale, setLocaleInStorage } from "astro-intlayer";
+
+  const { setLocale } = useLocale();
+
+  document.getElementById("locale-select")?.addEventListener("change", (e) => {
+    const target = e.target as HTMLSelectElement;
+    setLocale(target.value);
+  });
+</script>
+```
+
+## Valori restituiti
+
+L'hook restituisce un oggetto di tipo `UseLocaleResult`:
+
+| Proprietà          | Tipo                                   | Descrizione                                                                         |
+| ------------------ | -------------------------------------- | ----------------------------------------------------------------------------------- |
+| `locale`           | `DeclaredLocales`                      | Il locale attivo.                                                                   |
+| `defaultLocale`    | `DeclaredLocales`                      | Il locale di fallback predefinito configurato in `intlayer.config.ts`.              |
+| `availableLocales` | `DeclaredLocales[]`                    | Array di tutti i locale supportati configurati per il progetto.                     |
+| `setLocale`        | `(locale: LocalesValues) => void`      | Funzione per aggiornare il locale. (Interattiva in `<script>`, avvisa durante SSR). |
+| `subscribe`        | `(callback: () => void) => () => void` | Si iscrive alle modifiche del locale sul lato client.                               |
+
+## Comportamento Server vs Client
+
+- **Durante SSR / Rendering del Server**: Una richiesta viene elaborata una volta con parametri fissi. Chiamare `setLocale()` durante un rendering del server non ha alcun effetto ed emette un avviso; il cambio di locale deve essere eseguito sul client o navigando verso l'URL del locale di destinazione.
+- **Negli script client**: `setLocale` aggiorna lo store client e aggiorna i cookie persistiti o la memoria locale in base alla configurazione di Intlayer.
+
+## Documentazione correlata
+
+- [Integrazione `intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/astro-intlayer/intlayer.md)
+- [Hook `useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/astro-intlayer/useIntlayer.md)
+- [Hook `useDictionary`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/astro-intlayer/useDictionary.md)

package/docs/it/packages/remix-intlayer/Intlayer.md

@@ -0,0 +1,77 @@
+---
+createdAt: 2026-09-19
+updatedAt: 2026-09-19
+title: Documentazione del contesto Intlayer | remix-intlayer
+description: Scopri come utilizzare la chiave e la proprietà del contesto di richiesta Intlayer nelle applicazioni Remix 3.
+keywords:
+  - Intlayer
+  - remix
+  - remix-3
+  - contesto
+  - RequestContext
+  - Internazionalizzazione
+  - Documentazione
+slugs:
+  - doc
+  - packages
+  - remix-intlayer
+  - Intlayer
+history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Init doc"
+author: aymericzip
+---
+
+# Documentazione del contesto Intlayer
+
+In `remix-intlayer`, `Intlayer` è la chiave di `RequestContext` utilizzata per accedere allo stato di internazionalizzazione all'interno dei gestori di richieste di Remix 3.
+
+## Utilizzo
+
+Quando il middleware `intlayer()` viene eseguito, memorizza un oggetto `IntlayerState` nel contesto della richiesta sotto la chiave `Intlayer`. Puoi recuperarlo all'interno di qualsiasi gestore di route:
+
+```ts fileName="src/server.ts"
+import { createRouter } from "remix/router";
+import { intlayer, Intlayer } from "remix-intlayer";
+
+const router = createRouter({
+  middleware: [intlayer()],
+});
+
+router.get("/api/profile", (context) => {
+  // Accesso tramite context.get(Intlayer)
+  const { locale, defaultLocale, availableLocales } = context.get(Intlayer);
+
+  return Response.json({
+    locale,
+    defaultLocale,
+    availableLocales,
+  });
+});
+```
+
+Puoi accedere anche utilizzando la scorciatoia diretta della proprietà `context.intlayer`:
+
+```ts
+router.get("/api/status", (context) => {
+  const currentLocale = context.intlayer.locale;
+  return Response.json({ status: "ok", locale: currentLocale });
+});
+```
+
+## Struttura di `IntlayerState`
+
+L'oggetto `IntlayerState` contiene:
+
+| Proprietà          | Tipo                | Descrizione                                                            |
+| ------------------ | ------------------- | ---------------------------------------------------------------------- |
+| `locale`           | `DeclaredLocales`   | La locale risolta per la richiesta corrente.                           |
+| `defaultLocale`    | `DeclaredLocales`   | La locale di fallback predefinita configurata in `intlayer.config.ts`. |
+| `availableLocales` | `DeclaredLocales[]` | L'elenco di tutte le locale supportate configurate per il progetto.    |
+
+## Documentazione correlata
+
+- [Middleware `intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/remix-intlayer/intlayerMiddleware.md)
+- [Hook `useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/remix-intlayer/useLocale.md)
+- [Hook `useIntlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/remix-intlayer/useIntlayer.md)