# General Translation React SDKs (gt-react, gt-next, gt-react-native): createNextMiddleware URL: https://generaltranslation.com/it/docs/react/nextjs/reference/functions/create-next-middleware.mdx Docs index: https://generaltranslation.com/llms.txt Description: Aggiungi il routing e il rilevamento delle impostazioni regionali a un'app Next.js con General Translation. Riferimento API per createNextMiddleware. La funzione `createNextMiddleware` di `gt-next/middleware` rileva l'impostazione regionale di ogni visitatore, la memorizza in un cookie e lo reindirizza alla versione localizzata di una pagina. Per la configurazione attuale, usa la [guida al middleware di App Router](/docs/react/nextjs/app-router-middleware). Le app Pages Router usano invece il [routing internazionalizzato di Next.js](/docs/react/nextjs/pages-router-middleware). *Il middleware è facoltativo se non ti serve il rilevamento delle impostazioni regionali in fase di richiesta né URL con prefisso dell'impostazione regionale. Senza di esso, i selettori delle impostazioni regionali mantengono gli URL privi di prefisso, memorizzano l'impostazione regionale selezionata in un cookie e aggiornano il contenuto di App Router.* ## Panoramica [#overview] Crea il middleware ed esportalo, insieme a un path matcher, dal file `middleware`. Inseriscilo nella radice del progetto — `proxy.ts` in Next.js 16+, oppure `middleware.ts` in Next.js 15 e versioni precedenti — non all'interno di `app/` o `pages/`. ```ts title="proxy.ts" import { createNextMiddleware } from 'gt-next/middleware'; export default createNextMiddleware(); export const config = { // Corrisponde a tutti i percorsi eccetto le API route, i file statici e i componenti interni di Next.js matcher: ['/((?!api|static|.*\\..*|_next).*)'], }; ``` ## Come funziona [#how-it-works] Il middleware determina l'impostazione regionale di ogni richiesta a partire da queste fonti, in questo ordine: 1. **Reimposta cookie dell'impostazione regionale** — l'impostazione regionale appena selezionata nel browser, mentre è in attesa una reimpostazione del routing delle impostazioni regionali. 2. **Impostazione regionale nell'URL** — un prefisso dell'impostazione regionale supportata, ad esempio `/es/about`, oppure un percorso dell'impostazione regionale predefinita configurato senza prefisso. 3. **Cookie dell'impostazione regionale** — l'impostazione regionale selezionata in precedenza dal visitatore quando non è in attesa alcuna reimpostazione. 4. **Cookie dell'impostazione regionale del referrer** — l'impostazione regionale del precedente percorso client quando non è in attesa alcuna reimpostazione. 5. **Header del browser** — l'header `Accept-Language`, a meno che [`ignoreBrowserLocales`](/docs/react/nextjs/config#ignore-browser-locales) non sia abilitato. 6. **Impostazione regionale predefinita** — il `defaultLocale` configurato come fallback. Quindi imposta un cookie per l'impostazione regionale e, quando `localeRouting` è abilitato, reindirizza o riscrive il percorso localizzato corretto. Per impostazione predefinita, `defaultLocale` non ha prefisso (`/about` rimane `/about`), mentre le altre impostazioni regionali sì (`/es/about`). I codici locale vengono standardizzati nella forma canonica quando i servizi General Translation sono abilitati e le impostazioni regionali configurate non supportate generano un avviso in fase di build. ## Opzioni [#options] `createNextMiddleware` accetta un unico oggetto options. Tutti i campi sono facoltativi. | Opzione | Descrizione | Tipo | Facoltativo | Predefinito | | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------- | ----------- | ----------- | | [`localeRouting`](#locale-routing) | Abilita il routing basato sulle impostazioni regionali. | `boolean` | Sì | `true` | | [`prefixDefaultLocale`](#prefix-default-locale) | Aggiunge un prefisso anche all'impostazione regionale predefinita nell'URL. | `boolean` | Sì | `false` | | [`ignoreSourceMaps`](#ignore-source-maps) | Ignora le richieste di source map di Next.js. | `boolean` | Sì | `true` | | [`pathConfig`](#path-config) | Alias localizzati dei percorsi. | `object` | Sì | `{}` | | [`routeOverrides`](#route-overrides) | Usa un'implementazione di pagina specifica per un'impostazione regionale senza modificarne l'URL pubblico. | `RouteOverrides` | Sì | `{}` | | [`localeRoutes`](#locale-routes) | Limita i percorsi condivisi disponibili in ciascuna impostazione regionale. | `LocaleRoutes` | Sì | `{}` | *Nota: per limitare i pathname su cui il middleware viene eseguito, imposta [`pathRegex`](/docs/react/nextjs/config#path-regex) in `withGTConfig` — non è un'opzione del middleware. Il `matcher` nel `config` esportato è ciò che Next.js usa per decidere se il middleware debba essere eseguito o meno.* ### `localeRouting` [#locale-routing] **Tipo** `boolean` · **Facoltativo** · **Predefinito** `true` Abilita il routing basato sulle impostazioni regionali e i reindirizzamenti. Quando è `false`, il middleware continua a rilevare e memorizzare l'impostazione regionale, ma non aggiunge prefissi dell'impostazione regionale né riscrive i percorsi. ### `prefixDefaultLocale` [#prefix-default-locale] **Tipo** `boolean` · **Facoltativo** · **Predefinito** `false` Quando è `false` (impostazione predefinita), l'impostazione regionale predefinita viene servita senza prefisso (`/about`), mentre le altre impostazioni regionali sono precedute da un prefisso (`/es/about`). Quando è `true`, tutte le impostazioni regionali sono precedute da un prefisso, inclusa quella predefinita (`/en/about`). ### `ignoreSourceMaps` [#ignore-source-maps] **Type** `boolean` · **Facoltativo** · **Predefinito** `true` Quando è `true`, le richieste delle source map di Next.js vengono inoltrate inalterate. ### `pathConfig` [#path-config] **Tipo** `object` · **Facoltativo** · **Predefinito** `{}` Associa i percorsi condivisi ai percorsi localizzati, così una route può avere un URL diverso per ogni impostazione regionale. Ogni chiave è il percorso condiviso; ogni valore è un singolo percorso localizzato oppure una mappa per impostazione regionale. ```ts title="proxy.ts" export default createNextMiddleware({ pathConfig: { // Inglese: /products, Francese: /fr/produits '/products': { fr: '/produits', }, // Dinamico: /product/123, /fr/produit/123 '/product/[id]': { fr: '/produit/[id]', }, // Catch-all obbligatorio: /blog/2026/launch, /fr/articles/2026/launch '/blog/[...slug]': { fr: '/articles/[...slug]', }, // Catch-all facoltativo: /news o /news/latest, /fr/actualites o /fr/actualites/latest '/news/[[...slug]]': { fr: '/actualites/[[...slug]]', }, }, }); ``` ### `routeOverrides` [#route-overrides] **Type** `RouteOverrides` · **Optional** · **Default** `{}` Associa un'impostazione regionale ai pattern di route condivise che dispongono di un'implementazione di pagina specifica per quell'impostazione regionale. L'URL pubblico continua a usare la route condivisa o il suo alias [`pathConfig`](#path-config), mentre il middleware riscrive la richiesta verso una route con un secondo segmento statico di impostazione regionale. Ad esempio, questa struttura di file offre ai visitatori francesi implementazioni personalizzate di una pagina statica, di una pagina prodotto dinamica e di un insieme di pagine del blog: Configura ogni override con il relativo pattern di route condivisa: ```ts title="proxy.ts" export default createNextMiddleware({ routeOverrides: { fr: [ '/home', // Route statica '/product/[id]', // Parametro dinamico '/blog/[[...slug]]', // Route e tutti i percorsi figli ], }, }); ``` * `/home` usa `app/[locale]/fr/home/page.tsx` per il francese e la pagina condivisa `app/[locale]/home/page.tsx` per le altre impostazioni regionali. * `/product/[id]` aggiunge una pagina di prodotto solo per il francese, preservando l'`id` dinamico. * `/blog/[[...slug]]` aggiunge un'intera famiglia di pagine blog solo per il francese, ovvero `/blog`, `/blog/authors`, `/blog/posts` e `/blog/posts/[...slug]`. Gli overrides vengono ignorati quando `localeRouting` è `false`. Le chiavi delle impostazioni regionali vengono standardizzate quando i servizi General Translation sono attivi. Le API di cache e di layout vedono la route interna. Passa a `revalidatePath` di Next.js la destinazione del rewrite, ad esempio `/fr/fr/home`. Dal layout `[locale]`, `useSelectedLayoutSegments` include anche il segmento statico dell'impostazione regionale definito dall'override. Per la navigazione interna usa [``](/docs/react/nextjs/link) di `gt-next/link`: in questo modo le route con prefisso dell'impostazione regionale vengono generate prima della navigazione, senza un ulteriore reindirizzamento del middleware. ### `localeRoutes` [#locale-routes] **tipo** `LocaleRoutes` · **Optional** · **Default** `{}` ```ts type LocaleRoutes = Record; ``` Elenca i percorsi condivisi disponibili per ciascuna impostazione regionale. Ogni chiave è un'impostazione regionale e il relativo valore è un array di pattern di route condivisi. Le impostazioni regionali omesse da questa opzione possono servire tutte le route. Un array vuoto impedisce a un'impostazione regionale di servire qualsiasi route. ```ts title="proxy.ts" export default createNextMiddleware({ pathConfig: { '/pricing': { 'en-GB': '/prices', }, }, routeOverrides: { 'en-GB': ['/pricing'], }, localeRoutes: { 'en-GB': ['/pricing', '/blog/[[...slug]]'], fr: [], }, }); ``` In questo esempio, i visitatori che usano `en-GB` possono visualizzare la pagina dei prezzi e il blog, comprese le relative route figlie. `/en-GB/prices` continua a usare l'alias localizzato definito in `pathConfig` e l'implementazione della pagina specifica per impostazione regionale definita in `routeOverrides`. I visitatori che usano il francese ricadono sull'impostazione regionale predefinita per ogni route, mentre le impostazioni regionali non elencate in `localeRoutes` restano senza restrizioni. `localeRoutes` usa sempre percorsi condivisi, non alias localizzati. Ne controlla soltanto la disponibilità a livello di routing: non verifica se il contenuto esiste nel tuo CMS o in un'altra sorgente di dati. Quando una route richiesta non è disponibile, il middleware reindirizza all'URL pubblico corrispondente dell'impostazione regionale predefinita, preservando gli alias configurati, gli override delle route, i parametri di route, le query string, i percorsi di base e lo stile della barra finale. L'impostazione regionale predefinita è il fallback finale e, se la pagina corrispondente manca, entra in gioco la normale gestione del 404 di Next.js della tua applicazione. ## Esempio [#example] ```ts title="proxy.ts" import { createNextMiddleware } from 'gt-next/middleware'; export default createNextMiddleware({ prefixDefaultLocale: true, pathConfig: { '/about': { fr: '/a-propos', }, }, }); export const config = { matcher: ['/((?!api|static|.*\\..*|_next).*)'], }; ``` *Avviso: verifica attentamente il tuo matcher. Un matcher troppo generico può causare loop di reindirizzamento o compromettere le risorse statiche.* ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.