كيفية بناء مكون مبدل اللغة في TanStack Start v1

تبديل اللغات مع البقاء في نفس الصفحة

المشكلة

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

الحل

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

الخطوات

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

إنشاء ملف تكوين يسرد جميع اللغات التي يدعمها تطبيقك ويحدد اللغة المحلية الافتراضية.

export const locales = ["en", "fr", "es", "de"] as const;

export type Locale = (typeof locales)[number];

export const defaultLocale: Locale = "en";

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

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

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

import { defaultLocale, locales, type Locale } from "./locales";

export function getLocaleFromPathname(pathname: string): Locale {
  const segments = pathname.split("/").filter(Boolean);
  const firstSegment = segments[0];

  if (firstSegment && locales.includes(firstSegment as Locale)) {
    return firstSegment as Locale;
  }

  return defaultLocale;
}

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

3. إنشاء مساعد لبناء المسارات المترجمة

اكتب دالة تأخذ مسار الصفحة الحالي واللغة المستهدفة، ثم تقوم ببناء مسار جديد مع استبدال جزء اللغة.

import { defaultLocale, locales, type Locale } from "./locales";

export function getLocalizedPath(
  pathname: string,
  targetLocale: Locale,
): string {
  const segments = pathname.split("/").filter(Boolean);
  const firstSegment = segments[0];

  const hasLocalePrefix =
    firstSegment && locales.includes(firstSegment as Locale);

  if (hasLocalePrefix) {
    segments[0] = targetLocale;
  } else {
    segments.unshift(targetLocale);
  }

  return "/" + segments.join("/");
}

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

4. بناء مكون مبدل اللغة

قم بإنشاء مكون يستخدم الموقع الحالي لإنشاء روابط لجميع اللغات المدعومة.

import { Link } from "@tanstack/react-router";
import { useLocation } from "@tanstack/react-router";
import { locales, type Locale } from "./locales";
import { getLocaleFromPathname, getLocalizedPath } from "./locale-helpers";

export function LanguageSwitcher() {
  const location = useLocation();
  const currentLocale = getLocaleFromPathname(location.pathname);

  return (
    <nav>
      <ul>
        {locales.map((locale) => {
          const isActive = locale === currentLocale;
          const localizedPath = getLocalizedPath(location.pathname, locale);

          return (
            <li key={locale}>
              <Link
                to={localizedPath}
                search={location.search}
                hash={location.hash}
                aria-current={isActive ? "page" : undefined}
              >
                {locale.toUpperCase()}
              </Link>
            </li>
          );
        })}
      </ul>
    </nav>
  );
}

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