كيفية عرض معلومات العملة في TanStack Start v1

المشكلة

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

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

الحل

استخدم واجهات برمجة التطبيقات (APIs) المدمجة في المتصفح للتدويل لعرض معلومات العملة بالتنسيق الذي يتطابق مع كل من اللغة المحلية للمستخدم والسياق. توفر واجهة Intl.DisplayNames أسماء العملات الكاملة المترجمة، بينما يمكن لـ Intl.NumberFormat مع خيار currencyDisplay استخراج رموز العملات أو أكوادها. من خلال اختيار واجهة برمجة التطبيقات المناسبة وخيار التنسيق بناءً على السياق، تضمن أن تكون مراجع العملة واضحة ومترجمة بشكل صحيح دون الحاجة إلى الاحتفاظ ببيانات الترجمة.

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

الخطوات

1. إنشاء دالة مساعدة للحصول على أسماء العملات المترجمة

تقوم واجهة برمجة التطبيقات Intl.DisplayNames مع type: "currency" بإرجاع أسماء العملات المترجمة بالكامل لأي رمز عملة ISO 4217.

export function getCurrencyName(currencyCode: string, locale: string): string {
  const displayNames = new Intl.DisplayNames([locale], { type: "currency" });
  return displayNames.of(currencyCode) || currencyCode;
}

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

2. إنشاء دالة مساعدة لاستخراج رموز العملات

يتحكم خيار currencyDisplay في Intl.NumberFormat في كيفية ظهور العملة، مع قيم "code"، "symbol"، "narrowSymbol"، و"name".

export function getCurrencySymbol(
  currencyCode: string,
  locale: string,
  narrow: boolean = false,
): string {
  const formatter = new Intl.NumberFormat(locale, {
    style: "currency",
    currency: currencyCode,
    currencyDisplay: narrow ? "narrowSymbol" : "symbol",
  });

  const parts = formatter.formatToParts(0);
  const currencyPart = parts.find((part) => part.type === "currency");
  return currencyPart?.value || currencyCode;
}

تقوم هذه الدالة المساعدة بتنسيق قيمة صفرية واستخراج رمز العملة فقط. يتحكم المعامل narrow فيما إذا كان سيتم استخدام رمز مختصر مثل "$" أو رمز موضح مثل "US$". استخدم الرموز في عناصر واجهة المستخدم المدمجة مثل الجداول أو الرسوم البيانية.

3. إنشاء مكون لعرض معلومات العملة

قم ببناء مكون مرن يمكنه عرض معلومات العملة بأي تنسيق استنادًا إلى خاصية display.

interface CurrencyDisplayProps {
  code: string;
  locale: string;
  display: "name" | "symbol" | "narrowSymbol" | "code";
}

export function CurrencyDisplay({
  code,
  locale,
  display,
}: CurrencyDisplayProps) {
  let content: string;

  if (display === "name") {
    content = getCurrencyName(code, locale);
  } else if (display === "code") {
    content = code.toUpperCase();
  } else {
    content = getCurrencySymbol(code, locale, display === "narrowSymbol");
  }

  return <span>{content}</span>;
}

يقوم هذا المكون بتوحيد منطق عرض العملة ويجعل من السهل تبديل التنسيقات. استخدم "name" للقوائم المنسدلة والنص التوضيحي، و"symbol" أو "narrowSymbol" للعروض المدمجة، و"code" عندما تكون الدقة مطلوبة.

4. استخدام المكون في مسار TanStack Start

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

import { createFileRoute } from "@tanstack/react-router";
import { CurrencyDisplay } from "~/components/CurrencyDisplay";

export const Route = createFileRoute("/currencies")({
  component: CurrenciesPage,
});

function CurrenciesPage() {
  const locale = "en-US";

  return (
    <div>
      <h1>Currency Information</h1>
      <p>
        Full name: <CurrencyDisplay code="USD" locale={locale} display="name" />
      </p>
      <p>
        Symbol: <CurrencyDisplay code="USD" locale={locale} display="symbol" />
      </p>
      <p>
        Code: <CurrencyDisplay code="USD" locale={locale} display="code" />
      </p>
    </div>
  );
}

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