feat(plugin-ecommerce): add locale-aware currency formatting and symbol positioning (#15139)

This PR introduces automatic, locale-aware currency formatting using the
native Intl.NumberFormat API.

It also standardizes currency symbol positions and separators across the
frontend, ensuring consistent price display for different currencies in
Payload e-commerce.

**Changes**
1. useCurrency hook

- Added locale support in formatCurrency. 
- Replaced manual string formatting with Intl.NumberFormat:

```
return new Intl.NumberFormat(locale, {
  style: 'currency',
  currency: code,
  minimumFractionDigits: decimals,
  maximumFractionDigits: decimals,
}).format(value / Math.pow(10, decimals))
```


Automatically handles:
- Decimal separators (. vs ,) depending on locale 
- Currency placement (before or after the value) 
- Correct number of fraction digits
- Optional locale parameter allows overriding per call (default: 'en')


**2. Currency display settings**

Standardized symbol placement and separator:

```
<div className="priceCell">
  {currency.symbolPosition === 'before' ? `<span className="currencySymbol">${currency.symbol}</span>` : ''}
  {currency.symbolPosition === 'before' && currency.symbolSeparator}
  <span className="priceValue">{convertFromBaseValue({ baseValue: cellData, currency })}</span>
  {currency.symbolPosition === 'after' && currency.symbolSeparator}
  {currency.symbolPosition === 'after' ? `<span className="currencySymbol">${currency.symbol}</span>` : ''}
</div>
```

Ensures correct rendering for currencies that place the symbol before
(EUR, USD, GBP) or after (PLN).

**3. Predefined currencies**

Updated standard currency definitions:
```
export const EUR: Currency = { code: 'EUR', decimals: 2, label: 'Euro', symbol: '€', symbolPosition: 'before', symbolSeparator: '' }
export const USD: Currency = { code: 'USD', decimals: 2, label: 'US Dollar', symbol: '$', symbolPosition: 'before', symbolSeparator: '' }
export const GBP: Currency = { code: 'GBP', decimals: 2, label: 'British Pound', symbol: '£', symbolPosition: 'before', symbolSeparator: '' }
```


**4. Example: currenciesConfig in Payload**
```
import { EUR as BaseEUR, USD } from '@payloadcms/plugin-ecommerce';
import type { Currency } from '@payloadcms/plugin-ecommerce/types';

const PLN = {
  code: 'PLN',
  decimals: 2,
  label: 'Polski złoty',
  symbol: 'zł',
  symbolPosition: 'after',
  symbolSeparator: ' ',
} satisfies Currency;

export const currenciesConfig = {
  supportedCurrencies: [
    PLN,
    USD,
    BaseEUR,
  ],
  defaultCurrency: 'PLN',
};
```

<img width="576" height="641" alt="product-example"
src="https://github.com/user-attachments/assets/4965ac38-a8cc-44ab-b8d8-0f3d9082399c"
/>

---------

Co-authored-by: Paul Popus <paul@payloadcms.com>

Author: teastudiopl

packages/plugin-ecommerce/src/react/provider/index.tsx

@@ -1116,26 +1116,27 @@ export const useCurrency = () => {
   const { currenciesConfig, currency, setCurrency } = useEcommerce()
 
   const formatCurrency = useCallback(
-    (value?: null | number, options?: { currency?: Currency }): string => {
+    (value?: null | number, options?: { currency?: Currency; locale?: string }): string => {
       if (value === undefined || value === null) {
         return ''
       }
 
       const currencyToUse = options?.currency || currency
-
       if (!currencyToUse) {
         return value.toString()
       }
 
-      if (value === 0) {
-        return `${currencyToUse.symbol}0.${'0'.repeat(currencyToUse.decimals)}`
-      }
+      const { code, decimals, symbolDisplay } = currencyToUse
 
-      // Convert from base value (e.g., cents) to decimal value (e.g., dollars)
-      const decimalValue = value / Math.pow(10, currencyToUse.decimals)
+      const locale = options?.locale || 'en'
 
-      // Format with the correct number of decimal places
-      return `${currencyToUse.symbol}${decimalValue.toFixed(currencyToUse.decimals)}`
+      return new Intl.NumberFormat(locale, {
+        currency: code,
+        currencyDisplay: symbolDisplay || 'symbol',
+        maximumFractionDigits: decimals,
+        minimumFractionDigits: decimals,
+        style: 'currency',
+      }).format(value / Math.pow(10, decimals))
     },
     [currency],
   )

packages/plugin-ecommerce/src/types/index.ts

@@ -233,7 +233,7 @@ export type PaymentAdapterClient = {
 export type Currency = {
   /**
    * The ISO 4217 currency code
-   * @example 'usd'
+   * @example 'USD'
    */
   code: string
   /**
@@ -252,6 +252,11 @@ export type Currency = {
    * @example '$'
    */
   symbol: string
+  /**
+   * The display format for the currency symbol in formatted output.
+   * @example 'symbol'
+   */
+  symbolDisplay?: 'code' | 'symbol'
 }
 
 /**

packages/plugin-ecommerce/src/ui/PriceCell/index.tsx

@@ -1,11 +1,12 @@
 'use client'
+
 import type { DefaultCellComponentProps, TypedCollection } from 'payload'
 
 import { useTranslation } from '@payloadcms/ui'
 
 import type { CurrenciesConfig, Currency } from '../../types/index.js'
 
-import { convertFromBaseValue } from '../utilities.js'
+import { formatPrice } from '../utilities.js'
 
 type Props = {
   cellData?: number
@@ -16,7 +17,7 @@ type Props = {
 } & DefaultCellComponentProps
 
 export const PriceCell: React.FC<Props> = (args) => {
-  const { t } = useTranslation()
+  const { i18n, t } = useTranslation()
   const { cellData, currenciesConfig, currency: currencyFromProps, rowData } = args
 
   const currency = currencyFromProps || currenciesConfig.supportedCurrencies[0]
@@ -40,10 +41,5 @@ export const PriceCell: React.FC<Props> = (args) => {
     return <span>{t('plugin-ecommerce:priceNotSet')}</span>
   }
 
-  return (
-    <span>
-      {currency.symbol}
-      {convertFromBaseValue({ baseValue: cellData, currency })}
-    </span>
-  )
+  return <span>{formatPrice({ baseValue: cellData, currency, locale: i18n.language })}</span>
 }

packages/plugin-ecommerce/src/ui/PriceRowLabel/index.tsx

@@ -1,12 +1,12 @@
 'use client'
 
-import { useRowLabel } from '@payloadcms/ui'
+import { useRowLabel, useTranslation } from '@payloadcms/ui'
 import { useMemo } from 'react'
 
 import type { CurrenciesConfig } from '../../types/index.js'
 
 import './index.css'
-import { convertFromBaseValue } from '../utilities.js'
+import { formatPrice } from '../utilities.js'
 
 type Props = {
   currenciesConfig: CurrenciesConfig
@@ -16,6 +16,7 @@ export const PriceRowLabel: React.FC<Props> = (props) => {
   const { currenciesConfig } = props
   const { defaultCurrency, supportedCurrencies } = currenciesConfig
 
+  const { i18n } = useTranslation()
   const { data } = useRowLabel<{ amount: number; currency: string }>()
 
   const currency = useMemo(() => {
@@ -32,23 +33,20 @@ export const PriceRowLabel: React.FC<Props> = (props) => {
     return supportedCurrencies[0]
   }, [data.currency, supportedCurrencies, defaultCurrency])
 
-  const amount = useMemo(() => {
-    if (data.amount) {
-      return convertFromBaseValue({ baseValue: data.amount, currency: currency! })
+  const formattedPrice = useMemo(() => {
+    if (!currency) {
+      return '0'
     }
 
-    return '0'
-  }, [currency, data.amount])
+    return formatPrice({ baseValue: data.amount ?? 0, currency, locale: i18n.language })
+  }, [currency, data.amount, i18n.language])
 
   return (
     <div className="priceRowLabel">
       <div className="priceLabel">Price:</div>
 
       <div className="priceValue">
-        <span>
-          {currency?.symbol}
-          {amount}
-        </span>
+        <span>{formattedPrice}</span>
         <span>({data.currency})</span>
       </div>
     </div>

packages/plugin-ecommerce/src/ui/utilities.ts

@@ -44,3 +44,27 @@ export const convertFromBaseValue = ({
   // Format with the correct number of decimal places
   return decimalValue.toFixed(currency.decimals)
 }
+
+/**
+ * Format a base value as a locale-aware currency string using the Intl API.
+ *
+ * @example formatPrice({ baseValue: 2500, currency: USD }) // "$25.00"
+ * @example formatPrice({ baseValue: 2500, currency: EUR, locale: 'de' }) // "25,00 €"
+ */
+export const formatPrice = ({
+  baseValue,
+  currency,
+  locale = 'en',
+}: {
+  baseValue: number
+  currency: Currency
+  locale?: string
+}): string => {
+  return new Intl.NumberFormat(locale, {
+    currency: currency.code,
+    currencyDisplay: currency.symbolDisplay ?? 'symbol',
+    maximumFractionDigits: currency.decimals,
+    minimumFractionDigits: currency.decimals,
+    style: 'currency',
+  }).format(baseValue / Math.pow(10, currency.decimals))
+}