# gt-next: General Translation Next.js SDK: Middleware
URL: https://generaltranslation.com/it/docs/next/guides/middleware.mdx
---
title: Middleware
description: Rilevamento automatico della lingua e routing degli URL in base alle preferenze dell'utente
---

Middleware rileva automaticamente le preferenze linguistiche dell'utente e lo reindirizza alla versione localizzata più adatta del tuo sito.
Usa le impostazioni del browser, la geolocalizzazione e le preferenze dell'utente per servire la lingua corretta prima del caricamento di qualsiasi contenuto.

<Callout>
  **Percorso del file:** Posiziona `proxy.ts` nella radice del progetto, allo stesso livello della directory `app/`, non al suo interno. `proxy.ts` (Next.js 16+) o `middleware.ts` (Next.js 15 e versioni precedenti)
</Callout>

## Setup

### Passaggio 1: Crea una route dinamica

Crea una directory `[locale]` nella cartella `app/` e sposta al suo interno tutte le pagine:

<Files>
  <Folder name="my-app" defaultOpen={true}>
    <File name="proxy.ts" />

    <Folder name="app" defaultOpen={true}>
      <Folder name="[locale]" defaultOpen={true}>
        <File name="layout.tsx" />

        <File name="page.tsx" />

        <Folder name="about">
          <File name="page.tsx" />
        </Folder>
      </Folder>

      <Folder name="api">
        <File name="route.ts" />
      </Folder>
    </Folder>

    <File name="next.config.js" />
  </Folder>
</Files>

### Passaggio 2: Aggiungi il middleware

Crea `proxy.ts` nella radice del progetto:

```ts
import { createNextMiddleware } from 'gt-next/middleware';

export default createNextMiddleware();

export const config = {
  // Corrisponde a tutti i percorsi eccetto le route API, i file statici e gli elementi interni di Next.js
  matcher: ['/((?!api|static|.*\\..*|_next).*)']
};
```

Questo consente il rilevamento automatico della lingua e il routing degli URL con prefissi di impostazione regionale come `/en/about`, `/es/about`.


## Rilevamento della lingua

Il middleware rileva le preferenze linguistiche dell&#39;utente nel seguente ordine:

1. **Impostazione regionale nell&#39;URL** - `/es/about` → spagnolo
2. **Cookie dell&#39;utente** - Selezione della lingua precedente
3. **Intestazioni del browser** - Header `Accept-Language`
4. **Impostazione regionale predefinita** - Lingua di fallback configurata

Il middleware gestisce automaticamente il rilevamento della lingua del browser e la memorizzazione dei cookie senza configurazioni aggiuntive.

## Percorsi URL localizzati

Personalizza i percorsi URL per le diverse lingue:

```ts
export default createNextMiddleware({
  pathConfig: {
    // Inglese: /en/products, Cinese: /zh/产品
    "/products": {
      "zh": "/产品"
    },
    
    // Route dinamiche: /en/product/123, /zh/产品/123
    "/product/[id]": {
      "zh": "/产品/[id]"
    }
  }
});
```


## Struttura dell&#39;URL

Per impostazione predefinita, alla tua impostazione regionale predefinita **non** viene anteposto un codice locale:

```
/about     → /about        (impostazione regionale predefinita: English)
/about     → /es/about     (Spanish)
/about     → /fr/about     (French)
```


### Aggiungi un prefisso all&#39;impostazione regionale predefinita

Per aggiungere un prefisso a tutte le impostazioni regionali, compresa quella predefinita:

```ts
export default createNextMiddleware({
  prefixDefaultLocale: true
});
```

Risultato:

```
/about     → /en/about     (English, with prefix)
/about     → /es/about     (Spanish, with prefix)
/about     → /fr/about     (French, with prefix)
```


## Problemi comuni

### Route dinamica mancante

Tutte le pagine devono trovarsi all&#39;interno di `[locale]/`:

```
❌ Wrong:
app/
├── page.tsx
└── about/page.tsx

✅ Correct:
app/
└── [locale]/
    ├── page.tsx
    └── about/page.tsx
```


### Configurazione del matcher

Escludi le route API e i file statici:

```ts
export const config = {
  matcher: ['/((?!api|static|.*\\..*|_next).*)']
};
```

<Callout>
  Verifica attentamente la configurazione del middleware: matcher errati possono causare reindirizzamenti infiniti o compromettere le risorse statiche.
</Callout>


## Passaggi successivi

<Callout>
  **Guardalo in azione:** L&#39;[app di esempio di Static Site Generation](https://github.com/gt-examples/static-site-generation) include un setup completo del middleware con routing basato sull&#39;impostazione regionale — [anteprima live](https://static-site-generation.generaltranslation.dev).
</Callout>

* [Guida SSG](/docs/next/guides/ssg) - Generazione statica con routing basato sull&#39;impostazione regionale
* [Supporto RTL](/docs/next/guides/rtl) - Lingue da destra a sinistra
* Riferimenti API: