@intlayer/docs 5.5.10 → 5.5.12

package/frequent_questions/it/build_error_CI_CD.md

@@ -0,0 +1,75 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Errore di build in CI/CD
+description: Scopri come risolvere gli errori di build che si verificano negli ambienti CI/CD.
+keywords:
+  - build
+  - errore
+  - ci
+  - cd
+  - pipeline
+  - intlayer
+  - dizionari
+  - next.js
+  - prebuild
+  - automazione
+slugs:
+  - doc
+  - faq
+  - build-error-ci-cd
+---
+
+# Errore di build in CI/CD
+
+Se ricevi un errore come questo su Next.js:
+
+```text
+Error: An error occurred in the Server Components render. The specific message is omitted in production builds to avoid leaking sensitive details. A digest property is included on this error instance which may provide additional details about the nature of the error
+```
+
+Ecco alcune soluzioni:
+
+## 1. Dizionari mancanti
+
+Assicurati che i dizionari siano costruiti nella fase di build.
+
+È frequente che la build funzioni localmente ma non su CI/CD. Il motivo è che localmente la directory `.intlayer` è presente, mentre su CI/CD non lo è perché è esclusa dalla build.
+
+Puoi risolvere aggiungendo uno script di prebuild nel `package.json` del tuo progetto.
+
+```json5 fileName=package.json
+{
+  // ...
+  "scripts": {
+    "prebuild": "npx intlayer dictionaries build", // Verrà eseguito prima della build
+    "build": "next build",
+  },
+}
+```
+
+> Nota che se usi la funzione `withIntlayer`, o il plugin bundler equivalente per il tuo framework, lo script di prebuild verrà eseguito prima della build.
+
+## 2. Variabili d'ambiente mancanti al momento della build o dell'esecuzione
+
+In un container, o su una piattaforma con deploy automatico, è consigliato escludere il file `.env` dalla build.
+
+```text fileName=".gitignore or .dockerignore"
+# Variabili d'ambiente
+.env
+**/.env
+.env.*
+**/.env.*
+```
+
+Se le tue variabili d'ambiente non sono disponibili al momento della build, verrà generato un errore.
+
+```ts
+import { Metadata } from "next";
+
+export const generateMetadata = async ({ params }): Promise<Metadata> => ({
+  metadataBase: new URL(process.env.NEXT_PUBLIC_URL),
+});
+```
+
+Probabilmente non è correlato a Intlayer. Quindi verifica le tue variabili d'ambiente al momento della build sulla tua piattaforma CI/CD.

package/frequent_questions/it/customized_locale_list.md

@@ -0,0 +1,65 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Come personalizzare la lista delle localizzazioni?
+description: Scopri come personalizzare la lista delle localizzazioni.
+keywords:
+  - localizzazioni
+  - lista
+  - intlayer
+  - configurazione
+  - availableLocales
+  - defaultLocale
+  - useLocale
+  - hook
+  - localizzazione
+  - lista
+slugs:
+  - doc
+  - faq
+  - lista-localizzazioni-personalizzata
+---
+
+# È possibile bloccare un tipo di lingua, come l'inglese? Sto aggiungendo l'inglese nei miei dizionari ma non voglio che l'inglese sia ancora disponibile sul sito web
+
+Sì, puoi bloccare un tipo di lingua, come l'inglese, utilizzando l'opzione `availableLocales` nella configurazione di Intlayer.
+
+```ts
+import { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  locales: [Locales.FRENCH, Locales.SPANISH, Locales.ENGLISH],
+  availableLocales: [Locales.FRENCH, Locales.SPANISH],
+  defaultLocale: Locales.FRENCH,
+};
+```
+
+oppure
+
+```ts
+import { IntlayerConfig } from "intlayer";
+
+const locales = [Locales.FRENCH, Locales.SPANISH, Locales.ENGLISH];
+
+const config: IntlayerConfig = {
+  locales,
+  availableLocales: locales.filter((locale) => locale !== Locales.ENGLISH),
+  defaultLocale: Locales.FRENCH,
+};
+```
+
+Questa configurazione modificherà i tipi della tua funzione `t()` per includere solo le localizzazioni disponibili.
+
+L'opzione availableLocales è facoltativa, se non la fornisci, tutte le localizzazioni saranno disponibili.
+
+Fai attenzione, tutte le localizzazioni incluse nell'opzione `availableLocales` devono essere incluse anche nell'opzione `locales`.
+
+Nota che se usi l'hook `useLocale`, l'opzione `availableLocales` sarà utilizzata per impostare l'accesso alla lista delle localizzazioni.
+
+```ts
+import { useLocale } from "intlayer";
+
+const { availableLocales } = useLocale();
+
+console.log(availableLocales); // [Locales.FRENCH, Locales.SPANISH]
+```

package/frequent_questions/it/domain_routing.md

@@ -0,0 +1,114 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Come configurare il routing basato sul dominio?
+description: Scopri come configurare il routing basato sul dominio.
+keywords:
+  - dominio
+  - routing
+  - intlayer
+  - configurazione
+  - middleware
+  - react-router
+  - vue-router
+  - next.js
+  - vite
+  - framework
+slugs:
+  - doc
+  - faq
+  - domain-routing
+---
+
+# Come configurare il **routing basato sul dominio** con Intlayer invece dei percorsi `/[locale]/`?
+
+## Risposta breve
+
+Il routing basato sul dominio è più semplice rispetto al routing basato sul percorso (`example.com/[locale]/`) perché puoi evitare tutta la configurazione di middleware e routing. Basta distribuire la tua app su ogni dominio linguistico e impostare una variabile d'ambiente per ogni dominio.
+
+## Passo dopo passo
+
+1. **Distribuisci una volta per dominio** (`example.com`, `exemple.fr`, `ejemplo.es`, …).
+2. Per ogni distribuzione, imposta `LOCALE` (e le solite variabili d'ambiente di Intlayer) sulla lingua che quel dominio deve servire.
+3. Riferisciti a quella variabile come `defaultLocale` nel tuo file `intlayer.config.[ts|js]`.
+
+```ts
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: process.env.LOCALE, // 👈 il dominio decide la lingua
+  },
+  // ... il resto della tua configurazione
+};
+
+export default config;
+```
+
+Questo è tutto—funziona allo stesso modo per **Next.js**, **Vite + React**, **Vite + Vue**, ecc.
+
+## Cosa succede se tutti i domini puntano alla **stessa** distribuzione?
+
+Se tutti i domini puntano allo stesso bundle dell'applicazione, sarà necessario rilevare l'host a runtime e passare manualmente la lingua tramite il provider.
+
+### Per Next.js
+
+```tsx
+// src/IntlayerProvider.tsx
+import {
+  IntlayerClientProvider,
+  type IntlayerClientProviderProps,
+} from "next-intlayer";
+import { IntlayerServerProvider } from "next-intlayer/server";
+import type { FC } from "react";
+
+export const IntlayerProvider: FC<IntlayerClientProviderProps> = ({
+  children,
+  locale,
+}) => {
+  const resolvedLocale = locale ?? getLocaleFromHostname(); // 👈 risolvi la lingua dal nome host
+  return (
+    <IntlayerServerProvider locale={resolvedLocale}>
+      <IntlayerClientProvider locale={resolvedLocale}>
+        {children}
+      </IntlayerClientProvider>
+    </IntlayerServerProvider>
+  );
+};
+```
+
+### Per Vue
+
+```ts
+import { createApp } from "vue";
+import { installIntlayer } from "vue-intlayer";
+import App from "./App.vue";
+import { router } from "./routes";
+
+const app = createApp(App);
+app.use(router);
+installIntlayer(app, getLocaleFromHostname());
+app.mount("#app");
+```
+
+Sostituisci `getLocaleFromHostname()` con la tua logica di ricerca personalizzata.
+
+## Aggiorna il tuo selettore di lingua
+
+Quando si utilizza il routing basato sul dominio, cambiare lingua significa navigare verso un altro dominio:
+
+```ts
+const { locale } = useLocale();
+
+function changeLanguage(target: Locale) {
+  window.location.href = domainForLocale[target];
+}
+```
+
+## Vantaggi del routing basato sul dominio
+
+1. **Configurazione più semplice**: Non è necessario configurare `intlayerMiddleware`, `generateStaticParams`, `react-router` o `vue-router`
+2. **Migliore SEO**: Ogni lingua ha il proprio dominio
+3. **URL più puliti**: Nessun prefisso di localizzazione nel percorso
+4. **Manutenzione più semplice**: Ogni distribuzione linguistica è indipendente

package/frequent_questions/it/esbuild_error.md

@@ -0,0 +1,30 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Errore ESBuild
+description: Scopri come risolvere gli errori di ESBuild.
+keywords:
+  - esbuild
+  - errore
+  - intlayer
+  - plugin
+  - framework
+  - next.js
+  - vite
+  - react-native
+  - lynx
+slugs:
+  - doc
+  - faq
+  - errore-esbuild
+---
+
+# Errore ESBuild
+
+Se incontri un errore ESBuild durante il processo di build, è probabile che il plugin Intlayer non sia stato configurato correttamente.
+
+ESBuild è responsabile della lettura dei file di dichiarazione del contenuto (`.content.{ts,js,mjs,cjs,json}`) e della generazione dei dizionari corrispondenti nella cartella `.intlayer/dictionary`. Inoltre, legge il file di configurazione (`intlayer.config.ts`).
+
+Intlayer fornisce plugin per integrarsi con i tuoi bundler. È progettato per aliasare componenti che devono essere eseguiti solo sul lato server.
+
+Se stai utilizzando un framework come Next.js (Webpack / Turbopack), Vite, React Native, Lynx, ecc., Intlayer fornisce un plugin che puoi utilizzare per integrare Intlayer nella tua applicazione. Consulta quindi la documentazione specifica del tuo framework per imparare come integrare il plugin.

package/frequent_questions/it/get_locale_cookie.md

@@ -0,0 +1,144 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Come recuperare la locale dai cookie / header?
+description: Scopri come recuperare la locale dai cookie / header.
+keywords:
+  - cookie
+  - header
+  - intlayer
+  - locale
+  - hook
+  - useLocale
+  - useLocaleCookie
+  - next.js
+  - react-intlayer
+  - vue-intlayer
+slugs:
+  - doc
+  - faq
+  - get-locale-cookie
+---
+
+# Come recuperare la locale dai cookie / header
+
+## Uso degli Hooks (Consigliato)
+
+Per la maggior parte dei casi d'uso, è consigliato recuperare la locale corrente usando l'hook `useLocale` perché viene risolto automaticamente. Questo funziona in modo simile al composable `useLocale` in Vue.js.
+
+```ts
+import { useLocale } from "next-intlayer";
+// oppure import { useLocale } from "react-intlayer";
+// oppure import { useLocale } from "vue-intlayer";
+
+ts;
+// Uso lato client
+const { locale } = useLocale();
+```
+
+Per i componenti server, puoi importarlo da:
+
+```tsx
+import { useLocale } from "next-intlayer/server";
+
+const Test = () => {
+  const { locale } = useLocale();
+  return <>{locale}</>;
+};
+
+const Page = async ({ params }) => {
+  const { locale } = await params;
+
+  return (
+    <IntlayerServerProvider locale={locale}>
+      <Test />
+    </IntlayerServerProvider>
+  );
+};
+```
+
+Esiste anche un hook `useLocaleCookie` che risolve solo il valore del cookie.
+
+## Configurazione manuale del cookie
+
+Puoi dichiarare un nome personalizzato per il cookie come
+
+```ts
+import { type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  middleware: {
+    cookieName: "myCustomLocaleCookie", // il valore predefinito è 'intlayer-locale'
+  },
+};
+
+export default config;
+```
+
+il recupero come
+
+### Lato client
+
+```ts
+// Uso del nome cookie predefinito
+const locale = document.cookie
+  .split("; ")
+  .find((row) => row.startsWith("intlayer-locale="))
+  ?.split("=")[1];
+
+// Uso di un nome cookie personalizzato
+const locale = document.cookie
+  .split("; ")
+  .find((row) => row.startsWith("myCustomLocaleCookie="))
+  ?.split("=")[1];
+```
+
+### Lato server (Next.js)
+
+```ts
+import { cookies } from "next/headers";
+
+// Uso del nome cookie predefinito
+const locale = cookies().get("intlayer-locale")?.value;
+
+// Uso di un nome cookie personalizzato
+const locale = cookies().get("myCustomLocaleCookie")?.value;
+```
+
+### Se la locale non è ancora impostata
+
+La locale viene impostata come cookie solo una volta che l'utente seleziona esplicitamente la locale. Per impostazione predefinita, per i nuovi visitatori, la locale viene interpretata dai campi degli header.
+
+Puoi rilevare la locale preferita dall'utente dagli header della richiesta. Ecco un esempio di come gestirlo:
+
+```ts
+/**
+ * Rileva la locale dagli header della richiesta
+ *
+ * L'header accept-language è il più importante per il rilevamento della locale.
+ * Contiene una lista di codici lingua con valori di qualità (q-values) che indicano
+ * le lingue preferite dall'utente in ordine di preferenza.
+ *
+ * Esempio: "en-US,en;q=0.9,fr;q=0.8,es;q=0.7"
+ * - en-US è la lingua primaria (q=1.0 è implicito)
+ * - en è la seconda scelta (q=0.9)
+ * - fr è la terza scelta (q=0.8)
+ * - es è la quarta scelta (q=0.7)
+ */
+import { localeDetector } from "@intlayer/core";
+
+/**
+ * Esempio di header di negoziazione che i browser tipicamente inviano
+ * Questi header aiutano a determinare la lingua preferita dall'utente
+ */
+const exampleNegotiatorHeaders: Record<string, string> = {
+  "accept-language": "en-US,en;q=0.9,fr;q=0.8,es;q=0.7",
+  "accept":
+    "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
+  "user-agent":
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
+};
+
+// Esempio di utilizzo:
+const detectedLocale = localeDetector(exampleNegotiatorHeaders);
+```

package/frequent_questions/it/intlayer_command_undefined.md

@@ -0,0 +1,157 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Comando Intlayer non definito
+description: Scopri come risolvere l'errore comando intlayer non definito.
+keywords:
+  - intlayer
+  - comando
+  - non definito
+  - errore
+  - vscode
+  - estensione
+  - plugin
+  - framework
+  - next.js
+  - vite
+slugs:
+  - doc
+  - faq
+  - comando-intlayer-non-definito
+---
+
+# Comando Intlayer non definito
+
+## Panoramica
+
+La CLI di Intlayer offre un modo comodo per gestire i contenuti di intlayer, inclusa la creazione di dizionari, l'invio delle traduzioni e altro ancora. Tuttavia, non è essenziale per il funzionamento del tuo progetto. Se stai utilizzando il plugin bundler (come `withIntlayer()` per Next.js o `intlayerPlugin()` per Vite), Intlayer costruirà automaticamente i dizionari durante la compilazione dell'app o l'avvio del server di sviluppo. In modalità sviluppo, monitorerà anche le modifiche e ricostruirà automaticamente i file di dichiarazione dei contenuti.
+
+Puoi accedere ai comandi di intlayer in diversi modi:
+
+- Usando direttamente il comando CLI `intlayer`
+- Usando l'[estensione VSCode](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/vs_code_extension.md)
+- Usando l'SDK `@intlayer/cli`
+
+## Problema
+
+Quando si tenta di utilizzare il comando `intlayer`, potresti incontrare questo errore:
+
+```bash
+'intlayer' non è riconosciuto come comando interno o esterno,
+programma eseguibile o file batch.
+```
+
+## Soluzioni
+
+Prova queste soluzioni in ordine:
+
+1. **Verifica che il comando sia installato**
+
+```bash
+npx intlayer -h
+```
+
+Output previsto:
+
+```bash
+Usage: intlayer [options] [command]
+
+Intlayer CLI
+
+Options:
+    -V, --version            output the version number
+    -h, --help               display help for command
+
+Commands:
+    dictionary|dictionaries  Dictionaries operations
+    configuration|config     Configuration operations
+    help [command]           display help for command
+```
+
+2. **Installa globalmente il pacchetto intlayer-cli**
+
+```bash
+npm install intlayer-cli -g -g
+```
+
+> Non dovrebbe essere necessario se hai già installato il pacchetto `intlayer`
+
+3. **Installa il pacchetto globalmente**
+
+```bash
+npm install intlayer -g
+```
+
+4. **Riavvia il terminale**
+   A volte è necessario riavviare il terminale per riconoscere i nuovi comandi.
+
+5. **Pulisci e reinstalla**
+   Se le soluzioni precedenti non funzionano:
+
+```bash
+rm -rf node_modules package-lock.json
+npm install
+```
+
+6. **Verifica i file di installazione**
+   Se il problema persiste, controlla che questi file esistano:
+
+   - `node_modules/intlayer/dist/cjs/cli.cjs`
+   - `node_modules/intlayer/package.json` (dovrebbe avere un campo `bin` che fa riferimento a `./dist/cjs/cli.cjs`)
+
+7. **Controlla la variabile d'ambiente PATH**
+   Assicurati che la directory bin globale di npm sia nel tuo PATH:
+
+```bash
+# Per sistemi Unix-based (macOS/Linux)
+echo $PATH
+# Dovrebbe includere qualcosa come /usr/local/bin o ~/.npm-global/bin
+
+# Per Windows
+echo %PATH%
+# Dovrebbe includere la directory bin globale di npm
+```
+
+8. **Usa npx con il percorso completo**
+   Se il comando non viene ancora trovato, prova a usare npx con il percorso completo:
+
+```bash
+npx ./node_modules/intlayer/ dictionaries build
+```
+
+9. **Controlla installazioni in conflitto**
+
+```bash
+# Elenca tutti i pacchetti installati globalmente
+npm list -g --depth=0
+
+# Rimuovi eventuali installazioni globali in conflitto
+npm uninstall -g intlayer
+npm uninstall -g intlayer-cli
+# Poi reinstalla
+npm install -g intlayer
+```
+
+10. **Verifica le versioni di Node.js e npm**
+    Assicurati di usare versioni compatibili:
+
+```bash
+node --version
+npm --version
+```
+
+    Se stai usando una versione obsoleta, considera di aggiornare Node.js e npm.
+
+11. **Controlla problemi di permessi**
+    Se ricevi errori di permessi:
+
+    ```bash
+    # Per sistemi basati su Unix
+    sudo npm install -g intlayer
+
+    # Oppure cambia la directory predefinita di npm
+    mkdir ~/.npm-global
+    npm config set prefix '~/.npm-global'
+    # Aggiungi al tuo ~/.profile o ~/.bashrc:
+    export PATH=~/.npm-global/bin:$PATH
+    ```

package/frequent_questions/it/locale_incorect_in_url.md

@@ -0,0 +1,74 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Locale Errato Recuperato dall'URL
+description: Scopri come correggere il locale errato recuperato dall'URL.
+keywords:
+  - locale
+  - url
+  - intlayer
+  - next.js
+  - vite
+  - framework
+  - middleware
+  - configurazione
+  - prefixDefault
+  - noPrefix
+slugs:
+  - doc
+  - faq
+  - locale-errato-nell-url
+---
+
+# Locale Errato Recuperato dall'URL
+
+## Descrizione del Problema
+
+Quando si tenta di accedere al parametro locale dall'URL, potresti incontrare un problema in cui il valore del locale è errato:
+
+```js
+const { locale } = await params;
+console.log(locale); // restituisce "about" invece del locale previsto
+```
+
+## Soluzione
+
+### 1. Verifica la Struttura dei File
+
+Assicurati che il percorso del router della tua app Next.js segua questa struttura:
+
+```bash
+src/app/[locale]/about/page.tsx
+```
+
+### 2. Verifica la Configurazione del Middleware
+
+Il problema si verifica spesso quando il middleware non è presente o non viene attivato. Il file del middleware dovrebbe trovarsi in:
+
+```bash
+src/middleware.ts
+```
+
+Questo middleware è responsabile della riscrittura delle rotte quando `prefixDefault` è impostato su `false`. Ad esempio, riscrive `/en/about` in `/about`.
+
+### 3. Modelli di URL Basati sulla Configurazione
+
+#### Configurazione Predefinita (`prefixDefault: false`, `noPrefix: false`)
+
+- Inglese: `/about`
+- Francese: `/fr/about`
+- Spagnolo: `/es/about`
+
+#### Con `prefixDefault: true`
+
+- Inglese: `/en/about`
+- Francese: `/fr/about`
+- Spagnolo: `/es/about`
+
+#### Con `noPrefix: true`
+
+- Inglese: `/about`
+- Francese: `/about`
+- Spagnolo: `/about`
+
+Per maggiori dettagli su queste opzioni di configurazione, consulta la [Documentazione sulla Configurazione](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/configuration.md).

package/frequent_questions/it/static_rendering.md

@@ -0,0 +1,46 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-06-29
+title: Rendering Statico vs Dinamico con i18n in Next.js
+description: Scopri come utilizzare il rendering statico vs dinamico con i18n in Next.js.
+keywords:
+  - statico
+  - dinamico
+  - rendering
+  - i18n
+  - next.js
+  - next-intl
+  - intlayer
+  - framework
+  - middleware
+  - configurazione
+slugs:
+  - doc
+  - faq
+  - rendering-statico
+---
+
+# Rendering Statico vs Dinamico con i18n in Next.js
+
+## Il problema con **next-intl**
+
+- **Cosa succede?**
+  Quando usi `useTranslations`, `getTranslations` o qualsiasi helper di next-intl _all'interno di un Componente Server_ in un'app con routing i18n (`/en/…`, `/fr/…`), Next.js marca l'intero percorso come **dinamico**. ([Next Intl][1])
+
+- **Perché?**
+  next-intl recupera la locale corrente da un header disponibile solo nella richiesta (`x-next-intl-locale`) tramite `headers()`. Poiché `headers()` è un'**API dinamica**, qualsiasi componente che la utilizza perde l'ottimizzazione statica. ([Next Intl][1], [Next.js][2])
+
+- **Soluzione ufficiale (boilerplate)**
+
+  1. Esporta `generateStaticParams` con ogni locale supportata.
+  2. Chiama `setRequestLocale(locale)` in **ogni** layout/pagina _prima_ di chiamare `useTranslations`. ([Next Intl][1])
+     Questo rimuove la dipendenza dall'header, ma ora hai codice extra da mantenere e un'API instabile in produzione.
+
+## Come **intlayer** evita il problema
+
+**Scelte di design**
+
+1. **Solo parametro di rotta** – La locale proviene dal segmento URL `[locale]` che Next.js passa già a ogni pagina.
+2. **Bundle a tempo di compilazione** – Le traduzioni sono importate come normali moduli ES, quindi vengono ottimizzate tramite tree-shaking e incorporate al momento della build.
+3. **Nessuna API dinamica** – `useT()` legge dal contesto React, non da `headers()` o `cookies()`.
+4. **Nessuna configurazione aggiuntiva** – Una volta che le tue pagine risiedono sotto `app/[locale]/`, Next.js prerenderizza automaticamente un file HTML per ogni locale.