Política de URL por idioma

Define prefijos de idioma, negocia las preferencias lingüísticas y determina las redirecciones y las 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 #

sh
npm install @lingo.dev/locale-router@0.2.1
ts
import { 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 en la URL. Si no se especifica otro valor, 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 array de idiomas de solo lectura y devuelve LocaleRouter<L>. defaultLocale es obligatorio; exclude y slugs son opcionales. Las exclusiones se comprueban en el primer segmento de la ruta. También se excluye cualquier primer segmento que empiece por _ o contenga ., de modo que las rutas internas y de archivos quedan fuera de la localización.

Convierte una URL sin prefijo en una decisión de redirección #

ts
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 petición HTTP real no incluye el fragmento del navegador, aunque la función auxiliar de URL conserva el 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 anteriorResultado
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 una etiqueta de idioma.
locales.split("/br/account"){ locale: "pt-BR", rest: "/account" }.
locales.isLocalized("/account")true. Esto indica 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 rutas solo la ruta, no una cadena que contenga parámetros de consulta o un fragmento.

prefix y alternates esperan una ruta sin prefijo. Para cambiar /br/account al alemán, divide la ruta y pasa rest:

ts
const current = locales.split("/br/account");
const germanPath = current ? locales.prefix(current.rest, "de") : undefined;

El resultado es /de/account. Añadir el prefijo directamente a la ruta original puede introducir un segundo segmento de idioma.

Negocia las preferencias de idioma #

negotiate(acceptLanguage: string | null): L ordena las preferencias con un valor de calidad positivo según ese valor y las prueba una a una en ese orden. Para cada preferencia, busca primero una coincidencia exacta de la etiqueta de idioma y después una coincidencia con un idioma admitido. Si varias variantes regionales admitidas comparten un idioma, el orden en que se hayan configurado puede determinar qué variante se usa como alternativa.

Se descartan los valores de calidad no válidos y las preferencias con calidad cero. Las etiquetas no válidas no generan coincidencias, y un comodín no sustituye 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 necesita. Un servidor puede sustituir la ruta en una copia de la URL de la petición y conservar 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 añade este paso de normalización independiente.

Genera URL alternativas por idioma #

ts
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; con esta política, la entrada del inglés predeterminado usa /en/account.

El código que realiza la llamada los presenta como metadatos. Los metadatos de cabecera de TanStack añaden campos canónicos y de Open Graph sobre la base de esta política. El adaptador de Next Pages sigue la política de URL de Next para el idioma predeterminado, que es distinta, así que no intercambies sus resultados.