كيفية تنسيق الأرقام للغات المختلفة في Next.js (Pages Router) v16

المشكلة

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

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

الحل

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

توفر react-intl نهجين: مكون <FormattedNumber> للتنسيق التصريحي في JSX، وطريقة formatNumber من خطاف useIntl للتنسيق الإجرائي. كلاهما يعتمد على واجهة برمجة التطبيقات Intl.NumberFormat الخاصة بالمتصفح ويطبق تلقائياً اللغة المكونة في IntlProvider. يحترم الناتج المنسق الاصطلاحات الإقليمية لفواصل الآلاف والنقاط العشرية وتجميع الأرقام.

الخطوات

1. إنشاء مكون ينسق الأرقام بشكل تصريحي

يستخدم مكون <FormattedNumber> واجهات برمجة التطبيقات formatNumber و Intl.NumberFormat ويقبل خاصية value مع خيارات تتوافق مع Intl.NumberFormatOptions.

import { FormattedNumber } from "react-intl";

export default function ProductPrice({ price }: { price: number }) {
  return (
    <div>
      <FormattedNumber value={price} />
    </div>
  );
}

بشكل افتراضي، يعرض <FormattedNumber> الرقم المنسق في React.Fragment. يقرأ المكون اللغة من أقرب IntlProvider ويطبق قواعد التنسيق المناسبة.

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

مرر خيارات التنسيق للتحكم في كيفية ظهور الأرقام. تتضمن الخيارات الشائعة minimumFractionDigits، وmaximumFractionDigits، وstyle.

import { FormattedNumber } from "react-intl";

export default function Statistics({ value }: { value: number }) {
  return (
    <dl>
      <dt>Total Users</dt>
      <dd>
        <FormattedNumber
          value={value}
          minimumFractionDigits={0}
          maximumFractionDigits={0}
        />
      </dd>
      <dt>Conversion Rate</dt>
      <dd>
        <FormattedNumber
          value={value / 100}
          style="percent"
          minimumFractionDigits={2}
        />
      </dd>
    </dl>
  );
}

تتوافق هذه الخصائص مع Intl.NumberFormatOptions، مما يمنحك التحكم في الدقة والعرض مع الحفاظ على الفواصل الخاصة باللغة.

3. تنسيق الأرقام بشكل حتمي باستخدام خطاف useIntl

عندما يمكن التعبير عن مكون كمكون دالة، يوفر خطاف useIntl الوصول إلى كائن intl، والذي يتضمن طريقة formatNumber.

import { useIntl } from "react-intl";

export default function DataTable({ rows }: { rows: number[] }) {
  const intl = useIntl();

  return (
    <table>
      <tbody>
        {rows.map((value, index) => (
          <tr key={index}>
            <td>{intl.formatNumber(value)}</td>
          </tr>
        ))}
      </tbody>
    </table>
  );
}

تُرجع دالة formatNumber سلسلة رقمية منسقة وتقبل قيمة يمكن تحليلها كرقم، بالإضافة إلى خيارات تتوافق مع NumberFormatOptions.

4. تنسيق الأرقام في سياقات غير JSX

استخدم formatNumber عندما تحتاج إلى أرقام منسقة في السمات أو المتغيرات أو السياقات الأخرى حيث لا يمكن استخدام المكونات.

import { useIntl } from "react-intl";

export default function Chart({ dataPoints }: { dataPoints: number[] }) {
  const intl = useIntl();

  const formattedLabel = intl.formatNumber(dataPoints[0], {
    notation: "compact",
    maximumFractionDigits: 1,
  });

  return (
    <div>
      <img
        src="/chart.png"
        alt={`Chart showing ${formattedLabel} items`}
        title={formattedLabel}
      />
    </div>
  );
}

واجهة API الحتمية ضرورية لتعيين سمات النص مثل title، وaria-label، أو alt، حيث لا يمكن عرض مكونات React.