@carlonicora/nextjs-jsonapi 4.1.1 → 4.2.0

package/src/features/billing/components/cards/PaymentMethodSummaryCard.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import { useTranslations } from "next-intl";
 import { Wallet, ChevronRight } from "lucide-react";
 import { Card, CardContent, CardHeader, CardTitle, Button, Skeleton } from "../../../../shadcnui";
 import { PaymentMethodInterface } from "../../stripe-customer";
@@ -32,11 +33,12 @@ export function PaymentMethodSummaryCard({
   error,
   onManageClick,
 }: PaymentMethodSummaryCardProps) {
+  const t = useTranslations();
   if (loading) {
     return (
       <Card>
         <CardHeader className="flex flex-row items-center justify-between space-y-0 pb-2">
-          <CardTitle>Payment Method</CardTitle>
+          <CardTitle>{t("billing.ui.payment_method.title")}</CardTitle>
           <Wallet className="h-4 w-4 text-muted-foreground" />
         </CardHeader>
         <CardContent>
@@ -51,7 +53,7 @@ export function PaymentMethodSummaryCard({
     return (
       <Card>
         <CardHeader className="flex flex-row items-center justify-between space-y-0 pb-2">
-          <CardTitle>Payment Method</CardTitle>
+          <CardTitle>{t("billing.ui.payment_method.title")}</CardTitle>
           <Wallet className="h-4 w-4 text-muted-foreground" />
         </CardHeader>
         <CardContent>
@@ -67,14 +69,16 @@ export function PaymentMethodSummaryCard({
   return (
     <Card className="cursor-pointer hover:bg-accent/50 transition-colors" onClick={onManageClick}>
       <CardHeader className="flex flex-row items-center justify-between space-y-0 pb-2">
-        <CardTitle>Payment Method</CardTitle>
+        <CardTitle>{t("billing.ui.payment_method.title")}</CardTitle>
         <Wallet className="h-4 w-4 text-muted-foreground" />
       </CardHeader>
       <CardContent>
         {paymentMethods.length === 0 ? (
           <div className="space-y-2">
-            <p className="text-xl font-bold text-muted-foreground">No payment method</p>
-            <p className="text-xs text-muted-foreground">Add a card to enable subscriptions</p>
+            <p className="text-xl font-bold text-muted-foreground">
+              {t("billing.ui.cards.payment_method.empty_title")}
+            </p>
+            <p className="text-xs text-muted-foreground">{t("billing.ui.cards.payment_method.empty_description")}</p>
             <Button
               variant="outline"
               size="sm"
@@ -84,7 +88,7 @@ export function PaymentMethodSummaryCard({
                 onManageClick();
               }}
             >
-              Add Card
+              {t("billing.ui.cards.payment_method.add_card")}
               <ChevronRight className="h-4 w-4 ms-1 rtl:rotate-180" />
             </Button>
           </div>
@@ -94,17 +98,23 @@ export function PaymentMethodSummaryCard({
               {getCardBrandIcon(defaultMethod.card.brand)} ****{defaultMethod.card.last4}
             </p>
             <p className="text-sm text-muted-foreground">
-              Expires {String(defaultMethod.card.expMonth).padStart(2, "0")}/{defaultMethod.card.expYear}
+              {t("billing.ui.payment_method.expires", {
+                date: `${String(defaultMethod.card.expMonth).padStart(2, "0")}/${defaultMethod.card.expYear}`,
+              })}
             </p>
             {paymentMethods.length > 1 && (
-              <p className="text-xs text-muted-foreground">+{paymentMethods.length - 1} more card(s)</p>
+              <p className="text-xs text-muted-foreground">
+                {t("billing.ui.cards.payment_method.more_cards", { count: paymentMethods.length - 1 })}
+              </p>
             )}
           </div>
         ) : (
           <div className="space-y-2">
-            <p className="text-xl font-bold">{defaultMethod?.type || "Payment Method"}</p>
+            <p className="text-xl font-bold">{defaultMethod?.type || t("billing.ui.payment_method.title")}</p>
             {paymentMethods.length > 1 && (
-              <p className="text-xs text-muted-foreground">+{paymentMethods.length - 1} more method(s)</p>
+              <p className="text-xs text-muted-foreground">
+                {t("billing.ui.cards.payment_method.more_methods", { count: paymentMethods.length - 1 })}
+              </p>
             )}
           </div>
         )}

package/src/features/billing/components/cards/SubscriptionSummaryCard.tsx

@@ -1,8 +1,10 @@
 "use client";
 
+import { useTranslations } from "next-intl";
 import { ChevronRight, CreditCard } from "lucide-react";
 import { Badge, Button, Card, CardContent, CardHeader, CardTitle, Skeleton } from "../../../../shadcnui";
 import { StripeSubscriptionInterface, SubscriptionStatus } from "../../stripe-subscription";
+import { formatDate, useBillingFormatOptions } from "../utils";
 
 type SubscriptionSummaryCardProps = {
   subscriptions: StripeSubscriptionInterface[];
@@ -11,6 +13,9 @@ type SubscriptionSummaryCardProps = {
   onManageClick: () => void;
 };
 
+/** Statuses with a `billing.ui.subscription_status.*` label; anything else Stripe adds is shown raw. */
+const SUBSCRIPTION_STATUSES: string[] = Object.values(SubscriptionStatus);
+
 function getStatusBadgeVariant(status: SubscriptionStatus): "default" | "secondary" | "destructive" | "outline" {
   switch (status) {
     case SubscriptionStatus.ACTIVE:
@@ -26,22 +31,14 @@ function getStatusBadgeVariant(status: SubscriptionStatus): "default" | "seconda
   }
 }
 
-function formatDate(date: Date): string {
-  return new Date(date).toLocaleDateString(undefined, {
-    year: "numeric",
-    month: "short",
-    day: "numeric",
-  });
-}
-
-function formatPlanName(subscription: StripeSubscriptionInterface): string {
+function formatPlanName(subscription: StripeSubscriptionInterface, fallback: string): string {
   const productName = subscription.price?.product?.name || "";
   const nickname = subscription.price?.nickname || "";
 
   if (productName && nickname) {
     return `${productName} - ${nickname}`;
   }
-  return productName || nickname || "Subscription";
+  return productName || nickname || fallback;
 }
 
 export function SubscriptionSummaryCard({
@@ -50,11 +47,13 @@ export function SubscriptionSummaryCard({
   error,
   onManageClick,
 }: SubscriptionSummaryCardProps) {
+  const t = useTranslations();
+  const fmt = useBillingFormatOptions();
   if (loading) {
     return (
       <Card>
         <CardHeader className="flex flex-row items-center justify-between space-y-0 pb-2">
-          <CardTitle>Subscriptions</CardTitle>
+          <CardTitle>{t("billing.ui.subscriptions.title")}</CardTitle>
           <CreditCard className="h-4 w-4 text-muted-foreground" />
         </CardHeader>
         <CardContent>
@@ -70,7 +69,7 @@ export function SubscriptionSummaryCard({
     return (
       <Card>
         <CardHeader className="flex flex-row items-center justify-between space-y-0 pb-2">
-          <CardTitle>Subscriptions</CardTitle>
+          <CardTitle>{t("billing.ui.subscriptions.title")}</CardTitle>
           <CreditCard className="h-4 w-4 text-muted-foreground" />
         </CardHeader>
         <CardContent>
@@ -88,14 +87,14 @@ export function SubscriptionSummaryCard({
   return (
     <Card className="cursor-pointer hover:bg-accent/50 transition-colors" onClick={onManageClick}>
       <CardHeader className="flex flex-row items-center justify-between space-y-0 pb-2">
-        <CardTitle>Subscriptions</CardTitle>
+        <CardTitle>{t("billing.ui.subscriptions.title")}</CardTitle>
         <CreditCard className="h-4 w-4 text-muted-foreground" />
       </CardHeader>
       <CardContent>
         {subscriptions.length === 0 ? (
           <div className="space-y-2">
-            <p className="text-xl font-bold text-muted-foreground">No active plan</p>
-            <p className="text-xs text-muted-foreground">Subscribe to get started</p>
+            <p className="text-xl font-bold text-muted-foreground">{t("billing.ui.cards.subscriptions.empty_title")}</p>
+            <p className="text-xs text-muted-foreground">{t("billing.ui.cards.subscriptions.empty_description")}</p>
             <Button
               variant="outline"
               size="sm"
@@ -105,14 +104,16 @@ export function SubscriptionSummaryCard({
                 onManageClick();
               }}
             >
-              View Plans
+              {t("billing.ui.cards.subscriptions.view_plans")}
               <ChevronRight className="h-4 w-4 ms-1 rtl:rotate-180" />
             </Button>
           </div>
         ) : primarySubscription ? (
           <div className="space-y-2">
             <div className="flex items-center gap-2">
-              <p className="text-xl font-bold">{formatPlanName(primarySubscription)}</p>
+              <p className="text-xl font-bold">
+                {formatPlanName(primarySubscription, t("billing.ui.cards.subscriptions.fallback_name"))}
+              </p>
               <Badge
                 variant={
                   primarySubscription.cancelAtPeriodEnd
@@ -120,18 +121,30 @@ export function SubscriptionSummaryCard({
                     : getStatusBadgeVariant(primarySubscription.status)
                 }
               >
-                {primarySubscription.cancelAtPeriodEnd ? "Canceling" : primarySubscription.status}
+                {primarySubscription.cancelAtPeriodEnd
+                  ? t("billing.ui.cards.subscriptions.canceling")
+                  : SUBSCRIPTION_STATUSES.includes(primarySubscription.status)
+                    ? t(`billing.ui.subscription_status.${primarySubscription.status}`)
+                    : primarySubscription.status}
               </Badge>
             </div>
             <p className="text-xs text-muted-foreground">
               {!primarySubscription.price?.isTrial
-                ? `Ends on ${formatDate(primarySubscription.currentPeriodEnd)}`
+                ? t("billing.ui.cards.subscriptions.ends_on", {
+                    date: formatDate(primarySubscription.currentPeriodEnd, fmt),
+                  })
                 : primarySubscription.cancelAtPeriodEnd
-                  ? `Cancels on ${formatDate(primarySubscription.currentPeriodEnd)}`
-                  : `Renews on ${formatDate(primarySubscription.currentPeriodEnd)}`}
+                  ? t("billing.ui.cards.subscriptions.cancels_on", {
+                      date: formatDate(primarySubscription.currentPeriodEnd, fmt),
+                    })
+                  : t("billing.ui.cards.subscriptions.renews_on", {
+                      date: formatDate(primarySubscription.currentPeriodEnd, fmt),
+                    })}
             </p>
             {activeSubscriptions.length > 1 && (
-              <p className="text-xs text-muted-foreground">+{activeSubscriptions.length - 1} more subscription(s)</p>
+              <p className="text-xs text-muted-foreground">
+                {t("billing.ui.cards.subscriptions.more", { count: activeSubscriptions.length - 1 })}
+              </p>
             )}
           </div>
         ) : null}

package/src/features/billing/components/containers/BillingDashboardContainer.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import { useTranslations } from "next-intl";
 import { CreditCard, Loader2, Wallet } from "lucide-react";
 import { useSearchParams } from "next/navigation";
 import { useCallback, useEffect, useMemo, useState } from "react";
@@ -51,6 +52,7 @@ type ErrorState = {
 };
 
 export function BillingDashboardContainer() {
+  const t = useTranslations();
   const [data, setData] = useState<DataState>({
     customer: null,
     subscriptions: [],
@@ -68,6 +70,7 @@ export function BillingDashboardContainer() {
     usage: true,
   });
 
+  // Error state holds message keys; they are translated at render time.
   const [errors, setErrors] = useState<ErrorState>({
     customer: null,
     subscriptions: null,
@@ -118,7 +121,7 @@ export function BillingDashboardContainer() {
       if ((error as { status?: number })?.status === 404) {
         setNoCustomerExists(true);
       } else {
-        setErrors((prev) => ({ ...prev, customer: "Failed to load billing account" }));
+        setErrors((prev) => ({ ...prev, customer: "billing.ui.dashboard.errors.load_customer" }));
       }
     } finally {
       setLoading((prev) => ({ ...prev, customer: false }));
@@ -146,7 +149,7 @@ export function BillingDashboardContainer() {
         return subscriptions;
       } catch (error) {
         console.error("[BillingDashboard] Failed to load subscriptions:", error);
-        setErrors((prev) => ({ ...prev, subscriptions: "Failed to load subscriptions" }));
+        setErrors((prev) => ({ ...prev, subscriptions: "billing.ui.dashboard.errors.load_subscriptions" }));
         return [];
       } finally {
         setLoading((prev) => ({ ...prev, subscriptions: false }));
@@ -161,7 +164,7 @@ export function BillingDashboardContainer() {
         setErrors((prev) => ({ ...prev, paymentMethods: null }));
       } catch (error) {
         console.error("[BillingDashboard] Failed to load payment methods:", error);
-        setErrors((prev) => ({ ...prev, paymentMethods: "Failed to load payment methods" }));
+        setErrors((prev) => ({ ...prev, paymentMethods: "billing.ui.dashboard.errors.load_payment_methods" }));
       } finally {
         setLoading((prev) => ({ ...prev, paymentMethods: false }));
       }
@@ -175,7 +178,7 @@ export function BillingDashboardContainer() {
         setErrors((prev) => ({ ...prev, invoices: null }));
       } catch (error) {
         console.error("[BillingDashboard] Failed to load invoices:", error);
-        setErrors((prev) => ({ ...prev, invoices: "Failed to load invoices" }));
+        setErrors((prev) => ({ ...prev, invoices: "billing.ui.dashboard.errors.load_invoices" }));
       } finally {
         setLoading((prev) => ({ ...prev, invoices: false }));
       }
@@ -206,7 +209,7 @@ export function BillingDashboardContainer() {
       await fetchAllData();
     } catch (error) {
       console.error("[BillingDashboard] Failed to create customer:", error);
-      setErrors((prev) => ({ ...prev, customer: "Failed to set up billing" }));
+      setErrors((prev) => ({ ...prev, customer: "billing.ui.dashboard.errors.setup" }));
     } finally {
       setCreatingCustomer(false);
     }
@@ -242,7 +245,7 @@ export function BillingDashboardContainer() {
       setErrors((prev) => ({ ...prev, usage: null }));
     } catch (error) {
       console.error("[BillingDashboard] Failed to load usage data:", error);
-      setErrors((prev) => ({ ...prev, usage: "Failed to load usage data" }));
+      setErrors((prev) => ({ ...prev, usage: "billing.ui.dashboard.errors.load_usage" }));
     } finally {
       setLoading((prev) => ({ ...prev, usage: false }));
     }
@@ -311,13 +314,13 @@ export function BillingDashboardContainer() {
   const getModalTitle = (type: ModalType): string => {
     switch (type) {
       case "subscriptions":
-        return "Manage Subscriptions";
+        return t("billing.ui.dashboard.modal.subscriptions");
       case "payment-methods":
-        return "Payment Methods";
+        return t("billing.ui.payment_methods.title");
       case "invoices":
-        return "Invoice History";
+        return t("billing.ui.dashboard.modal.invoices");
       case "usage":
-        return "Usage Tracking";
+        return t("billing.ui.usage.title");
       default:
         return "";
     }
@@ -331,7 +334,7 @@ export function BillingDashboardContainer() {
       {/* Header */}
       <div className="flex items-center gap-x-3">
         <Wallet className="h-8 w-8" />
-        <h1 className="text-primary text-3xl font-semibold">Billing</h1>
+        <h1 className="text-primary text-3xl font-semibold">{t("billing.title")}</h1>
       </div>
 
       {/* Initial Loading State */}
@@ -350,27 +353,24 @@ export function BillingDashboardContainer() {
             <div className="mx-auto mb-4 flex h-16 w-16 items-center justify-center rounded-full bg-primary/10">
               <CreditCard className="h-8 w-8 text-primary" />
             </div>
-            <CardTitle>Set Up Billing</CardTitle>
-            <CardDescription>
-              Your company doesn&apos;t have a billing account yet. Set one up to manage subscriptions, payment methods,
-              and view invoices.
-            </CardDescription>
+            <CardTitle>{t("billing.ui.dashboard.setup_title")}</CardTitle>
+            <CardDescription>{t("billing.ui.dashboard.setup_description")}</CardDescription>
           </CardHeader>
           <CardContent className="flex justify-center pb-8">
             <Button onClick={handleCreateCustomer} disabled={creatingCustomer} size="lg">
               {creatingCustomer ? (
                 <>
                   <Loader2 className="me-2 h-4 w-4 animate-spin" />
-                  Setting up...
+                  {t("billing.ui.dashboard.setting_up")}
                 </>
               ) : (
-                "Set Up Billing Account"
+                t("billing.ui.dashboard.setup_button")
               )}
             </Button>
           </CardContent>
           {errors.customer && (
             <CardContent className="pt-0">
-              <p className="text-center text-destructive text-xs/relaxed">{errors.customer}</p>
+              <p className="text-center text-destructive text-xs/relaxed">{t(errors.customer)}</p>
             </CardContent>
           )}
         </Card>
@@ -394,7 +394,7 @@ export function BillingDashboardContainer() {
             <SubscriptionSummaryCard
               subscriptions={data.subscriptions}
               loading={loading.subscriptions}
-              error={errors.subscriptions || undefined}
+              error={errors.subscriptions ? t(errors.subscriptions) : undefined}
               onManageClick={() => {
                 if (data.subscriptions.length === 0) {
                   // No subscriptions - open wizard directly
@@ -410,20 +410,20 @@ export function BillingDashboardContainer() {
               paymentMethods={data.paymentMethods}
               defaultPaymentMethodId={data.customer?.defaultPaymentMethodId}
               loading={loading.paymentMethods}
-              error={errors.paymentMethods || undefined}
+              error={errors.paymentMethods ? t(errors.paymentMethods) : undefined}
               onManageClick={() => setActiveModal("payment-methods")}
             />
 
             <CustomerInfoCard
               customer={data.customer}
               loading={loading.customer}
-              error={errors.customer || undefined}
+              error={errors.customer ? t(errors.customer) : undefined}
             />
 
             <InvoicesSummaryCard
               invoices={data.invoices}
               loading={loading.invoices}
-              error={errors.invoices || undefined}
+              error={errors.invoices ? t(errors.invoices) : undefined}
               onViewAllClick={() => setActiveModal("invoices")}
             />
 
@@ -433,7 +433,7 @@ export function BillingDashboardContainer() {
                 meters={data.meters}
                 summaries={data.meterSummaries}
                 loading={loading.usage}
-                error={errors.usage || undefined}
+                error={errors.usage ? t(errors.usage) : undefined}
                 onViewDetailsClick={() => setActiveModal("usage")}
               />
             )}

package/src/features/billing/components/utils/__tests__/billing-formatters.spec.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "vitest";
+import { StripePriceInterface } from "../../../stripe-price/data/stripe-price.interface";
+import { formatCurrency, formatFixed, formatInterval } from "../currency";
+import { formatDate } from "../date";
+
+const price = (recurring?: { interval: string; intervalCount: number }, priceType = "recurring") =>
+  ({ priceType, recurring }) as unknown as StripePriceInterface;
+
+/** Echoes the key and values so a test can see exactly what was asked for. */
+const t = (key: string, values?: Record<string, any>) => (values ? `${key}|${JSON.stringify(values)}` : key);
+
+describe("formatInterval", () => {
+  it("keeps the English output when no translator is passed", () => {
+    expect(formatInterval(price(undefined, "one_time"))).toBe("one-time");
+    expect(formatInterval(price({ interval: "month", intervalCount: 1 }))).toBe("/month");
+    expect(formatInterval(price({ interval: "week", intervalCount: 2 }))).toBe("/2 weeks");
+  });
+
+  it("asks the translator for every word it emits", () => {
+    expect(formatInterval(price(undefined, "one_time"), { t })).toBe("billing.ui.interval.one_time");
+    expect(formatInterval(price({ interval: "day", intervalCount: 1 }), { t })).toBe("billing.ui.interval.per_day");
+    expect(formatInterval(price({ interval: "year", intervalCount: 1 }), { t })).toBe("billing.ui.interval.per_year");
+    expect(formatInterval(price({ interval: "month", intervalCount: 3 }), { t })).toBe(
+      'billing.ui.interval.per_months|{"count":3}',
+    );
+  });
+});
+
+describe("formatCurrency", () => {
+  it("keeps the en-US output and the $0.00 literal without a locale", () => {
+    expect(formatCurrency(999, "usd")).toBe("$9.99");
+    expect(formatCurrency(undefined, "usd")).toBe("$0.00");
+  });
+
+  it("formats with the given locale", () => {
+    expect(formatCurrency(999, "eur", { locale: "it" })).toMatch(/^9,99\s€$/);
+    expect(formatCurrency(undefined, "eur", { locale: "it" })).toMatch(/^0,00\s€$/);
+  });
+});
+
+describe("formatDate", () => {
+  const date = new Date(2025, 0, 15, 12);
+
+  it("keeps the English output without options", () => {
+    expect(formatDate(date)).toBe("Jan 15, 2025");
+    expect(formatDate(undefined)).toBe("N/A");
+    expect(formatDate(new Date("not a date"))).toBe("Invalid Date");
+  });
+
+  it("uses the locale and the translator when given", () => {
+    expect(formatDate(date, { locale: "it", t })).toBe("15 gen 2025");
+    expect(formatDate(undefined, { locale: "it", t })).toBe("billing.ui.not_available");
+    expect(formatDate(new Date("not a date"), { locale: "it", t })).toBe("billing.ui.invalid_date");
+  });
+});
+
+describe("formatFixed", () => {
+  it("matches toFixed in English and uses the locale's decimal separator otherwise", () => {
+    expect(formatFixed(12.345, "en", 1)).toBe((12.345).toFixed(1));
+    expect(formatFixed(1234.5, "en", 1)).toBe("1234.5");
+    expect(formatFixed(12.5, "it", 1)).toBe("12,5");
+  });
+});

package/src/features/billing/components/utils/currency.ts

@@ -1,11 +1,8 @@
 import { StripePriceInterface } from "../../stripe-price/data/stripe-price.interface";
+import { BillingFormatOptions, DEFAULT_BILLING_LOCALE } from "./format-options";
 
-/**
- * Format price recurring interval for display
- * @param price - Stripe price object
- * @returns Formatted interval string (e.g., "/month", "/year", "/2 weeks", "one-time")
- */
-export function formatInterval(price: StripePriceInterface): string {
+/** English output kept for callers that pass no translator. */
+function formatIntervalEnglish(price: StripePriceInterface): string {
   if (price.priceType === "one_time" || !price.recurring) {
     return "one-time";
   }
@@ -22,20 +19,68 @@ export function formatInterval(price: StripePriceInterface): string {
   return `/${intervalCount} ${pluralInterval}`;
 }
 
+/**
+ * Format price recurring interval for display
+ * @param price - Stripe price object
+ * @param options - `t` translates the interval words; without it the output is English
+ * @returns Formatted interval string (e.g., "/month", "/year", "/2 weeks", "one-time")
+ */
+export function formatInterval(price: StripePriceInterface, options: BillingFormatOptions = {}): string {
+  const { t } = options;
+  if (!t) return formatIntervalEnglish(price);
+
+  if (price.priceType === "one_time" || !price.recurring) {
+    return t("billing.ui.interval.one_time");
+  }
+
+  const { interval, intervalCount } = price.recurring;
+
+  if (intervalCount === 1) {
+    switch (interval) {
+      case "day":
+        return t("billing.ui.interval.per_day");
+      case "week":
+        return t("billing.ui.interval.per_week");
+      case "month":
+        return t("billing.ui.interval.per_month");
+      default:
+        return t("billing.ui.interval.per_year");
+    }
+  }
+
+  switch (interval) {
+    case "day":
+      return t("billing.ui.interval.per_days", { count: intervalCount });
+    case "week":
+      return t("billing.ui.interval.per_weeks", { count: intervalCount });
+    case "month":
+      return t("billing.ui.interval.per_months", { count: intervalCount });
+    default:
+      return t("billing.ui.interval.per_years", { count: intervalCount });
+  }
+}
+
 /**
  * Format currency amount from cents to localized currency string
  * @param amount - Amount in cents
  * @param currency - Currency code (e.g., "USD", "EUR", "GBP")
+ * @param options - `locale` drives number formatting; defaults to "en-US"
  * @returns Formatted currency string (e.g., "$9.99", "€9,99")
  */
-export function formatCurrency(amount: number | undefined, currency: string): string {
-  if (amount === undefined) return "$0.00";
+export function formatCurrency(
+  amount: number | undefined,
+  currency: string,
+  options: BillingFormatOptions = {},
+): string {
+  const { locale } = options;
+  // No locale: the historical literal. With one, zero goes through Intl like any amount.
+  if (amount === undefined && !locale) return "$0.00";
 
   // Convert cents to dollars
-  const dollars = amount / 100;
+  const dollars = (amount ?? 0) / 100;
 
   try {
-    return new Intl.NumberFormat("en-US", {
+    return new Intl.NumberFormat(locale ?? DEFAULT_BILLING_LOCALE, {
       style: "currency",
       currency: currency.toUpperCase(),
       minimumFractionDigits: 2,
@@ -47,3 +92,15 @@ export function formatCurrency(amount: number | undefined, currency: string): st
     return `$${dollars.toFixed(2)}`;
   }
 }
+
+/**
+ * `value.toFixed(digits)` with the locale's decimal separator ("12.5" in English,
+ * "12,5" in Italian). No grouping, so English output matches `toFixed` exactly.
+ */
+export function formatFixed(value: number, locale: string | undefined, digits: number): string {
+  return new Intl.NumberFormat(locale ?? DEFAULT_BILLING_LOCALE, {
+    minimumFractionDigits: digits,
+    maximumFractionDigits: digits,
+    useGrouping: false,
+  }).format(value);
+}

package/src/features/billing/components/utils/date.ts

@@ -1,21 +1,26 @@
+import { BillingFormatOptions, DEFAULT_BILLING_LOCALE } from "./format-options";
+
 /**
  * Format a date to a localized date string
  * @param date - Date object or ISO string
+ * @param options - `locale` drives the date format (default "en-US"); `t` translates the
+ *   placeholder shown for a missing or invalid date (default English)
  * @returns Formatted date string (e.g., "Jan 15, 2025")
  */
-export function formatDate(date: Date | string | undefined): string {
-  if (!date) return "N/A";
+export function formatDate(date: Date | string | undefined, options: BillingFormatOptions = {}): string {
+  const { locale, t } = options;
+  if (!date) return t ? t("billing.ui.not_available") : "N/A";
 
   const dateObj = typeof date === "string" ? new Date(date) : date;
 
   try {
-    return new Intl.DateTimeFormat("en-US", {
+    return new Intl.DateTimeFormat(locale ?? DEFAULT_BILLING_LOCALE, {
       month: "short",
       day: "numeric",
       year: "numeric",
     }).format(dateObj);
   } catch (error) {
     console.error("Error formatting date:", error);
-    return "Invalid Date";
+    return t ? t("billing.ui.invalid_date") : "Invalid Date";
   }
 }

package/src/features/billing/components/utils/format-options.ts

@@ -0,0 +1,20 @@
+/** A message translator, as returned by `useTranslations()`. */
+export type BillingTranslator = (key: string, values?: Record<string, any>) => string;
+
+/**
+ * What the billing formatters need from the caller's React context. The
+ * formatters are plain functions and cannot call hooks, so a component reads
+ * `useI18nLocale()` and `useTranslations()` and passes both here.
+ *
+ * Both are optional so existing callers keep their output: without a `locale`
+ * the formatters use "en-US", without `t` they return the English literals they
+ * always returned.
+ */
+export type BillingFormatOptions = {
+  /** BCP 47 locale for `Intl` (the app's active locale, from `useI18nLocale()`). */
+  locale?: string;
+  /** Translator for the words the formatters emit. */
+  t?: BillingTranslator;
+};
+
+export const DEFAULT_BILLING_LOCALE = "en-US";

package/src/features/billing/components/utils/index.ts

@@ -1,2 +1,4 @@
-export { formatCurrency, formatInterval } from "./currency";
+export { formatCurrency, formatFixed, formatInterval } from "./currency";
 export { formatDate } from "./date";
+export type { BillingFormatOptions, BillingTranslator } from "./format-options";
+export { useBillingFormatOptions } from "./useBillingFormatOptions";

package/src/features/billing/components/utils/useBillingFormatOptions.ts

@@ -0,0 +1,11 @@
+import { useTranslations } from "next-intl";
+import { useMemo } from "react";
+import { useI18nLocale } from "../../../../i18n";
+import { BillingFormatOptions } from "./format-options";
+
+/** The active locale and translator, ready to pass to the billing formatters. */
+export function useBillingFormatOptions(): Required<BillingFormatOptions> {
+  const t = useTranslations();
+  const locale = useI18nLocale();
+  return useMemo(() => ({ locale, t }), [locale, t]);
+}