Política de URL por idioma
Define prefijos de idioma, negocia las preferencias de idioma y determina redirecciones y rutas alternativas sin depender de un framework.
Una URL localizada necesita una política coherente: qué idiomas están disponibles, cómo aparecen en las rutas y adónde debe llevar al lector una ruta sin prefijo. @lingo.dev/locale-router toma esas decisiones con Intl nativo. Tu servidor envía la redirección y tu aplicación carga el catálogo elegido.
Define los idiomas admitidos y sus slugs #
npm install @lingo.dev/locale-router@0.2.1import { createLocaleRouter } from "@lingo.dev/locale-router";
const locales = createLocaleRouter(["en", "de", "pt-BR"] as const, {
defaultLocale: "en",
exclude: ["api", "assets"],
slugs: { "pt-BR": "br" },
});El idioma pt-BR identifica el portugués de Brasil; br es solo su slug de URL. Si no se especifica un valor personalizado, los slugs son las etiquetas de idioma en minúsculas. Usa etiquetas válidas, un idioma predeterminado del conjunto admitido y slugs distintos en minúsculas. El constructor no valida todas las configuraciones que pueden generar conflictos.
createLocaleRouter<L extends string>(locales, options) acepta un arreglo de idiomas de solo lectura y devuelve LocaleRouter<L>. defaultLocale es obligatorio; exclude y slugs son opcionales. Las exclusiones se comparan con el primer segmento de la ruta. También se excluye cualquier primer segmento que comience con _ o contenga ., para mantener las rutas internas y de archivos fuera de la localización.
Convierte una URL sin prefijo en una decisión de redirección #
const target = locales.redirect(
new URL("https://example.com/account?tab=billing#details"),
"de-CH,de;q=0.8,en;q=0.5",
);
if (target) {
console.log(target.href);
}Esto genera https://example.com/de/account?tab=billing#details. La preferencia por el alemán de Suiza coincide con el idioma alemán admitido. La función auxiliar devuelve una nueva URL; no envía una respuesta HTTP ni establece una cookie. Tu servidor elige el código de estado y envía la ubicación de destino. Una solicitud HTTP real no incluye el fragmento del navegador, aunque la función auxiliar de URL conserva cualquier fragmento que se le proporcione.
Si una preferencia guardada debe tener prioridad, valida su etiqueta de idioma con toLocale y pasa el resultado como tercer argumento opcional de redirect. No pases una cadena arbitraria como idioma admitido.
Inspecciona y construye rutas #
| Llamada con la política anterior | Resultado |
|---|---|
locales.toLocale("pt_BR") | "pt-BR". Los guiones bajos se normalizan antes de buscar una coincidencia exacta de idioma. |
locales.toLocale("br") | undefined. Un slug de URL no es la etiqueta de idioma. |
locales.split("/br/account") | { locale: "pt-BR", rest: "/account" }. |
locales.isLocalized("/account") | true. Esto significa que la ruta se puede localizar, no que ya tenga un prefijo. |
locales.prefix("/account", "de") | "/de/account". |
locales.prefix("/", "de") | "/de". |
locales.prefix("/api/status", "de") | "/api/status", sin cambios. |
locales.canonical("/DE/account") | "/de/account". |
split devuelve undefined si no reconoce el slug del primer segmento. Pasa a los métodos de ruta solo el componente de ruta, no una cadena con parámetros de consulta o un fragmento.
prefix y alternates esperan una ruta sin prefijo. Para cambiar /br/account al alemán, sepárala y pasa rest:
const current = locales.split("/br/account");
const germanPath = current ? locales.prefix(current.rest, "de") : undefined;El resultado es /de/account. Agregar un prefijo directamente a la ruta original puede añadir un segundo segmento de idioma.
Negocia las preferencias de idioma #
negotiate(acceptLanguage: string | null): L ordena las preferencias con un valor de calidad mayor que cero según ese valor y prueba cada una en ese orden. Para cada preferencia, busca primero una coincidencia exacta de idioma y luego una coincidencia con un idioma admitido. Si varias variantes regionales admitidas comparten un idioma, su orden en la configuración puede determinar la variante de respaldo.
Se descartan los valores de calidad no válidos y las preferencias con calidad cero. Las etiquetas no válidas no producen coincidencias y un comodín no reemplaza la política predeterminada. Si ninguna preferencia coincide, el método devuelve defaultLocale. Así se selecciona un idioma a partir de las preferencias indicadas, no de la geolocalización.
Mantén la canonicalización separada de las redirecciones de rutas sin prefijo #
canonical(pathname): string | undefined sugiere un slug normalizado cuando reconoce un primer segmento con formato de etiqueta de idioma. No es un generador general de URL canónicas. redirect devuelve undefined para las rutas que ya tienen prefijo, las exclusiones y las rutas para las que canonical puede sugerir una corrección.
Gestiona la normalización de /DE/account por separado si tu aplicación la requiere. Un servidor puede reemplazar el componente de ruta en una copia de la URL de la solicitud, conservando los parámetros de consulta, antes de enviar la redirección elegida. El middleware de TanStack gestiona la negociación de rutas sin prefijo, pero no agrega este paso de normalización independiente.
Genera URL para otros idiomas #
const links = locales.alternates("/account").map(({ locale, pathname }) => ({
hrefLang: locale,
href: new URL(pathname, "https://example.com").href,
}));Usa el origen de confianza del sitio en lugar del que aparece en el ejemplo. alternates devuelve un { locale, pathname } por cada idioma admitido, además de x-default, que apunta a la ruta del idioma predeterminado. La entrada del idioma pt-BR usa /br/account; la entrada predeterminada en inglés usa /en/account según esta política.
El código que hace la llamada los presenta como metadatos. Los metadatos de cabecera de TanStack agregan campos canónicos y de Open Graph a esta política. El adaptador de Next Pages sigue una política diferente de Next para las URL del idioma predeterminado, así que no debes intercambiar sus resultados.