# gt-next: General Translation Next.js SDK: Alias delle impostazioni regionali e SEO
URL: https://generaltranslation.com/it/docs/next/guides/locale-aliases.mdx
---
title: Alias delle impostazioni regionali e SEO
description: Usa alias personalizzati per le impostazioni regionali nel routing degli URL, mantenendo la conformità a BCP 47 per i motori di ricerca
---
Gli alias delle impostazioni regionali ti permettono di usare codici locale personalizzati negli URL (ad esempio `/cn/` invece di `/zh/`), mantenendo i metadati SEO conformi allo [standard BCP 47](https://www.w3.org/International/articles/language-tags/) richiesto dai motori di ricerca.
## Perché gli alias?
I codici locale BCP 47 come `zh` (cinese) o `zh-Hant` (cinese tradizionale) sono lo standard per identificare le lingue sul web.
Tuttavia, potresti voler usare codici diversi nei percorsi URL per motivi di branding, leggibilità o regionali — ad esempio, usare `/cn/` invece di `/zh/` per il pubblico cinese.
GT supporta questo tramite la **mappatura personalizzata** nel tuo `gt.config.json`. L'alias viene usato per il routing e i percorsi URL, mentre il codice BCP 47 canonico viene usato ovunque sia necessario ai motori di ricerca.
**Requisito SEO:** I motori di ricerca riconoscono solo i [codici locale BCP 47](https://www.w3.org/International/articles/language-tags/).
L'uso di codici non standard come `cn` negli attributi `hreflang` o in `` farà sì che i motori di ricerca ignorino i segnali della tua impostazione regionale.
## Setup
### Passaggio 1: Configura la mappatura personalizzata
Aggiungi una voce `customMapping` nel tuo `gt.config.json` per ogni alias:
```json title="gt.config.json"
{
"defaultLocale": "en-US",
"locales": ["en-US", "cn", "ja", "zh-Hant"],
"customMapping": {
"cn": {
"code": "zh",
"name": "Mandarin"
}
}
}
```
Qui, `cn` è l'alias usato negli URL e nel middleware routing, mentre `zh` è il codice BCP 47 canonico.
### Passaggio 2: usa il middleware normalmente
Il [middleware](/docs/next/guides/middleware) e la route dinamica `[locale]` funzionano subito con i tuoi codici alias. Gli utenti che visitano `/cn/about` vedranno contenuti in cinese, senza bisogno di alcuna gestione speciale del routing.
## Conformità a BCP 47 per la SEO
Sebbene gli alias funzionino senza problemi per il routing, ci sono tre casi in cui **devi** usare il codice BCP 47 canonico invece dell'alias:
1. L'attributo `lang` del tag ``
2. I tag `link` alternativi nei metadati della pagina
3. Le voci alternative nella sitemap
GT fornisce il metodo `resolveCanonicalLocale()` per riconvertire gli alias nei codici BCP 47. Puoi accedervi tramite `getGTClass` da `gt-next/server`:
```ts
import { getGTClass } from 'gt-next/server';
const gtInstance = getGTClass();
const canonicalLocale = gtInstance.resolveCanonicalLocale('cn');
// Restituisce: "zh"
```
Per le impostazioni regionali senza alias, `resolveCanonicalLocale()` restituisce l'input invariato:
```ts
gtInstance.resolveCanonicalLocale('ja'); // "ja"
gtInstance.resolveCanonicalLocale('en-US'); // "en-US"
```
### 1. Attributo HTML `lang`
L'attributo `` indica ai browser e ai motori di ricerca qual è la lingua della pagina. Deve essere un codice BCP 47 valido.
Nel tuo layout radice, determina l'impostazione regionale prima di passarla al tag ``:
```tsx title="app/[locale]/layout.tsx"
import { getGTClass } from 'gt-next/server';
export default function RootLayout({
children,
params,
}: {
children: React.ReactNode;
params: { locale: string };
}) {
const gtInstance = getGTClass();
const canonicalLocale = gtInstance.resolveCanonicalLocale(params.locale);
return (
{children}
);
}
```
Senza questo, una pagina su `/cn/about` eseguirebbe erroneamente il rendering di ``, che i motori di ricerca non riconoscono.
### 2. Metadati alternativi
I link alternativi indicano ai motori di ricerca quali versioni di una pagina sono disponibili in altre lingue. L'attributo `hreflang` deve utilizzare codici BCP 47.
```tsx title="app/[locale]/layout.tsx"
import type { Metadata } from 'next';
import { getGTClass } from 'gt-next/server';
export async function generateMetadata({
params,
}: {
params: { locale: string };
}): Promise {
const gtInstance = getGTClass();
const locales = ['en-US', 'cn', 'ja', 'zh-Hant'];
// Costruisce gli alternates con i codici BCP 47 canonici come chiavi
const languages: Record = {};
for (const locale of locales) {
const canonical = gtInstance.resolveCanonicalLocale(locale);
languages[canonical] = `https://example.com/${locale}`;
}
// Aggiunge x-default per l'impostazione regionale predefinita
languages['x-default'] = 'https://example.com';
return {
alternates: {
canonical: `https://example.com/${params.locale}`,
languages,
},
};
}
```
Questo genera i tag `` corretti nell'head della pagina:
```html
```
Nota che i valori di `hreflang` usano codici canonici (`zh`, non `cn`), mentre gli URL `href` usano ancora i percorsi alias (`/cn/`).
### 3. Alternative della sitemap
Se usi una [sitemap dinamica](https://nextjs.org/docs/app/api-reference/file-conventions/metadata/sitemap), applica lo stesso pattern:
```ts title="app/sitemap.ts"
import type { MetadataRoute } from 'next';
import { getGTClass } from 'gt-next/server';
export default function sitemap(): MetadataRoute.Sitemap {
const gtInstance = getGTClass();
const locales = ['en-US', 'cn', 'ja', 'zh-Hant'];
const baseUrl = 'https://example.com';
const pages = ['', '/about', '/pricing'];
return pages.map((page) => {
// Costruisce le alternative linguistiche con codici canonici
const languages: Record = {};
for (const locale of locales) {
const canonical = gtInstance.resolveCanonicalLocale(locale);
languages[canonical] = `${baseUrl}/${locale}${page}`;
}
return {
url: `${baseUrl}${page}`,
lastModified: new Date(),
alternates: {
languages,
},
};
});
}
```
Questo genera una sitemap XML con gli attributi `hreflang` corretti:
```xml
https://example.com
```
## Errori comuni
| Errore | Impatto | Soluzione |
| ----------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Uso di un codice alias in `` | I motori di ricerca non riescono a identificare la lingua della pagina | Usa `resolveCanonicalLocale()` per l'attributo `lang` |
| Uso di un codice alias in `hreflang` | I motori di ricerca ignorano il link alternativo | Usa `resolveCanonicalLocale()` per i valori di `hreflang` |
| Alternativa `x-default` mancante | Nessun fallback per gli utenti la cui lingua non è indicata | Aggiungi `x-default` che punti all'URL della tua impostazione regionale predefinita |
| Alternative incoerenti tra HTML e sitemap | I segnali contrastanti confondono i crawler | Usa `resolveCanonicalLocale()` in entrambi i casi |
## Passaggi successivi
* Scopri [middleware](/docs/next/guides/middleware) per il routing degli URL basato sull'impostazione regionale
* Consulta il riferimento API di [`resolveCanonicalLocale`](/docs/core/class/methods/locales/resolve-canonical-locale)
* Configura [`customMapping`](/docs/cli/reference/config) nel tuo `gt.config.json`