# 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ì | `{}` | *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. ## 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.