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

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

المشكلة

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

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

الحل

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

يعمل هذا النهج من خلال قراءة اللغة النشطة من معاملات المسار باستخدام خطافات الموجه، ثم دمج تلك اللغة في معاملات رابط الوجهة. يحافظ الغلاف على جميع وظائف 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 الأساسي. يضمن عامل النشر أن أي معاملات مقدمة بشكل صريح لها الأولوية.

استبدل مكونات 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 بشكل صريح. يتيح هذا للمستخدمين تغيير اللغات مع البقاء على نفس الصفحة المنطقية.