# gt-next: General Translation Next.js SDK: Alias de configuración regional y SEO
URL: https://generaltranslation.com/es/docs/next/guides/locale-aliases.mdx
---
title: Alias de configuración regional y SEO
description: Usa alias personalizados de configuración regional para el routing de URL sin dejar de cumplir con BCP 47 para los motores de búsqueda
---
Los alias de configuración regional te permiten usar códigos de configuración regional personalizados en tus URL (p. ej., `/cn/` en lugar de `/zh/`) sin dejar de mantener tus metadatos SEO conformes con el [estándar BCP 47](https://www.w3.org/International/articles/language-tags/) que esperan los motores de búsqueda.
## ¿Por qué usar alias?
Los códigos de configuración regional BCP 47, como `zh` (chino) o `zh-Hant` (chino tradicional), son el estándar para identificar idiomas en la web.
Sin embargo, quizá quieras usar códigos distintos en las rutas URL por motivos de marca, legibilidad o requisitos regionales; por ejemplo, usar `/cn/` en lugar de `/zh/` para tu público en China.
GT admite esto mediante **mapeo personalizado** en tu `gt.config.json`. El alias se usa para el routing y las rutas URL, mientras que el código canónico BCP 47 se usa donde lo requieren los motores de búsqueda.
**Requisito de SEO:** Los motores de búsqueda solo reconocen [códigos de configuración regional BCP 47](https://www.w3.org/International/articles/language-tags/).
Usar códigos no estándar como `cn` en los atributos `hreflang` o en `` hará que los motores de búsqueda ignoren tus señales de configuración regional.
## Configuración
### Paso 1: Configura el mapeo personalizado
Añade una entrada `customMapping` a tu `gt.config.json` para cada alias:
```json title="gt.config.json"
{
"defaultLocale": "en-US",
"locales": ["en-US", "cn", "ja", "zh-Hant"],
"customMapping": {
"cn": {
"code": "zh",
"name": "Mandarin"
}
}
}
```
Aquí, `cn` es el alias que se usa en las URL y en el routing con middleware, y `zh` es el código BCP 47 canónico.
### Paso 2: Usa middleware con normalidad
El [middleware](/docs/next/guides/middleware) y la ruta dinámica `[locale]` funcionan con tus códigos alias de forma predeterminada. A los usuarios que visiten `/cn/about` se les mostrará contenido en chino; no hace falta ninguna configuración especial para el routing.
## Cumplimiento de BCP 47 para el SEO
Aunque los alias funcionan sin problemas para el routing, hay tres lugares donde **debes** usar el código BCP 47 canónico en lugar del alias:
1. El atributo `lang` de tu etiqueta ``
2. Las etiquetas de enlace alternativas en los metadatos de tu página
3. Las entradas alternativas de tu mapa del sitio
GT proporciona el método `resolveCanonicalLocale()` para convertir los alias nuevamente en sus códigos BCP 47. Puedes acceder a él mediante `getGTClass` desde `gt-next/server`:
```ts
import { getGTClass } from 'gt-next/server';
const gtInstance = getGTClass();
const canonicalLocale = gtInstance.resolveCanonicalLocale('cn');
// Devuelve: "zh"
```
Para las configuraciones regionales sin alias, `resolveCanonicalLocale()` devuelve la entrada sin modificar:
```ts
gtInstance.resolveCanonicalLocale('ja'); // "ja"
gtInstance.resolveCanonicalLocale('en-US'); // "en-US"
```
### 1. Atributo HTML `lang`
El atributo `` indica a los navegadores y a los motores de búsqueda en qué idioma está la página. Debe ser un código BCP 47 válido.
En tu layout raíz, determina la configuración regional antes de pasarla a la etiqueta ``:
```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}
);
}
```
Sin esto, una página en `/cn/about` renderizaría incorrectamente ``, que los motores de búsqueda no reconocen.
### 2. Metadatos alternativos
Los enlaces alternativos indican a los motores de búsqueda qué versiones de una página existen en otros idiomas. El atributo `hreflang` debe usar códigos 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'];
// Construir alternates con códigos BCP 47 canónicos como claves
const languages: Record = {};
for (const locale of locales) {
const canonical = gtInstance.resolveCanonicalLocale(locale);
languages[canonical] = `https://example.com/${locale}`;
}
// Agregar x-default para la configuración regional predeterminada
languages['x-default'] = 'https://example.com';
return {
alternates: {
canonical: `https://example.com/${params.locale}`,
languages,
},
};
}
```
Esto genera las etiquetas `` correctas en el encabezado de la página:
```html
```
Ten en cuenta que los valores de `hreflang` usan códigos canónicos (`zh`, no `cn`), mientras que las URL de `href` siguen usando las rutas alias (`/cn/`).
### 3. Alternativas de mapa del sitio
Si usas un [mapa del sitio dinámico](https://nextjs.org/docs/app/api-reference/file-conventions/metadata/sitemap), aplica el mismo patrón:
```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) => {
// Construir alternativas de idioma con códigos canónicos
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,
},
};
});
}
```
Esto genera un mapa del sitio XML con los atributos `hreflang` correctos:
```xml
https://example.com
```
## Errores comunes
| Error | Impacto | Solución |
| ------------------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Usar un código alias en `` | Los motores de búsqueda no pueden identificar el idioma de la página | Usa `resolveCanonicalLocale()` para el atributo `lang` |
| Usar un código alias en `hreflang` | Los motores de búsqueda ignoran el enlace alternativo | Usa `resolveCanonicalLocale()` para los valores de `hreflang` |
| Falta la alternativa `x-default` | No hay una opción de respaldo para los usuarios cuyo idioma no figura en la lista | Agrega `x-default` apuntando a la URL de tu configuración regional predeterminada |
| Alternativas inconsistentes entre el HTML y el mapa del sitio | Las señales contradictorias confunden a los rastreadores | Usa `resolveCanonicalLocale()` en ambos lugares |
## Próximos pasos
* Aprende sobre [middleware](/docs/next/guides/middleware) para el routing de URL según la configuración regional
* Consulta la referencia de la API de [`resolveCanonicalLocale`](/docs/core/class/methods/locales/resolve-canonical-locale)
* Configura [`customMapping`](/docs/cli/reference/config) en tu `gt.config.json`