كيفية اكتشاف تفضيلات لغة المستخدم في TanStack Start v1

المشكلة

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

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

الحل

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

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

الخطوات

1. إنشاء مساعد لتحليل ترويسة Accept-Language

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

export function parseAcceptLanguage(
  header: string | null,
  supportedLocales: string[],
): string | null {
  if (!header) {
    return null;
  }

  const languages = header
    .split(",")
    .map((lang) => {
      const [code, qValue] = lang.trim().split(";q=");
      const quality = qValue ? parseFloat(qValue) : 1.0;
      return { code: code.toLowerCase(), quality };
    })
    .sort((a, b) => b.quality - a.quality);

  for (const { code } of languages) {
    const exactMatch = supportedLocales.find(
      (locale) => locale.toLowerCase() === code,
    );
    if (exactMatch) {
      return exactMatch;
    }

    const baseCode = code.split("-")[0];
    const baseMatch = supportedLocales.find((locale) =>
      locale.toLowerCase().startsWith(baseCode),
    );
    if (baseMatch) {
      return baseMatch;
    }
  }

  return null;
}

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

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

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

export const SUPPORTED_LOCALES = ["en", "fr", "de", "es", "ja"];
export const DEFAULT_LOCALE = "en";

تقوم هذه الثوابت بتوحيد تكوين اللغة الخاص بك وتسهل إضافة أو إزالة اللغات المدعومة مع نمو تطبيقك.

3. إنشاء معالج مسار الخادم للمسار الجذر

أضف معالج GET من جانب الخادم إلى مسار الفهرس الخاص بك الذي يقرأ ترويسة Accept-Language، ويحدد أفضل لغة، ويعيد توجيه المستخدم إلى المسار المناسب للغة المحددة.

import { createFileRoute, redirect } from "@tanstack/react-router";
import { getRequestHeaders } from "@tanstack/react-start/server";

export const Route = createFileRoute("/")({
  server: {
    handlers: {
      GET: async () => {
        const headers = getRequestHeaders();
        const acceptLanguage = headers.get("accept-language");

        const preferredLocale = parseAcceptLanguage(
          acceptLanguage,
          SUPPORTED_LOCALES,
        );

        const targetLocale = preferredLocale || DEFAULT_LOCALE;

        throw redirect({
          to: `/${targetLocale}`,
          statusCode: 302,
        });
      },
    },
  },
});

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

4. استيراد دالة المساعدة

تأكد من توفر دالة التحليل المساعدة في ملف المسار الخاص بك عن طريق استيرادها في الأعلى مع تكوين اللغة الخاص بك.

import { createFileRoute, redirect } from "@tanstack/react-router";
import { getRequestHeaders } from "@tanstack/react-start/server";
import {
  parseAcceptLanguage,
  SUPPORTED_LOCALES,
  DEFAULT_LOCALE,
} from "../lib/locale";

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