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

المشكلة

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

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

الحل

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

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

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 أو سياق المسار الخاص بك للتأكد من أن جميع عروض العملات تحترم تفضيل لغة المستخدم.