كيفية التحقق من صحة معاملات اللغة في عناوين URL في TanStack Start v1

المشكلة

عندما تصبح رموز اللغة جزءًا من بنية عنوان URL، فإنها تتحول إلى مدخلات مستخدم يجب التحقق من صحتها. يمكن للمستخدمين كتابة أي نص يدويًا في جزء اللغة—/xx/about، /gibberish/contact، أو /typo123/products—بنفس سهولة الرموز الصحيحة مثل /en/about أو /fr/contact. بدون التحقق من الصحة، قد يحاول التطبيق تحميل ترجمات للغات غير موجودة، أو عرض محتوى معطوب، أو التعطل. كل لغة غير صحيحة تمثل طريقًا مسدودًا محتملاً حيث لا يمكن للمستخدمين الاستعادة أو الانتقال إلى صفحات تعمل.

معاملات اللغة غير المتحقق منها تخلق سلوكًا غير متوقع. قد يفشل التطبيق بصمت في تحميل الترجمات، أو يعرض مزيجًا من المحتوى الاحتياطي والمحتوى المفقود، أو يطرح أخطاء وقت التشغيل عند الوصول إلى مفاتيح الترجمة. المستخدمون الذين يتبعون روابط معطوبة أو يخطئون في كتابة عناوين URL يُتركون دون ملاحظات واضحة حول ما حدث من خطأ أو كيفية إصلاحه.

الحل

تحقق من صحة معامل اللغة من عنوان URL مقابل قائمة اللغات المدعومة في دالة beforeLoad الخاصة بالمسار. عندما تكون اللغة غير صحيحة أو مفقودة، أعد توجيه المستخدم إلى عنوان URL صحيح باللغة الافتراضية أو اطرح خطأ عدم العثور لعرض صفحة خطأ مفيدة. هذا يضمن معالجة اللغات المدعومة فقط وأن المستخدمين يصلون دائمًا إلى صفحة صحيحة قابلة للترجمة.

تعمل دالة beforeLoad قبل تحميل المسار، مما يجعلها المكان المثالي للتحقق من اللغة. من خلال طرح خطأ redirect() أو notFound()، فإنك تمنع عرض المسار بلغة غير صحيحة وتوجه المستخدمين إلى حالة عمل صحيحة.

الخطوات

1. تحديد اللغات المدعومة

أنشئ مصفوفة ثابتة من رموز اللغات الصالحة ودالة تحقق آمنة من حيث الأنواع.

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);
}

يوفر هذا مصدراً واحداً للحقيقة للغات المدعومة ودالة تحقق قابلة لإعادة الاستخدام يمكن لـ TypeScript فهمها.

2. إنشاء مسار تخطيط مع التحقق من اللغة

استخدم معامل لغة اختياري وتحقق منه في 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,
    };
  },
});

تتحقق دالة beforeLoad من معامل اللغة. إذا كان موجوداً ولكنه غير صالح، يتم إعادة توجيه المستخدم إلى نفس المسار بدون بادئة اللغة، والذي يتم حله إلى اللغة الافتراضية. يتم إرجاع اللغة المتحقق منها في السياق لاستخدامها بواسطة المسارات الفرعية.

3. التحقق من اللغة في المسارات المتداخلة

بالنسبة للمسارات التي تتطلب لغة، تحقق منها وارمِ notFound() إذا كانت غير صالحة.

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>;
}

يعرض هذا النهج صفحة غير موجودة للغات غير الصالحة بدلاً من إعادة التوجيه، وهو مفيد عندما تريد الإشارة إلى أن عنوان URL مشوه بدلاً من تصحيحه بصمت.

4. إضافة مكون غير موجود للغات غير الصالحة

حدد notFoundComponent على المسار الجذر للتعامل مع أخطاء اللغة غير الصالحة بشكل سلس.

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>
    );
  },
});

يتم عرض هذا المكون عندما يتم رمي notFound() من beforeLoad، مما يمنح المستخدمين رسالة واضحة وطريقة للتنقل إلى صفحة صالحة.