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

Problema

Cuando los códigos de idioma se convierten en parte de la estructura de la URL, se transforman en entrada de usuario que debe ser validada. 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 roto o fallar. Cada localización inválida representa un potencial 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 comportamiento impredecible. La aplicación podría fallar silenciosamente al cargar traducciones, renderizar una mezcla de contenido de respaldo y contenido 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 URLs quedan sin retroalimentación clara sobre qué 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 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. Crea una ruta de layout con validación de localización

Usa 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 es inválido, el usuario es redirigido a la misma ruta sin el prefijo de localización, lo que se resuelve a la localización predeterminada. La localización validada se devuelve en el contexto para que las rutas hijas la utilicen.

3. Valida la localización en rutas anidadas

Para rutas que requieren una localización, valídala y lanza notFound() si es invá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 señalar que la URL está mal formada en lugar de corregirla silenciosamente.

4. Añade 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 forma 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.