# gt-next: General Translation Next.js SDK: Alias de paramètres régionaux et SEO
URL: https://generaltranslation.com/fr/docs/next/guides/locale-aliases.mdx
---
title: Alias de paramètres régionaux et SEO
description: Utilisez des alias de paramètres régionaux personnalisés pour le routing des URL tout en restant conforme à BCP 47 pour les moteurs de recherche
---
Les alias de paramètres régionaux vous permettent d’utiliser des codes de langue personnalisés dans vos URL (par exemple `/cn/` au lieu de `/zh/`) tout en conservant des métadonnées SEO conformes à la norme [BCP 47](https://www.w3.org/International/articles/language-tags/) attendue par les moteurs de recherche.
## Pourquoi des alias ?
Les codes de langue BCP 47 comme `zh` (chinois) ou `zh-Hant` (chinois traditionnel) sont la norme pour identifier les langues sur le web.
Cependant, vous pouvez préférer utiliser d’autres codes dans vos chemins d’URL pour des raisons d’image de marque, de lisibilité ou de contexte régional — par exemple, utiliser `/cn/` au lieu de `/zh/` pour votre audience chinoise.
GT prend cela en charge via le **mappage personnalisé** dans votre `gt.config.json`. L’alias est utilisé pour le routing et les chemins d’URL, tandis que le code BCP 47 canonique est utilisé partout où les moteurs de recherche en ont besoin.
**Exigence SEO :** Les moteurs de recherche ne reconnaissent que les [codes de langue BCP 47](https://www.w3.org/International/articles/language-tags/).
L’utilisation de codes non standard comme `cn` dans les attributs `hreflang` ou `` amènera les moteurs de recherche à ignorer vos indications de paramètre régional.
## Configuration
### Étape 1 : Configurer le mappage personnalisé
Ajoutez une entrée `customMapping` à votre `gt.config.json` pour chaque alias :
```json title="gt.config.json"
{
"defaultLocale": "en-US",
"locales": ["en-US", "cn", "ja", "zh-Hant"],
"customMapping": {
"cn": {
"code": "zh",
"name": "Mandarin"
}
}
}
```
Ici, `cn` est l’alias utilisé dans les URL et pour le middleware routing, et `zh` est le code BCP 47 canonique.
### Étape 2 : utilisez le middleware comme d’habitude
Le [middleware](/docs/next/guides/middleware) et la route dynamique `[locale]` fonctionnent nativement avec vos codes d’alias. Les utilisateurs qui consultent `/cn/about` recevront du contenu en chinois — aucune configuration particulière n’est nécessaire au niveau du routing.
## Conformité BCP 47 pour le SEO
Bien que les alias fonctionnent parfaitement pour le routing, il existe trois endroits où vous **devez** utiliser le code BCP 47 canonique au lieu de l'alias :
1. L'attribut `lang` de votre balise ``
2. Les balises de lien alternatif dans les métadonnées de votre page
3. Les entrées alternatives dans votre plan de site
GT fournit la méthode `resolveCanonicalLocale()` pour reconvertir les alias en codes BCP 47. Vous pouvez y accéder via `getGTClass` depuis `gt-next/server` :
```ts
import { getGTClass } from 'gt-next/server';
const gtInstance = getGTClass();
const canonicalLocale = gtInstance.resolveCanonicalLocale('cn');
// Retourne : "zh"
```
Pour les paramètres régionaux sans alias, `resolveCanonicalLocale()` renvoie la valeur d’entrée inchangée :
```ts
gtInstance.resolveCanonicalLocale('ja'); // "ja"
gtInstance.resolveCanonicalLocale('en-US'); // "en-US"
```
### 1. Attribut HTML `lang`
L’attribut `` indique aux navigateurs et aux moteurs de recherche la langue de la page. Il doit s’agir d’un code BCP 47 valide.
Dans votre layout racine, résolvez le paramètre régional avant de le transmettre à la balise `` :
```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}
);
}
```
Sans cela, une page à l’adresse `/cn/about` générerait à tort ``, que les moteurs de recherche ne reconnaissent pas.
### 2. Métadonnées d’alternance
Les liens alternatifs indiquent aux moteurs de recherche quelles versions d’une page existent dans d’autres langues. L’attribut `hreflang` doit utiliser des codes 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'];
// Construire les alternates avec les codes BCP 47 canoniques comme clés
const languages: Record = {};
for (const locale of locales) {
const canonical = gtInstance.resolveCanonicalLocale(locale);
languages[canonical] = `https://example.com/${locale}`;
}
// Ajouter x-default pour le paramètre régional par défaut
languages['x-default'] = 'https://example.com';
return {
alternates: {
canonical: `https://example.com/${params.locale}`,
languages,
},
};
}
```
Cela génère des balises `` correctes dans l’en-tête de la page :
```html
```
Notez que les valeurs `hreflang` utilisent des codes canoniques (`zh` et non `cn`), tandis que les URL `href` continuent d’utiliser les chemins d’alias (`/cn/`).
### 3. Alternatives de plan de site
Si vous utilisez un [plan de site dynamique](https://nextjs.org/docs/app/api-reference/file-conventions/metadata/sitemap), appliquez la même approche :
```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) => {
// Construire les variantes linguistiques avec les codes canoniques
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,
},
};
});
}
```
Cela génère un plan de site XML avec les attributs `hreflang` appropriés :
```xml
https://example.com
```
## Erreurs courantes
| Erreur | Impact | Correction |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Utilisation d’un code alias dans `` | Les moteurs de recherche ne peuvent pas identifier la langue de la page | Utilisez `resolveCanonicalLocale()` pour l’attribut `lang` |
| Utilisation d’un code alias dans `hreflang` | Les moteurs de recherche ignorent le lien alternatif | Utilisez `resolveCanonicalLocale()` pour les valeurs de `hreflang` |
| Absence d’alternative `x-default` | Aucun contenu de remplacement pour les utilisateurs dont la langue n’est pas indiquée | Ajoutez `x-default` pointant vers l’URL de votre paramètre régional par défaut |
| Alternatives incohérentes entre le HTML et le plan de site | Des signaux contradictoires perturbent les robots d’exploration | Utilisez `resolveCanonicalLocale()` aux deux endroits |
## Étapes suivantes
* Découvrez le [middleware](/docs/next/guides/middleware) pour le routage des URL en fonction du paramètre régional
* Consultez la référence API de [`resolveCanonicalLocale`](/docs/core/class/methods/locales/resolve-canonical-locale)
* Configurez [`customMapping`](/docs/cli/reference/config) dans votre `gt.config.json`