كيفية التحقق من صحة معلمات اللغة في عناوين 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، مما يعطي المستخدمين رسالة واضحة وطريقة للتنقل مرة أخرى إلى صفحة صالحة.