@intlayer/docs 9.4.4 → 9.5.1

package/docs/it/intlayer_with_nextjs_compiler.md

@@ -1,838 +0,0 @@
----
-createdAt: 2026-01-10
-updatedAt: 2026-08-30
-title: "Next.js i18n - Guida completa per tradurre la tua applicazione"
-description: "Niente più i18next. La guida 2026 per creare un'applicazione Next.js multilingue (i18n). Traduci con agenti AI e ottimizza la dimensione del bundle, SEO e prestazioni."
-keywords:
-  - Internazionalizzazione
-  - Documentazione
-  - Intlayer
-  - Next.js
-  - JavaScript
-  - React
-  - Compilatore
-  - IA
-slugs:
-  - doc
-  - environment
-  - nextjs
-  - compiler
-applicationTemplate: https://github.com/aymericzip/intlayer-next-no-lolale-path-template
-youtubeVideo: https://www.youtube.com/watch?v=e_PPG7PTqGU
-history:
-  - version: 8.9.0
-    date: 2026-05-04
-    changes: "Aggiornare l'uso dell'API useIntlayer di Solid all'accesso diretto alle proprietà"
-  - version: 8.2.0
-    date: 2026-03-09
-    changes: "Update compiler options, add FilePathPattern support"
-  - version: 8.1.6
-    date: 2026-02-23
-    changes: "Rilascio iniziale"
-author: aymericzip
----
-
-# Come rendere multilingue (i18n) un'applicazione Next.js esistente (guida i18n 2026)
-
-<Tabs defaultTab="video">
-  <Tab label="Video" value="video">
-
-<iframe title="La migliore soluzione i18n per Next.js? Scopri Intlayer" class="m-auto aspect-16/9 w-full overflow-hidden rounded-lg border-0" allow="autoplay; gyroscope;" loading="lazy" width="1080" height="auto" src="https://www.youtube.com/embed/e_PPG7PTqGU?autoplay=0&amp;origin=https://intlayer.org&amp;controls=0&amp;rel=1"/>
-
-  </Tab>
-  <Tab label="Codice" value="code">
-
-<iframe
-  src="https://ide.intlayer.org/aymericzip/intlayer-next-16-no-locale-path-template?file=intlayer.config.ts"
-  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
-  title="Demo CodeSandbox - Come internazionalizzare la tua applicazione con Intlayer"
-  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
-  loading="lazy"
-/>
-
-  </Tab>
-</Tabs>
-
-Vedi il [Template dell'Applicazione](https://github.com/aymericzip/intlayer-next-no-lolale-path-template) su GitHub.
-
-## Sommario
-
-<TOC/>
-
-## Perché è difficile internazionalizzare un'applicazione esistente?
-
-Se hai mai provato ad aggiungere più lingue a un'app nata per una sola, conosci la fatica. Non è solo "difficile", è noioso. Devi passare al setaccio ogni file, scovare ogni stringa di testo e spostarla in file dizionario separati.
-
-Poi arriva la parte rischiosa: sostituire tutto quel testo con hook di codice senza rompere layout o logica. È il tipo di lavoro che blocca lo sviluppo di nuove funzionalità per settimane e sembra un refactoring infinito.
-
-## Cos'è l'Intlayer Compiler?
-
-L'**Intlayer Compiler** è stato creato per saltare questo lavoro manuale. Invece di costringerti a estrarre le stringhe a mano, il compilatore lo fa per te. Scansiona il codice, trova il testo e usa l'IA per generare i dizionari dietro le quinte.
-Quindi, modifica il codice durante la build per iniettare gli hook i18n necessari. In sostanza, continui a scrivere l'app come se fosse monolingua, e il compilatore gestisce automaticamente la trasformazione multilingue.
-
-> Doc Compilatore: [https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/compiler.md](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/compiler.md)
-
-### Limitazioni
-
-Dato che il compilatore esegue l'analisi e la trasformazione del codice (inserendo hook e generando dizionari) a **tempo di compilazione**, può **rallentare il processo di build** dell'applicazione.
-
-Per mitigare l'impatto durante lo sviluppo, puoi configurare il compilatore in modalità [`'build-only'`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/configuration.md) o disabilitarlo quando non necessario.
-
----
-
-## Guida passo dopo passo per configurare Intlayer in un'applicazione Next.js
-
-<Steps>
-
-<Step number={1} title="Installare le dipendenze">
-
-Installa i pacchetti necessari utilizzando npm:
-
-```bash packageManager="npm"
-npx intlayer init --interactive
-```
-
-```bash packageManager="pnpm"
-pnpm dlx intlayer init --interactive
-```
-
-```bash packageManager="yarn"
-yarn dlx intlayer init --interactive
-```
-
-```bash packageManager="bun"
-bunx intlayer init --interactive
-```
-
-> il flag `--interactive` è opzionale. Usa `intlayer-cli init` se sei un agente IA.
-
-> Questo comando rileverà il tuo ambiente e installerà i pacchetti richiesti. Ad esempio:
-
-```bash packageManager="npm"
-npm install intlayer next-intlayer
-npm install @intlayer/babel --save-dev
-```
-
-```bash packageManager="pnpm"
-pnpm add intlayer next-intlayer
-pnpm add @intlayer/babel --save-dev
-```
-
-```bash packageManager="yarn"
-yarn add intlayer next-intlayer
-yarn add @intlayer/babel --save-dev
-```
-
-```bash packageManager="bun"
-bun add intlayer next-intlayer
-bun add @intlayer/babel --dev
-```
-
-- **intlayer**
-
-  Il pacchetto core che fornisce strumenti di internazionalizzazione per gestione della configurazione, traduzione, [dichiarazione dei contenuti](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dictionary/content_file.md), transpilazione e [comandi CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/cli/index.md).
-
-- **next-intlayer**
-
-  Il pacchetto che integra Intlayer con Next.js. Fornisce context provider e hook per l'internazionalizzazione di Next.js. Include inoltre il plugin Next.js per integra web Intlayer con [Webpack](https://webpack.js.org/) o [Turbopack](https://nextjs.org/docs/app/api-reference/turbopack), oltre a un proxy per rilevare la lingua preferita dell'utente, gestire i cookie e i reindirizzamenti URL.
-
-</Step>
-
-<Step number={2} title="Configurare il progetto">
-
-Crea un file di configurazione per definire le lingue dell'applicazione:
-
-```typescript fileName="intlayer.config.ts"
-import { Locales, type IntlayerConfig } from "intlayer";
-
-const config: IntlayerConfig = {
-  internationalization: {
-    locales: [Locales.ENGLISH, Locales.ITALIAN],
-    defaultLocale: Locales.ITALIAN,
-  },
-  routing: {
-    mode: "search-params",
-  },
-  compiler: {
-    /**
-     * Indica se il compilatore deve essere abilitato.
-     */
-    enabled: true,
-
-    /**
-     * Directory di output per i dizionari ottimizzati.
-     */
-    output: ({ locale, key }) => `compiler/${locale}/${key}.json`,
-
-    /**
-     * Inserisci solo il contenuto nel file generato, senza chiave.
-     */
-    noMetadata: false,
-
-    /**
-     * Prefisso chiave dizionario
-     */
-    dictionaryKeyPrefix: "", // Remove base prefix
-
-    /**
-     * Indica se i componenti devono essere salvati dopo essere stati trasformati.
-     * In questo modo, il compilatore può essere eseguito una sola volta per trasformare l'app e poi rimosso.
-     */
-    saveComponents: false,
-  },
-  ai: {
-    provider: "openai",
-    model: "gpt-5-mini",
-    apiKey: process.env.OPEN_AI_API_KEY,
-    applicationContext: "Questa applicazione è un'app di mappe",
-  },
-};
-
-export default config;
-```
-
-> **Nota**: Assicurati di avere `OPEN_AI_API_KEY` impostata nelle variabili d'ambiente.
-
-> Tramite questo file, puoi configurare URL localizzati, reindirizzamenti proxy, nomi dei cookie, posizione ed estensione delle dichiarazioni di contenuto, disabilitare i log di Intlayer e altro. Per l'elenco completo dei parametri, consulta la [documentazione della configurazione](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/configuration.md).
-
-</Step>
-
-<Step number={3} title="Integrare Intlayer nella configurazione Next.js">
-
-Configura il setup Next.js per usare Intlayer:
-
-```typescript fileName="next.config.ts"
-import type { NextConfig } from "next";
-import { withIntlayer } from "next-intlayer/server";
-
-const nextConfig: NextConfig = {/* opzioni di configurazione qui */};
-
-export default withIntlayer(nextConfig);
-```
-
-> Il plugin `withIntlayer()` integra Intlayer con Next.js. Assicura la creazione dei file di dichiarazione dei contenuti e li monitora in modalità sviluppo. Definisce le variabili d'ambiente Intlayer negli ambienti [Webpack](https://webpack.js.org/) o [Turbopack](https://nextjs.org/docs/app/api-reference/turbopack). Inoltre, fornisce alias per ottimizzare le prestazioni e garantisce compatibilità con i Server Components.
-
-</Step>
-
-<Step number={4} title="Configurare Babel">
-
-L'Intlayer Compiler richiede Babel per estrarre e ottimizzare i contenuti. Aggiorna il file `babel.config.js` (o `babel.config.json`) per includere i plugin Intlayer:
-
-```typescript fileName="babel.config.js"
-const {
-  intlayerExtractBabelPlugin,
-  intlayerOptimizeBabelPlugin,
-  getExtractPluginOptions,
-  getOptimizePluginOptions,
-} = require("@intlayer/babel");
-
-module.exports = {
-  presets: ["next/babel"],
-  plugins: [
-    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
-    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
-  ],
-};
-```
-
-</Step>
-
-<Step number={5} title="Rilevare la lingua nelle pagine">
-
-Rimuovi tutto dal `RootLayout` e sostituiscilo con questo codice:
-
-```tsx fileName="src/app/layout.tsx"
-import type { Metadata } from "next";
-import type { ReactNode } from "react";
-import "./globals.css";
-import { IntlayerProvider, LocalPromiseParams } from "next-intlayer";
-import { getHTMLTextDir, getIntlayer } from "intlayer";
-import { getLocale } from "next-intlayer/server";
-export { generateStaticParams } from "next-intlayer";
-
-export const generateMetadata = async (): Promise<Metadata> => {
-  const locale = await getLocale();
-  const { title, description, keywords } = getIntlayer("metadata", locale);
-
-  return {
-    title,
-    description,
-    keywords,
-  };
-};
-
-const RootLayout = async ({
-  children,
-}: Readonly<{
-  children: ReactNode;
-}>) => {
-  const locale = await getLocale();
-
-  return (
-    <html lang={locale} dir={getHTMLTextDir(locale)}>
-      <body>
-        <IntlayerProvider defaultLocale={locale}>{children}</IntlayerProvider>
-      </body>
-    </html>
-  );
-};
-
-export default RootLayout;
-```
-
-</Step>
-
-<Step number={6} title="Compilare i componenti">
-
-Con il compilatore abilitato, **non devi più** dichiarare manualmente i dizionari (come i file `.content.ts`).
-
-Puoi scrivere i contenuti direttamente nel codice come stringhe. Intlayer analizzerà il codice, genererà le traduzioni usando l'IA e sostituirà le stringhe con i contenuti localizzati durante la compilazione.
-
-Scrivi i componenti con stringhe "hardcoded" nella lingua predefinita. Il compilatore farà il resto.
-
-Esempio di come apparirà la pagina:
-
-<Tabs>
-<Tab value="Code">
-
-```tsx fileName="src/app/page.tsx"
-import type { FC } from "react";
-import { IntlayerServerProvider } from "next-intlayer/server";
-import { getLocale } from "next-intlayer/server";
-
-const PageContent: FC = () => {
-  return (
-    <>
-      <p>Inizia a modificare</p>
-      <code>src/app/page.tsx</code>
-    </>
-  );
-};
-
-export default async function Page() {
-  const locale = await getLocale();
-
-  return (
-    <IntlayerServerProvider locale={locale}>
-      <PageContent />
-    </IntlayerServerProvider>
-  );
-}
-```
-
-</Tab>
-<Tab value="Output">
-
-```ts fileName="i18n/page-content.content.tsx"
-{
-  key: "page-content",
-  content: {
-    nodeType: "translation",
-    translation: {
-      en: {
-        getStartedByEditing: "Get started by editing",
-      },
-      fr: {
-        getStartedByEditing: "Commencez par éditer",
-      },
-      it: {
-        getStartedByEditing: "Inizia a modificare",
-      },
-    }
-  }
-}
-```
-
-</Tab>
-</Tabs>
-
-<Tabs>
-<Tab label='Intlayer >=9.4' value='>=9.4'>
-
-```tsx fileName="src/app/page.tsx"
-import { type FC } from "react";
-import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";
-import { getLocale } from "next-intlayer/server";
-
-const PageContent: FC = () => {
-  const content = useIntlayer("page-content");
-
-  return (
-    <>
-      <p>{content.getStartedByEditing}</p>
-      <code>src/app/page.tsx</code>
-    </>
-  );
-};
-
-export default async function Page() {
-  const locale = await getLocale();
-
-  return (
-    <IntlayerServerProvider locale={locale}>
-      <PageContent />
-    </IntlayerServerProvider>
-  );
-}
-```
-
-- **`IntlayerProvider`** viene montato una sola volta, nel layout radice. Fornisce la locale sia ai componenti server che client, quindi le pagine non si avvolgono più su se stesse.
-- Senza un segmento di percorso `[locale]`, la locale proviene sempre dalla richiesta — l'header `x-intlayer-locale` impostato dal proxy Intlayer, quindi il cookie della locale — che gli hook del server leggono autonomamente quando il provider non è stato eseguito.
-
-</Tab>
-<Tab label='Intlayer <9.4' value='<9.4'>
-
-```tsx fileName="src/app/page.tsx"
-import { type FC } from "react";
-import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";
-import { getLocale } from "next-intlayer/server";
-
-const PageContent: FC = () => {
-  const content = useIntlayer("page-content");
-
-  return (
-    <>
-      <p>{content.getStartedByEditing}</p>
-      <code>src/app/page.tsx</code>
-    </>
-  );
-};
-
-export default async function Page() {
-  const locale = await getLocale();
-
-  return (
-    <IntlayerServerProvider locale={locale}>
-      <PageContent />
-    </IntlayerServerProvider>
-  );
-}
-```
-
-- **`IntlayerClientProvider`** serve per fornire la lingua ai componenti client.
-- **`IntlayerServerProvider`** serve per fornire la lingua ai componenti server figli.
-
-  > Layout and page cannot share a common server context because the server context system is based on a per-request data store (via [React's cache](https://react.dev/reference/react/cache) mechanism), causing each "context" to be re-created for different segments of the application. Placing the provider in a shared layout would break this isolation, preventing the correct propagation of the server context values to your server components.
-
-</Tab>
-
-</Tabs>
-
-</Step>
-
-<Step number={7} title="Completare le traduzioni mancanti" isOptional={true}>
-
-Intlayer offre uno strumento CLI per completare le traduzioni mancanti. Usa il comando `intlayer` per testare e riempire le lacune nel codice.
-
-```bash packageManager="npm"
-npx intlayer test         # Verifica traduzioni mancanti
-```
-
-```bash packageManager="yarn"
-yarn intlayer test         # Verifica traduzioni mancanti
-```
-
-```bash packageManager="pnpm"
-pnpm intlayer test         # Verifica traduzioni mancanti
-```
-
-```bash packageManager="bun"
-bun x intlayer test         # Verifica traduzioni mancanti
-```
-
-```bash packageManager="npm"
-npx intlayer fill         # Completa traduzioni mancanti
-```
-
-```bash packageManager="yarn"
-yarn intlayer fill         # Completa traduzioni mancanti
-```
-
-```bash packageManager="pnpm"
-pnpm intlayer fill         # Completa traduzioni mancanti
-```
-
-```bash packageManager="bun"
-bun x intlayer fill         # Completa traduzioni mancanti
-```
-
-> Per maggiori dettagli, fare riferimento alla [documentazione CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/cli/ci.md)
-
-</Step>
-
-<Step number={8} title="Configurare il Proxy per il rilevamento lingua" isOptional={true}>
-
-Imposta un proxy per rilevare la lingua preferita dall'utente:
-
-```typescript fileName="src/proxy.ts"
-export { intlayerProxy as proxy } from "next-intlayer/proxy";
-
-export const config = {
-  matcher:
-    "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",
-};
-```
-
-> `intlayerProxy` rileva la lingua dell'utente e reindirizza all'URL corretto basandosi sulla [configurazione](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/configuration.md). Consente anche di salvare la preferenza in un cookie.
-
-> A partire da Intlayer v9, questo middleware rispetta l'opzione `routing.enableProxy` (`true` per impostazione predefinita). Imposta `routing.enableProxy: false` nella tua configurazione per trasformarlo in un pass-through senza rimuovere questo file. Vedi le [note di rilascio v9](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/releases/v9.md).
-
-</Step>
-
-<Step number={9} title="Cambiare la lingua del contenuto" isOptional={true}>
-
-Per cambiare lingua in Next.js, si consiglia di usare il componente `Link` per reindirizzare alla pagina localizzata. `Link` permette il prefetching, evitando il ricaricamento completo della pagina.
-
-```tsx fileName="src/components/localeSwitcher/LocaleSwitcher.tsx"
-"use client";
-
-import type { FC } from "react";
-import { Locales, getHTMLTextDir, getLocaleName } from "intlayer";
-import { useLocale } from "next-intlayer";
-
-export const LocaleSwitcher: FC = () => {
-  const { locale, availableLocales, setLocale } = useLocale();
-
-  return (
-    <div>
-      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>
-      <div id="localePopover" popover="auto">
-        {availableLocales.map((localeItem) => (
-          <button
-            key={localeItem}
-            aria-current={locale === localeItem ? "page" : undefined}
-            onClick={() => setLocale(localeItem)}
-          >
-            <span>
-              {/* Lingua - es. IT */}
-              {localeItem}
-            </span>
-            <span>
-              {/* Lingua nel proprio Locale - es. Italiano */}
-              {getLocaleName(localeItem, locale)}
-            </span>
-            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
-              {/* Lingua nel locale corrente - es. Francés se il locale è Locales.SPANISH */}
-              {getLocaleName(localeItem)}
-            </span>
-            <span dir="ltr" lang={Locales.ENGLISH}>
-              {/* Lingua in inglese - es. Italian */}
-              {getLocaleName(localeItem, Locales.ENGLISH)}
-            </span>
-          </button>
-        ))}
-      </div>
-    </div>
-  );
-};
-```
-
-> In alternativa, puoi usare `setLocale` dall'hook `useLocale`, ma non permetterà il prefetching. Consulta la [documentazione di `useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/packages/next-intlayer/useLocale.md).
-
-</Step>
-
-<Step number={10} title="Ottimizzare il bundle" isOptional={true}>
-
-Con `next-intlayer`, i dizionari sono inclusi di default in ogni pagina. Per ottimizzare il bundle, Intlayer offre un plugin SWC opzionale che sostituisce le chiamate `useIntlayer` con macro. Così i dizionari appaiono solo dove servono davvero.
-
-Il plugin `@intlayer/babel` integra già l'ottimizzazione del bundling (vedi `babel.config.js`). Ma il plugin `@intlayer/swc` è più performante. Se rimuovi il plugin `@intlayer/babel`, puoi utilizzare il plugin `@intlayer/swc`.
-
-Installa `@intlayer/swc`. `next-intlayer` lo rileverà e userà automaticamente:
-
-```bash packageManager="npm"
-npm install @intlayer/swc --save-dev
-```
-
-```bash packageManager="pnpm"
-pnpm add @intlayer/swc --save-dev
-```
-
-```bash packageManager="yarn"
-yarn add @intlayer/swc --save-dev
-```
-
-```bash packageManager="bun"
-bun add @intlayer/swc --dev
-```
-
-> Nota: Solo per Next.js 13+.
-
-> Nota: Non installato di default perché i plugin SWC in Next.js sono ancora sperimentali.
-
-> Nota: Se usi `importMode: 'dynamic'` o `'fetch'`, dovrai avvolgere le chiamate `useIntlayer` in un `Suspense`. Non potrai usarlo al livello superiore di Pagina / Layout.
-
-</Step>
-
-<Step number={11} title="Estrarre il contenuto dei tuoi componenti" isOptional={true}>
-
-Se hai una base di codice esistente, trasformare migliaia di file può richiedere molto tempo.
-
-Per facilitare questo processo, Intlayer propone un [compilatore](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/compiler.md) / [estrattore](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/cli/extract.md) per trasformare i tuoi componenti ed estrarre il contenuto.
-
-Per configurarlo, puoi aggiungere una sezione `compiler` nel tuo file `intlayer.config.ts`:
-
-```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
-import { type IntlayerConfig } from "intlayer";
-
-const config: IntlayerConfig = {
-  // ... Resto della tua configurazione
-  compiler: {
-    /**
-     * Indica se il compilatore deve essere abilitato.
-     */
-    enabled: true,
-
-    /**
-     * Definisce il percorso dei file di output
-     */
-    output: ({ fileName, extension }) => `./${fileName}${extension}`,
-
-    /**
-     * Indica se i componenti devono essere salvati dopo essere stati trasformati. In questo modo, il compilatore può essere eseguito solo una volta per trasformare l'app e poi rimosso.
-     */
-    saveComponents: false,
-
-    /**
-     * Prefisso chiave dizionario
-     */
-    dictionaryKeyPrefix: "",
-  },
-};
-
-export default config;
-```
-
-<Tabs>
-<Tab value='Extract command'>
-
-Esegui l'estrattore per trasformare i tuoi componenti ed estrarre il contenuto
-
-```bash packageManager="npm"
-npx intlayer extract
-```
-
-```bash packageManager="pnpm"
-pnpm intlayer extract
-```
-
-```bash packageManager="yarn"
-yarn intlayer extract
-```
-
-```bash packageManager="bun"
-bun x intlayer extract
-```
-
-</Tab>
-<Tab value='Babel compiler'>
-
-> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
-
-```bash packageManager="npm"
-npm install @intlayer/babel --save-dev
-```
-
-```bash packageManager="pnpm"
-pnpm add @intlayer/babel --save-dev
-```
-
-```bash packageManager="yarn"
-yarn add @intlayer/babel --save-dev
-```
-
-```bash packageManager="bun"
-bun add @intlayer/babel --dev
-```
-
-```js fileName="babel.config.js"
-const {
-  intlayerExtractBabelPlugin,
-  getExtractPluginOptions,
-} = require("@intlayer/babel");
-
-module.exports = {
-  presets: ["next/babel"],
-  plugins: [
-    // Estrai il contenuto dai componenti nei dizionari
-    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
-  ],
-};
-```
-
-```bash packageManager="npm"
-npm run build # Oppure npm run dev
-```
-
-```bash packageManager="pnpm"
-pnpm run build # O pnpm run dev
-```
-
-```bash packageManager="yarn"
-yarn build # O yarn dev
-```
-
-```bash packageManager="bun"
-bun run build # Or bun run dev
-```
-
-</Tab>
-</Tabs>
-</Step>
-
-</Steps>
-
-### Configurare TypeScript
-
-Intlayer usa la module augmentation per potenziare TypeScript.
-
-![Autocompletamento](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true)
-
-![Errore traduzione](https://github.com/aymericzip/intlayer/blob/main/docs/assets/translation_error.png?raw=true)
-
-Assicurati che `tsconfig.json` includa i tipi generati.
-
-```json5 fileName="tsconfig.json"
-{
-  // ... Config TS esistenti
-  "include": [
-    // ... Config TS esistenti
-    ".intlayer/**/*.ts", // Includi i tipi autogenerati
-  ],
-}
-```
-
-### Configurazione Git
-
-Ignora i file generati da Intlayer per evitare di includerli nel repository.
-
-Nel file `.gitignore`:
-
-```plaintext fileName=".gitignore"
-# Ignora i file generati da Intlayer
-.intlayer
-```
-
-### Estensione VS Code
-
-Per una migliore esperienza, installa l'**Estensione ufficiale Intlayer per VS Code**.
-
-[Installa dal Marketplace](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
-
-Caratteristiche:
-
-- **Autocompletamento** chiavi.
-- **Rilevamento errori** in tempo reale.
-- **Anteprime inline**.
-- **Azioni rapide** per creare/aggiornare traduzioni.
-
-Consulta la [documentazione dell'estensione](https://intlayer.org/doc/vs-code-extension) per i dettagli.
-
-### Vai oltre
-
-Puoi implementare l' [editor visuale](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/intlayer_visual_editor.md) o esternalizzare i contenuti col [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/intlayer_CMS.md).
-
-## Domande frequenti
-
-<FAQ>
-
-<Question title="Quali sono le diverse soluzioni disponibili per internazionalizzare un'app Next.js?">
-
-Il campo `i18n` di `next.config.js` non si applica all'App Router, quindi il livello di localizzazione è sempre una scelta di libreria:
-
-- **`next-intl`**, **`next-i18next` / `i18next`** e **`react-intl`**: cataloghi JSON o ICU caricati per namespace, con chiavi scritte a mano in ogni punto di chiamata.
-- **`Lingui`**: guidata dall'estrazione, con messaggi ICU compilati in fase di build.
-- **`Intlayer`**: contenuto compilato dai tuoi componenti in fase di build, completamente tipizzato, con traduzione AI, un editor visivo e un CMS.
-
-Questa guida usa la configurazione con il compilatore, dove continui a scrivere stringhe semplici nei tuoi componenti e i dizionari sono generati per te. Vedi [perché Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/interest_of_intlayer.md) e il [benchmark i18n di Next.js](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/benchmark/nextjs.md).
-
-</Question>
-
-<Question title="Quanto aggiunge l'i18n alla dimensione del mio bundle Next.js?">
-
-Molto meno di una configurazione basata su namespace, perché una pagina non scarica mai un catalogo che non renderizza. I Server Component risolvono il loro contenuto sul server, e il compilatore in fase di build sostituisce le chiamate `useIntlayer` con le esatte voci del dizionario che un componente utilizza, quindi le chiavi e le lingue non utilizzate vengono eliminate, e i [dizionari dinamici](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dynamic_dictionaries/index.md) suddividono il resto per locale. Misurato rispetto alle alternative abituali, Intlayer riduce la dimensione del bundle e delle pagine fino al 50%. Vedi [ottimizzazione del bundle](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/bundle_optimization.md) e il [benchmark](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/benchmark/nextjs.md).
-
-</Question>
-
-<Question title="Posso migrare da `next-intl`, `next-i18next` o `i18next` senza riscrivere i miei componenti?">
-
-Sì, e ci sono due percorsi. Puoi migrare il contenuto progressivamente con la [guida alla migrazione da next-intl](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/migration_from_next-intl_to_intlayer.md) o la [guida alla migrazione da i18next](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/migration_from_i18next_to_intlayer.md). Oppure puoi mantenere interamente la tua API attuale: gli [adattatori di compatibilità](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/compat/index.md) espongono esattamente la stessa API di `next-intl`, `react-i18next` e `react-intl`, ma servita dai dizionari Intlayer, quindi cambiano gli import e il codice dei componenti no.
-
-</Question>
-
-<Question title="Posso mantenere i miei file di traduzione JSON esistenti?">
-
-Sì. Il [plugin di sincronizzazione JSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/plugins/sync-json.md) mantiene i tuoi file `/messages/{locale}/{namespace}.json` come fonte di verità e genera dizionari Intlayer da essi, in entrambe le direzioni. Un [plugin di sincronizzazione PO](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/plugins/sync-po.md) fa lo stesso per i cataloghi gettext, e i [file per locale](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/per_locale_file.md) ti permettono di dividere il contenuto per lingua invece di raggruppare i locale in un unico file.
-
-</Question>
-
-<Question title="Devo spostare il mio contenuto chiave per chiave?">
-
-No, ed è ciò che questa guida configura. Scrivi i tuoi componenti con stringhe semplici nella tua locale predefinita, e il [Compilatore Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/compiler.md) analizza il sorgente ad ogni build, estrae il testo visibile all'utente e genera i dizionari, così non ci sono chiavi da creare o mantenere a mano.
-
-Due limiti vale la pena conoscere. Il compilatore funziona per analisi statica, quindi le stringhe che esistono solo a runtime, come i codici di errore delle API o i campi del CMS, restano fuori portata e hanno comunque bisogno di un dizionario dichiarato. E deve distinguere il testo visibile all'utente dalla logica applicativa come `className="active"` o un codice di stato, il che richiede alcune annotazioni in una codebase estesa.
-
-Se preferisci mantenere il controllo, `npx intlayer extract` esegue la stessa estrazione una volta, sui file che scegli, e scrive un file `.content` accanto a ciascun componente perché tu lo riveda. Vedi il [comando extract](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/cli/extract.md).
-
-</Question>
-
-<Question title="Quali strumenti di editor e agenti AI sono disponibili?">
-
-Cinque componenti, tutti opzionali:
-
-- **[Estensione VS Code](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/vs_code_extension.md)**: salta da una chiave `useIntlayer` al file di contenuto che la dichiara, estrai il contenuto da un componente ed esegui build, fill, test, push e pull dalla palette dei comandi o da una scheda Intlayer dedicata.
-- **[Server LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/lsp.md)**: la stessa consapevolezza in qualsiasi editor che parla LSP, con vai alla definizione, trova tutti i riferimenti, anteprime al passaggio del mouse di un valore tradotto, autocompletamento di chiavi e campi, e un avviso quando una chiave non è dichiarata da nessuna parte. Risolve anche le chiamate `i18next`, `react-i18next`, `next-intl` e `use-intl`, il che aiuta durante la migrazione.
-- **[Server MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/mcp_server.md)**: espone la documentazione di Intlayer e la CLI a Cursor, VS Code, Claude Desktop, Claude Code e ChatGPT, così un assistente risponde in base alla documentazione aggiornata invece di tirare a indovinare, e può eseguire da solo comandi come `intlayer fill`.
-- **[Agent skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/agent_skills.md)**: competenze mirate come `intlayer-config`, `intlayer-cli` e `intlayer-content`, più una per framework, che insegnano a un agente la tua configurazione di routing e i tipi di nodo dei contenuti.
-- **[Plugin ESLint](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/eslint.md)**: `no-raw-text` segnala le stringhe hardcoded, con ulteriori regole per le chiavi statiche dei dizionari e i contenuti non utilizzati.
-
-</Question>
-
-<Question title="Dovrei usare il compilatore o dichiarare il mio contenuto io stesso?">
-
-Usa il compilatore quando vuoi aggiungere l'i18n a una codebase esistente con il minimo di cambiamenti: i tuoi componenti restano come sono e i dizionari seguono. Dichiara il contenuto tu stesso, come mostra la [guida Next.js standard](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/intlayer_with_nextjs_16.md), quando vuoi un controllo esplicito su chiavi, struttura e riuso. I due possono coesistere nello stesso livello di dizionari.
-
-</Question>
-
-<Question title="Perché devo configurare Babel?">
-
-Lo copre il passo 4. Il compilatore legge i tuoi componenti attraverso una trasformazione Babel, quindi Next.js ha bisogno di un `babel.config.js` perché il passaggio di estrazione venga eseguito. `npx intlayer init --interactive` lo genera per te quando scegli la configurazione con il compilatore.
-
-</Question>
-
-<Question title="Cosa succede alle stringhe che il compilatore non riesce a vedere?">
-
-Restano non tradotte, perché il compilatore funziona per analisi statica. Qualsiasi cosa assemblata a runtime, come un messaggio di errore di un'API, un campo del CMS o una stringa costruita per concatenazione, deve essere dichiarata in un file di contenuto nel modo normale. Esegui `npx intlayer test` per trovare ciò che manca.
-
-</Question>
-
-<Question title="Come riempio le traduzioni mancanti?">
-
-Lo copre il passo 7. `npx intlayer fill` invia il contenuto estratto all'LLM di tua scelta, usando il tuo provider e la tua API key, e `--git-diff` limita l'esecuzione a ciò che è cambiato nel branch. Vedi il [comando fill](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/cli/fill.md) e l'[integrazione CI/CD](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/CI_CD.md).
-
-</Question>
-
-<Question title="Come viene rilevata la locale?">
-
-Il passo 5 la legge nelle tue pagine e il passo 8 aggiunge il proxy che la risolve dall'URL, un cookie o l'header `Accept-Language`. `routing.mode` decide se la locale appare del tutto nel percorso. Vedi il [riferimento di configurazione](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/configuration.md).
-
-</Question>
-
-<Question title="Intlayer supporta plurali, genere e rich text?">
-
-Sì: [forme plurali](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dictionary/plurial.md), [contenuto basato sul genere](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dictionary/gender.md), condizioni, [inserimenti](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dictionary/insertion.md), [Markdown](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/dictionary/markdown.md) e [formattatori](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/formatters.md) per numeri, date e valute.
-
-</Question>
-
-<Question title="Come possono i traduttori modificare il contenuto senza toccare il codice?">
-
-Attraverso l'[editor visivo](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/intlayer_visual_editor.md), che gira sulla tua infrastruttura e permette a chiunque di modificare il testo sul posto nell'app in esecuzione, o il [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/intlayer_CMS.md), che esternalizza il contenuto così può cambiare senza un deployment.
-
-</Question>
-
-<Question title="Intlayer è gratuito e open source?">
-
-Sì, sotto licenza Apache 2.0, uso commerciale incluso. Il CMS ospitato è un servizio a pagamento opzionale che può anche essere [auto-ospitato](https://github.com/aymericzip/intlayer/blob/main/docs/docs/it/self_hosting.md).
-
-</Question>
-
-</FAQ>