Cómo validar parámetros de localización en URLs en TanStack Start v1

Problema

Cuando los códigos de idioma forman parte de la estructura de URL, se convierten en datos de entrada del usuario que deben validarse. Los usuarios pueden escribir manualmente cualquier cadena en el segmento de localización—/xx/about, /gibberish/contact, o /typo123/products—tan fácilmente como códigos válidos como /en/about o /fr/contact. Sin validación, la aplicación puede intentar cargar traducciones para localizaciones inexistentes, mostrar contenido incompleto o fallar. Cada localización inválida representa un posible callejón sin salida donde los usuarios no pueden recuperarse o navegar a páginas funcionales.

Los parámetros de localización no validados crean comportamientos impredecibles. La aplicación podría fallar silenciosamente al cargar traducciones, mostrar una mezcla de contenido predeterminado y faltante, o lanzar errores en tiempo de ejecución cuando se accede a las claves de traducción. Los usuarios que siguen enlaces rotos o escriben mal las URL se quedan sin una retroalimentación clara sobre lo que salió mal o cómo solucionarlo.

Solución

Valida el parámetro de localización de la URL contra una lista de localizaciones soportadas en la función beforeLoad de la ruta. Cuando la localización es inválida o falta, redirige al usuario a una URL válida con la localización predeterminada o lanza un error de no encontrado para mostrar una página de error útil. Esto asegura que solo se procesen las localizaciones soportadas y que los usuarios siempre lleguen a una página válida y traducible.

La función beforeLoad se ejecuta antes de que la ruta se cargue, lo que la convierte en el lugar ideal para verificar la localización. Al lanzar un error redirect() o notFound(), evitas que la ruta se renderice con una localización inválida y guías a los usuarios a un estado funcional.

Pasos

1. Define las localizaciones soportadas

Crea un array constante de códigos de localización válidos y una función de validación con seguridad de tipos.

const SUPPORTED_LOCALES = ["en", "fr", "es", "de"] as const;

type Locale = (typeof SUPPORTED_LOCALES)[number];

function isValidLocale(locale: string | undefined): locale is Locale {
  return SUPPORTED_LOCALES.includes(locale as Locale);
}

Esto proporciona una única fuente de verdad para las localizaciones soportadas y una función de validación reutilizable que TypeScript puede entender.

2. Crear una ruta de diseño con validación de localización

Utiliza un parámetro de localización opcional y valídalo en beforeLoad.

import { createFileRoute, redirect } from "@tanstack/react-router";

const DEFAULT_LOCALE: Locale = "en";

export const Route = createFileRoute("/{-$locale}")({
  beforeLoad: ({ params }) => {
    const { locale } = params;

    if (locale && !isValidLocale(locale)) {
      throw redirect({
        to: "/{-$locale}",
        params: { locale: undefined },
        replace: true,
      });
    }

    return {
      locale: (locale as Locale) || DEFAULT_LOCALE,
    };
  },
});

La función beforeLoad verifica el parámetro de localización. Si existe pero no es válido, el usuario es redirigido a la misma ruta sin el prefijo de localización, lo que resuelve a la localización predeterminada. La localización validada se devuelve en el contexto para que las rutas secundarias la utilicen.

3. Validar la localización en rutas anidadas

Para rutas que requieren una localización, valídala y lanza notFound() si no es válida.

import { createFileRoute, notFound } from "@tanstack/react-router";

export const Route = createFileRoute("/{-$locale}/products")({
  beforeLoad: ({ params }) => {
    const { locale } = params;

    if (locale && !isValidLocale(locale)) {
      throw notFound();
    }

    return {
      locale: (locale as Locale) || DEFAULT_LOCALE,
    };
  },
  component: ProductsPage,
});

function ProductsPage() {
  const { locale } = Route.useRouteContext();
  return <div>Products in {locale}</div>;
}

Este enfoque muestra una página de no encontrado para localizaciones inválidas en lugar de redirigir, lo cual es útil cuando quieres indicar que la URL está mal formada en lugar de corregirla silenciosamente.

4. Añadir un componente de no encontrado para localizaciones inválidas

Define un notFoundComponent en la ruta raíz para manejar errores de localización inválida de manera elegante.

import { createRootRoute } from "@tanstack/react-router";

export const Route = createRootRoute({
  notFoundComponent: () => {
    return (
      <div>
        <h1>Page Not Found</h1>
        <p>The language or page you requested does not exist.</p>
        <a href="/">Go to home page</a>
      </div>
    );
  },
});

Este componente se renderiza cuando se lanza notFound() desde beforeLoad, proporcionando a los usuarios un mensaje claro y una forma de navegar de vuelta a una página válida.