كيفية تنسيق الأرقام لمختلف اللغات المحلية في TanStack Start v1

المشكلة

تُكتب الأرقام بشكل مختلف حول العالم. ما يظهر كـ 10,000.5 في الولايات المتحدة يصبح 10.000,5 في ألمانيا—حيث تتبادل الفواصل والنقاط أدوارها تمامًا. هذه ليست مسألة تفضيل أو أسلوب، بل مسألة وضوح. قد يقرأ المستخدم الألماني 10,000.5 على أنها عشرة، متجاهلًا فواصل التجميع. وقد يقرأ المستخدم الأمريكي 10.000,5 على أنها عشرة آلاف، متجاهلًا الفاصلة العشرية. نفس الأرقام، معانٍ متعاكسة.

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

الحل

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

توفر مكتبة React-intl مكونات وخطافات تستفيد من واجهة برمجة التطبيقات المدمجة في المتصفح Intl.NumberFormat لتطبيق التنسيق الخاص باللغة المحلية. من خلال تمرير قيمة رقمية واللغة المحلية الحالية، تختار هذه الأدوات تلقائيًا الفواصل الصحيحة وتجميع الأرقام والاتفاقيات الإقليمية الأخرى. النتيجة هي سلسلة منسقة تتطابق مع توقعات المستخدم دون معالجة يدوية للسلاسل أو منطق خاص باللغة المحلية في مكوناتك.

الخطوات

1. إنشاء مكون عرض الأرقام باستخدام FormattedNumber

قم ببناء مكون يقبل قيمة رقمية ويعرضها بتنسيق مناسب للغة المحلية باستخدام مكون FormattedNumber من react-intl.

import { FormattedNumber } from "react-intl";

interface PriceDisplayProps {
  value: number;
}

export function PriceDisplay({ value }: PriceDisplayProps) {
  return (
    <div>
      <FormattedNumber value={value} />
    </div>
  );
}

يطبق مكون FormattedNumber تلقائيًا الفواصل العشرية وفواصل التجميع الخاصة باللغة المحلية. يقرأ اللغة المحلية من أقرب IntlProvider في شجرة المكونات وينسق الرقم وفقًا لذلك.

2. تنسيق الأرقام بأنماط محددة

قم بتخصيص تنسيق الأرقام عن طريق تمرير خيارات النمط إلى FormattedNumber للعملات، النسب المئوية، أو الوحدات.

import { FormattedNumber } from "react-intl";

interface MetricsProps {
  revenue: number;
  growthRate: number;
  fileSize: number;
}

export function Metrics({ revenue, growthRate, fileSize }: MetricsProps) {
  return (
    <div>
      <p>
        الإيرادات:{" "}
        <FormattedNumber value={revenue} style="currency" currency="USD" />
      </p>
      <p>
        النمو: <FormattedNumber value={growthRate} style="percent" />
      </p>
      <p>
        الحجم:{" "}
        <FormattedNumber
          value={fileSize}
          style="unit"
          unit="megabyte"
          unitDisplay="short"
        />
      </p>
    </div>
  );
}

تتحكم خاصية style في وضع التنسيق. يتطلب تنسيق العملة رمز currency، ويقوم تنسيق النسبة المئوية تلقائيًا بالضرب في 100، ويتطلب تنسيق الوحدة معرّف unit. تحترم جميع الأنماط اتفاقيات اللغة النشطة.

3. تنسيق الأرقام بشكل إجرائي باستخدام useIntl

استخدم الخطاف useIntl لتنسيق الأرقام في السياقات التي لا تكون فيها المكونات مناسبة، مثل إنشاء سمات ديناميكية أو إعداد البيانات لواجهات برمجة التطبيقات غير React.

import { useIntl } from "react-intl";

interface ChartTooltipProps {
  dataPoint: number;
}

export function ChartTooltip({ dataPoint }: ChartTooltipProps) {
  const intl = useIntl();
  const formattedValue = intl.formatNumber(dataPoint, {
    minimumFractionDigits: 2,
    maximumFractionDigits: 2,
  });

  return <div title={formattedValue}>{formattedValue}</div>;
}

تُرجع طريقة formatNumber سلسلة منسقة على الفور، مما يجعلها مناسبة للسمات، وتسميات aria، أو أي سياق تحتاج فيه إلى القيمة المنسقة كسلسلة نصية بدلاً من عنصر React.

4. تطبيق خيارات التنسيق المخصصة

تحكم في الدقة، والتجميع، والترميز عن طريق تمرير Intl.NumberFormatOptions إلى FormattedNumber أو formatNumber.

import { FormattedNumber } from "react-intl";

interface StatisticProps {
  value: number;
  compact?: boolean;
}

export function Statistic({ value, compact }: StatisticProps) {
  return (
    <div>
      <FormattedNumber
        value={value}
        notation={compact ? "compact" : "standard"}
        minimumFractionDigits={0}
        maximumFractionDigits={2}
      />
    </div>
  );
}

تتحكم خيارات مثل notation، وminimumFractionDigits، وmaximumFractionDigits في كيفية عرض الرقم. يحول الترميز المضغوط الأرقام الكبيرة إلى أشكال مختصرة مثل "1.2M" مع احترام الاختصارات الخاصة باللغة.