كيفية الحفاظ على اللغة في روابط التنقل في TanStack Start v1

الحفاظ على اللغة عبر التنقل الداخلي

المشكلة

عندما يتم تضمين معلومات اللغة في مسار عنوان URL، يجب أن تحافظ كل روابط التنقل على تلك اللغة للحفاظ على تجربة مستخدم متسقة. إذا كان المستخدم يتصفح النسخة الفرنسية من موقع ما في /fr/products، فإن النقر على رابط إلى /about سينقله إلى اللغة الافتراضية، مما يؤدي إلى كسر سياق جلسته. إن ترميز معلمات اللغة يدويًا في كل رابط هو أمر متكرر وعرضة للأخطاء، خاصة مع نمو التطبيق وإضافة المزيد من الروابط عبر المكونات.

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

الحل

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

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

الخطوات

بناء مكون يقرأ اللغة الحالية ويتضمنها تلقائيًا في معلمات التنقل.

import { Link, LinkProps, useParams } from "@tanstack/react-router";

type LocaleLinkProps = LinkProps & {
  to: string;
};

export function LocaleLink(props: LocaleLinkProps) {
  const params = useParams({ strict: false });
  const currentLocale = params.locale;

  const enhancedParams = {
    ...props.params,
    ...(currentLocale && { locale: currentLocale }),
  };

  return <Link {...props} params={enhancedParams} />;
}

يستخدم هذا المكون useParams مع strict: false للوصول إلى المعلمات من أي مسار في التطبيق، ويستخرج locale الحالي، ويدمجه في خاصية params التي يتم تمريرها إلى مكون Link الأساسي. يضمن عامل التشغيل spread أن أي معلمات يتم توفيرها صراحةً تأخذ الأولوية.

استبدل مكونات Link القياسية بمكونات LocaleLink في جميع أنحاء تطبيقك.

import { createFileRoute } from "@tanstack/react-router";
import { LocaleLink } from "../components/LocaleLink";

export const Route = createFileRoute("/{-$locale}/products")({
  component: ProductsPage,
});

function ProductsPage() {
  return (
    <div>
      <h1>Products</h1>
      <nav>
        <LocaleLink to="/{-$locale}/about">About</LocaleLink>
        <LocaleLink to="/{-$locale}/contact">Contact</LocaleLink>
        <LocaleLink to="/{-$locale}/products/$id" params={{ id: "123" }}>
          Product 123
        </LocaleLink>
      </nav>
    </div>
  );
}

عندما يزور المستخدم /fr/products، تقوم جميع مكونات LocaleLink تلقائيًا بالتحويل إلى /fr/about و/fr/contact و/fr/products/123. يتم الحفاظ على معلمة اللغة دون تدخل يدوي في كل موقع رابط.

3. التعامل مع تبديل اللغة بشكل صريح عند الحاجة

بالنسبة لمكونات مبدل اللغة، تجاوز الحقن التلقائي للغة باستخدام Link القياسي مباشرة.

import { Link, useParams } from "@tanstack/react-router";

export function LanguageSwitcher() {
  const params = useParams({ strict: false });
  const currentPath = window.location.pathname.replace(/^\/(en|fr|es)/, "");

  return (
    <div>
      <Link to={`/{-$locale}${currentPath}`} params={{ locale: "en" }}>
        English
      </Link>
      <Link to={`/{-$locale}${currentPath}`} params={{ locale: "fr" }}>
        Français
      </Link>
      <Link to={`/{-$locale}${currentPath}`} params={{ locale: "es" }}>
        Español
      </Link>
    </div>
  );
}

تتطلب مبدلات اللغة تحكمًا صريحًا في معلمة اللغة، لذلك تستخدم مكون Link القياسي وتعين معلمة locale بشكل صريح. هذا يسمح للمستخدمين بتغيير اللغات مع البقاء في نفس الصفحة المنطقية.