feat(clerk-js): Pass locale to Stripe elements

.changeset/cold-bottles-watch.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/shared': patch
+---
+
+Propagate locale from ClerkProvider to PaymentElement

packages/clerk-js/src/core/clerk.ts

@@ -2420,6 +2420,7 @@ export class Clerk implements ClerkInterface {
  ..._props,
  options: this.#initOptions({ ...this.#options, ..._props.options }),
  };
+
  return this.#componentControls?.ensureMounted().then(controls => controls.updateProps(props));
  };
 

packages/shared/src/react/__tests__/commerce.test.tsx

@@ -0,0 +1,250 @@
+import { render, screen } from '@testing-library/react';
+import React from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { __experimental_PaymentElement, __experimental_PaymentElementProvider } from '../commerce';
+import { OptionsContext } from '../contexts';
+
+// Mock the Stripe components
+vi.mock('../stripe-react', () => ({
+ Elements: ({ children, options }: { children: React.ReactNode; options: any }) => (
+ <div
+ data-testid='stripe-elements'
+ data-locale={options.locale}
+ >
+ {children}
+ </div>
+ ),
+ PaymentElement: ({ fallback }: { fallback?: React.ReactNode }) => <div>{fallback}</div>,
+ useElements: () => null,
+ useStripe: () => null,
+}));
+
+// Mock the hooks
+const mockGetOption = vi.fn();
+vi.mock('../hooks/useClerk', () => ({
+ useClerk: () => ({
+ __internal_loadStripeJs: vi.fn().mockResolvedValue(() => Promise.resolve({})),
+ __internal_getOption: mockGetOption,
+ __unstable__environment: {
+ commerceSettings: {
+ billing: {
+ stripePublishableKey: 'pk_test_123',
+ },
+ },
+ displayConfig: {
+ userProfileUrl: 'https://example.com/profile',
+ organizationProfileUrl: 'https://example.com/org-profile',
+ },
+ },
+ }),
+}));
+
+vi.mock('../hooks/useUser', () => ({
+ useUser: () => ({
+ user: {
+ id: 'user_123',
+ initializePaymentSource: vi.fn().mockResolvedValue({
+ externalGatewayId: 'acct_123',
+ externalClientSecret: 'seti_123',
+ paymentMethodOrder: ['card'],
+ }),
+ },
+ }),
+}));
+
+vi.mock('../hooks/useOrganization', () => ({
+ useOrganization: () => ({
+ organization: null,
+ }),
+}));
+
+vi.mock('swr', () => ({
+ __esModule: true,
+ default: () => ({ data: { loadStripe: vi.fn().mockResolvedValue({}) } }),
+}));
+
+vi.mock('swr/mutation', () => ({
+ __esModule: true,
+ default: () => ({
+ data: {
+ externalGatewayId: 'acct_123',
+ externalClientSecret: 'seti_123',
+ paymentMethodOrder: ['card'],
+ },
+ trigger: vi.fn().mockResolvedValue({
+ externalGatewayId: 'acct_123',
+ externalClientSecret: 'seti_123',
+ paymentMethodOrder: ['card'],
+ }),
+ }),
+}));
+
+describe('PaymentElement Localization', () => {
+ const mockCheckout = {
+ id: 'checkout_123',
+ needsPaymentMethod: true,
+ plan: {
+ id: 'plan_123',
+ name: 'Test Plan',
+ description: 'Test plan description',
+ fee: { amount: 1000, amountFormatted: '$10.00', currency: 'usd', currencySymbol: '$' },
+ annualFee: { amount: 10000, amountFormatted: '$100.00', currency: 'usd', currencySymbol: '$' },
+ annualMonthlyFee: { amount: 833, amountFormatted: '$8.33', currency: 'usd', currencySymbol: '$' },
+ currency: 'usd',
+ interval: 'month' as const,
+ intervalCount: 1,
+ maxAllowedInstances: 1,
+ trialDays: 0,
+ isAddon: false,
+ isPopular: false,
+ isPerSeat: false,
+ isUsageBased: false,
+ isFree: false,
+ isLegacy: false,
+ isDefault: false,
+ isRecurring: true,
+ hasBaseFee: true,
+ forPayerType: 'user' as const,
+ publiclyVisible: true,
+ slug: 'test-plan',
+ avatarUrl: '',
+ freeTrialDays: 0,
+ freeTrialEnabled: false,
+ pathRoot: '/',
+ reload: vi.fn(),
+ features: [],
+ limits: {},
+ metadata: {},
+ },
+ totals: {
+ subtotal: { amount: 1000, amountFormatted: '$10.00', currency: 'usd', currencySymbol: '$' },
+ grandTotal: { amount: 1000, amountFormatted: '$10.00', currency: 'usd', currencySymbol: '$' },
+ taxTotal: { amount: 0, amountFormatted: '$0.00', currency: 'usd', currencySymbol: '$' },
+ totalDueNow: { amount: 1000, amountFormatted: '$10.00', currency: 'usd', currencySymbol: '$' },
+ credit: { amount: 0, amountFormatted: '$0.00', currency: 'usd', currencySymbol: '$' },
+ pastDue: { amount: 0, amountFormatted: '$0.00', currency: 'usd', currencySymbol: '$' },
+ },
+ status: 'needs_confirmation' as const,
+ error: null,
+ fetchStatus: 'idle' as const,
+ confirm: vi.fn(),
+ start: vi.fn(),
+ clear: vi.fn(),
+ finalize: vi.fn(),
+ getState: vi.fn(),
+ isConfirming: false,
+ isStarting: false,
+ planPeriod: 'month' as const,
+ externalClientSecret: 'seti_123',
+ externalGatewayId: 'acct_123',
+ isImmediatePlanChange: false,
+ paymentMethodOrder: ['card'],
+ freeTrialEndsAt: null,
+ payer: {
+ id: 'payer_123',
+ createdAt: new Date('2023-01-01'),
+ updatedAt: new Date('2023-01-01'),
+ imageUrl: null,
+ userId: 'user_123',
+ email: 'test@example.com',
+ firstName: 'Test',
+ lastName: 'User',
+ organizationId: undefined,
+ organizationName: undefined,
+ pathRoot: '/',
+ reload: vi.fn(),
+ },
+ };
+
+ const renderWithLocale = (locale: string) => {
+ // Mock the __internal_getOption to return the expected localization
+ mockGetOption.mockImplementation(key => {
+ if (key === 'localization') {
+ return { locale };
+ }
+ return undefined;
+ });
+
+ const options = {
+ localization: { locale },
+ };
+
+ return render(
+ <OptionsContext.Provider value={options}>
+ <__experimental_PaymentElementProvider checkout={mockCheckout}>
+ <__experimental_PaymentElement fallback={<div>Loading...</div>} />
+ </__experimental_PaymentElementProvider>
+ </OptionsContext.Provider>,
+ );
+ };
+
+ it('should pass the correct locale to Stripe Elements', () => {
+ renderWithLocale('es');
+
+ const elements = screen.getByTestId('stripe-elements');
+ expect(elements.getAttribute('data-locale')).toBe('es');
+ });
+
+ it('should default to "en" when no locale is provided', () => {
+ // Mock the __internal_getOption to return undefined for localization
+ mockGetOption.mockImplementation(key => {
+ if (key === 'localization') {
+ return undefined;
+ }
+ return undefined;
+ });
+
+ const options = {};
+
+ render(
+ <OptionsContext.Provider value={options}>
+ <__experimental_PaymentElementProvider checkout={mockCheckout}>
+ <__experimental_PaymentElement fallback={<div>Loading...</div>} />
+ </__experimental_PaymentElementProvider>
+ </OptionsContext.Provider>,
+ );
+
+ const elements = screen.getByTestId('stripe-elements');
+ expect(elements.getAttribute('data-locale')).toBe('en');
+ });
+
+ it('should normalize full locale strings to 2-letter codes for Stripe', () => {
+ const testCases = [
+ { input: 'en', expected: 'en' },
+ { input: 'en-US', expected: 'en' },
+ { input: 'fr-FR', expected: 'fr' },
+ { input: 'es-ES', expected: 'es' },
+ { input: 'de-DE', expected: 'de' },
+ { input: 'it-IT', expected: 'it' },
+ { input: 'pt-BR', expected: 'pt' },
+ ];
+
+ testCases.forEach(({ input, expected }) => {
+ // Mock the __internal_getOption to return the expected localization
+ mockGetOption.mockImplementation(key => {
+ if (key === 'localization') {
+ return { locale: input };
+ }
+ return undefined;
+ });
+
+ const options = {
+ localization: { locale: input },
+ };
+
+ const { unmount } = render(
+ <OptionsContext.Provider value={options}>
+ <__experimental_PaymentElementProvider checkout={mockCheckout}>
+ <__experimental_PaymentElement fallback={<div>Loading...</div>} />
+ </__experimental_PaymentElementProvider>
+ </OptionsContext.Provider>,
+ );
+
+ const elements = screen.getByTestId('stripe-elements');
+ expect(elements.getAttribute('data-locale')).toBe(expected);
+
+ unmount();
+ });
+ });
+});

packages/shared/src/react/commerce.tsx

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/consistent-type-imports */
-import type { Stripe, StripeElements } from '@stripe/stripe-js';
+import type { Stripe, StripeElements, StripeElementsOptions } from '@stripe/stripe-js';
 import React, { type PropsWithChildren, type ReactNode, useCallback, useEffect, useMemo, useState } from 'react';
 import useSWR from 'swr';
 import useSWRMutation from 'swr/mutation';
@@ -62,6 +62,23 @@ const useInternalEnvironment = () => {
  return clerk.__unstable__environment as unknown as EnvironmentResource | null | undefined;
 };
 
+const useLocalization = () => {
+ const clerk = useClerk();
+
+ let locale = 'en';
+ try {
+ const localization = clerk.__internal_getOption('localization');
+ locale = localization?.locale || 'en';
+ } catch {
+ // ignore errors
+ }
+
+ // Normalize locale to 2-letter language code for Stripe compatibility
+ const normalizedLocale = locale.split('-')[0];
+
+ return normalizedLocale;
+};
+
 const usePaymentSourceUtils = (forResource: ForPayerType = 'user') => {
  const { organization } = useOrganization();
  const { user } = useUser();
@@ -206,6 +223,7 @@ const PaymentElementProvider = ({ children, ...props }: PropsWithChildren<Paymen
 
 const PaymentElementInternalRoot = (props: PropsWithChildren) => {
  const { stripe, externalClientSecret, stripeAppearance } = usePaymentElementContext();
+ const locale = useLocalization();
 
  if (stripe && externalClientSecret) {
  return (
@@ -219,6 +237,7 @@ const PaymentElementInternalRoot = (props: PropsWithChildren) => {
  appearance: {
  variables: stripeAppearance,
  },
+ locale: locale as StripeElementsOptions['locale'],
  }}
  >
  <ValidateStripeUtils>{props.children}</ValidateStripeUtils>

.changeset/cold-bottles-watch.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/shared': patch
+---
+
+Propagate locale from ClerkProvider to PaymentElement

packages/clerk-js/src/core/clerk.ts

@@ -2420,6 +2420,7 @@ export class Clerk implements ClerkInterface {
  ..._props,
  options: this.#initOptions({ ...this.#options, ..._props.options }),
  };
+
  return this.#componentControls?.ensureMounted().then(controls => controls.updateProps(props));
  };
 

packages/shared/src/react/__tests__/commerce.test.tsx

@@ -0,0 +1,250 @@
+import { render, screen } from '@testing-library/react';
+import React from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { __experimental_PaymentElement, __experimental_PaymentElementProvider } from '../commerce';
+import { OptionsContext } from '../contexts';
+
+// Mock the Stripe components
+vi.mock('../stripe-react', () => ({
+ Elements: ({ children, options }: { children: React.ReactNode; options: any }) => (
+ <div
+ data-testid='stripe-elements'
+ data-locale={options.locale}
+ >
+ {children}
+ </div>
+ ),
+ PaymentElement: ({ fallback }: { fallback?: React.ReactNode }) => <div>{fallback}</div>,
+ useElements: () => null,
+ useStripe: () => null,
+}));
+
+// Mock the hooks
+const mockGetOption = vi.fn();
+vi.mock('../hooks/useClerk', () => ({
+ useClerk: () => ({
+ __internal_loadStripeJs: vi.fn().mockResolvedValue(() => Promise.resolve({})),
+ __internal_getOption: mockGetOption,
+ __unstable__environment: {
+ commerceSettings: {
+ billing: {
+ stripePublishableKey: 'pk_test_123',
+ },
+ },
+ displayConfig: {
+ userProfileUrl: 'https://example.com/profile',
+ organizationProfileUrl: 'https://example.com/org-profile',
+ },
+ },
+ }),
+}));
+
+vi.mock('../hooks/useUser', () => ({
+ useUser: () => ({
+ user: {
+ id: 'user_123',
+ initializePaymentSource: vi.fn().mockResolvedValue({
+ externalGatewayId: 'acct_123',
+ externalClientSecret: 'seti_123',
+ paymentMethodOrder: ['card'],
+ }),
+ },
+ }),
+}));
+
+vi.mock('../hooks/useOrganization', () => ({
+ useOrganization: () => ({
+ organization: null,
+ }),
+}));
+
+vi.mock('swr', () => ({
+ __esModule: true,
+ default: () => ({ data: { loadStripe: vi.fn().mockResolvedValue({}) } }),
+}));
+
+vi.mock('swr/mutation', () => ({
+ __esModule: true,
+ default: () => ({
+ data: {
+ externalGatewayId: 'acct_123',
+ externalClientSecret: 'seti_123',
+ paymentMethodOrder: ['card'],
+ },
+ trigger: vi.fn().mockResolvedValue({
+ externalGatewayId: 'acct_123',
+ externalClientSecret: 'seti_123',
+ paymentMethodOrder: ['card'],
+ }),
+ }),
+}));
+
+describe('PaymentElement Localization', () => {
+ const mockCheckout = {
+ id: 'checkout_123',
+ needsPaymentMethod: true,
+ plan: {
+ id: 'plan_123',
+ name: 'Test Plan',
+ description: 'Test plan description',
+ fee: { amount: 1000, amountFormatted: '$10.00', currency: 'usd', currencySymbol: '$' },
+ annualFee: { amount: 10000, amountFormatted: '$100.00', currency: 'usd', currencySymbol: '$' },
+ annualMonthlyFee: { amount: 833, amountFormatted: '$8.33', currency: 'usd', currencySymbol: '$' },
+ currency: 'usd',
+ interval: 'month' as const,
+ intervalCount: 1,
+ maxAllowedInstances: 1,
+ trialDays: 0,
+ isAddon: false,
+ isPopular: false,
+ isPerSeat: false,
+ isUsageBased: false,
+ isFree: false,
+ isLegacy: false,
+ isDefault: false,
+ isRecurring: true,
+ hasBaseFee: true,
+ forPayerType: 'user' as const,
+ publiclyVisible: true,
+ slug: 'test-plan',
+ avatarUrl: '',
+ freeTrialDays: 0,
+ freeTrialEnabled: false,
+ pathRoot: '/',
+ reload: vi.fn(),
+ features: [],
+ limits: {},
+ metadata: {},
+ },
+ totals: {
+ subtotal: { amount: 1000, amountFormatted: '$10.00', currency: 'usd', currencySymbol: '$' },
+ grandTotal: { amount: 1000, amountFormatted: '$10.00', currency: 'usd', currencySymbol: '$' },
+ taxTotal: { amount: 0, amountFormatted: '$0.00', currency: 'usd', currencySymbol: '$' },
+ totalDueNow: { amount: 1000, amountFormatted: '$10.00', currency: 'usd', currencySymbol: '$' },
+ credit: { amount: 0, amountFormatted: '$0.00', currency: 'usd', currencySymbol: '$' },
+ pastDue: { amount: 0, amountFormatted: '$0.00', currency: 'usd', currencySymbol: '$' },
+ },
+ status: 'needs_confirmation' as const,
+ error: null,
+ fetchStatus: 'idle' as const,
+ confirm: vi.fn(),
+ start: vi.fn(),
+ clear: vi.fn(),
+ finalize: vi.fn(),
+ getState: vi.fn(),
+ isConfirming: false,
+ isStarting: false,
+ planPeriod: 'month' as const,
+ externalClientSecret: 'seti_123',
+ externalGatewayId: 'acct_123',
+ isImmediatePlanChange: false,
+ paymentMethodOrder: ['card'],
+ freeTrialEndsAt: null,
+ payer: {
+ id: 'payer_123',
+ createdAt: new Date('2023-01-01'),
+ updatedAt: new Date('2023-01-01'),
+ imageUrl: null,
+ userId: 'user_123',
+ email: 'test@example.com',
+ firstName: 'Test',
+ lastName: 'User',
+ organizationId: undefined,
+ organizationName: undefined,
+ pathRoot: '/',
+ reload: vi.fn(),
+ },
+ };
+
+ const renderWithLocale = (locale: string) => {
+ // Mock the __internal_getOption to return the expected localization
+ mockGetOption.mockImplementation(key => {
+ if (key === 'localization') {
+ return { locale };
+ }
+ return undefined;
+ });
+
+ const options = {
+ localization: { locale },
+ };
+
+ return render(
+ <OptionsContext.Provider value={options}>
+ <__experimental_PaymentElementProvider checkout={mockCheckout}>
+ <__experimental_PaymentElement fallback={<div>Loading...</div>} />
+ </__experimental_PaymentElementProvider>
+ </OptionsContext.Provider>,
+ );
+ };
+
+ it('should pass the correct locale to Stripe Elements', () => {
+ renderWithLocale('es');
+
+ const elements = screen.getByTestId('stripe-elements');
+ expect(elements.getAttribute('data-locale')).toBe('es');
+ });
+
+ it('should default to "en" when no locale is provided', () => {
+ // Mock the __internal_getOption to return undefined for localization
+ mockGetOption.mockImplementation(key => {
+ if (key === 'localization') {
+ return undefined;
+ }
+ return undefined;
+ });
+
+ const options = {};
+
+ render(
+ <OptionsContext.Provider value={options}>
+ <__experimental_PaymentElementProvider checkout={mockCheckout}>
+ <__experimental_PaymentElement fallback={<div>Loading...</div>} />
+ </__experimental_PaymentElementProvider>
+ </OptionsContext.Provider>,
+ );
+
+ const elements = screen.getByTestId('stripe-elements');
+ expect(elements.getAttribute('data-locale')).toBe('en');
+ });
+
+ it('should normalize full locale strings to 2-letter codes for Stripe', () => {
+ const testCases = [
+ { input: 'en', expected: 'en' },
+ { input: 'en-US', expected: 'en' },
+ { input: 'fr-FR', expected: 'fr' },
+ { input: 'es-ES', expected: 'es' },
+ { input: 'de-DE', expected: 'de' },
+ { input: 'it-IT', expected: 'it' },
+ { input: 'pt-BR', expected: 'pt' },
+ ];
+
+ testCases.forEach(({ input, expected }) => {
+ // Mock the __internal_getOption to return the expected localization
+ mockGetOption.mockImplementation(key => {
+ if (key === 'localization') {
+ return { locale: input };
+ }
+ return undefined;
+ });
+
+ const options = {
+ localization: { locale: input },
+ };
+
+ const { unmount } = render(
+ <OptionsContext.Provider value={options}>
+ <__experimental_PaymentElementProvider checkout={mockCheckout}>
+ <__experimental_PaymentElement fallback={<div>Loading...</div>} />
+ </__experimental_PaymentElementProvider>
+ </OptionsContext.Provider>,
+ );
+
+ const elements = screen.getByTestId('stripe-elements');
+ expect(elements.getAttribute('data-locale')).toBe(expected);
+
+ unmount();
+ });
+ });
+});

packages/shared/src/react/commerce.tsx

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/consistent-type-imports */
-import type { Stripe, StripeElements } from '@stripe/stripe-js';
+import type { Stripe, StripeElements, StripeElementsOptions } from '@stripe/stripe-js';
 import React, { type PropsWithChildren, type ReactNode, useCallback, useEffect, useMemo, useState } from 'react';
 import useSWR from 'swr';
 import useSWRMutation from 'swr/mutation';
@@ -62,6 +62,23 @@ const useInternalEnvironment = () => {
  return clerk.__unstable__environment as unknown as EnvironmentResource | null | undefined;
 };
 
+const useLocalization = () => {
+ const clerk = useClerk();
+
+ let locale = 'en';
+ try {
+ const localization = clerk.__internal_getOption('localization');
+ locale = localization?.locale || 'en';
+ } catch {
+ // ignore errors
+ }
+
+ // Normalize locale to 2-letter language code for Stripe compatibility
+ const normalizedLocale = locale.split('-')[0];
+
+ return normalizedLocale;
+};
+
 const usePaymentSourceUtils = (forResource: ForPayerType = 'user') => {
  const { organization } = useOrganization();
  const { user } = useUser();
@@ -206,6 +223,7 @@ const PaymentElementProvider = ({ children, ...props }: PropsWithChildren<Paymen
 
 const PaymentElementInternalRoot = (props: PropsWithChildren) => {
  const { stripe, externalClientSecret, stripeAppearance } = usePaymentElementContext();
+ const locale = useLocalization();
 
  if (stripe && externalClientSecret) {
  return (
@@ -219,6 +237,7 @@ const PaymentElementInternalRoot = (props: PropsWithChildren) => {
  appearance: {
  variables: stripeAppearance,
  },
+ locale: locale as StripeElementsOptions['locale'],
  }}
  >
  <ValidateStripeUtils>{props.children}</ValidateStripeUtils>

.changeset/cold-bottles-watch.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/shared': patch
+---
+
+Propagate locale from ClerkProvider to PaymentElement

packages/clerk-js/src/core/clerk.ts

@@ -2420,6 +2420,7 @@ export class Clerk implements ClerkInterface {
  ..._props,
  options: this.#initOptions({ ...this.#options, ..._props.options }),
  };
+
  return this.#componentControls?.ensureMounted().then(controls => controls.updateProps(props));
  };
 

packages/shared/src/react/__tests__/commerce.test.tsx

@@ -0,0 +1,250 @@
+import { render, screen } from '@testing-library/react';
+import React from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { __experimental_PaymentElement, __experimental_PaymentElementProvider } from '../commerce';
+import { OptionsContext } from '../contexts';
+
+// Mock the Stripe components
+vi.mock('../stripe-react', () => ({
+ Elements: ({ children, options }: { children: React.ReactNode; options: any }) => (
+ <div
+ data-testid='stripe-elements'
+ data-locale={options.locale}
+ >
+ {children}
+ </div>
+ ),
+ PaymentElement: ({ fallback }: { fallback?: React.ReactNode }) => <div>{fallback}</div>,
+ useElements: () => null,
+ useStripe: () => null,
+}));
+
+// Mock the hooks
+const mockGetOption = vi.fn();
+vi.mock('../hooks/useClerk', () => ({
+ useClerk: () => ({
+ __internal_loadStripeJs: vi.fn().mockResolvedValue(() => Promise.resolve({})),
+ __internal_getOption: mockGetOption,
+ __unstable__environment: {
+ commerceSettings: {
+ billing: {
+ stripePublishableKey: 'pk_test_123',
+ },
+ },
+ displayConfig: {
+ userProfileUrl: 'https://example.com/profile',
+ organizationProfileUrl: 'https://example.com/org-profile',
+ },
+ },
+ }),
+}));
+
+vi.mock('../hooks/useUser', () => ({
+ useUser: () => ({
+ user: {
+ id: 'user_123',
+ initializePaymentSource: vi.fn().mockResolvedValue({
+ externalGatewayId: 'acct_123',
+ externalClientSecret: 'seti_123',
+ paymentMethodOrder: ['card'],
+ }),
+ },
+ }),
+}));
+
+vi.mock('../hooks/useOrganization', () => ({
+ useOrganization: () => ({
+ organization: null,
+ }),
+}));
+
+vi.mock('swr', () => ({
+ __esModule: true,
+ default: () => ({ data: { loadStripe: vi.fn().mockResolvedValue({}) } }),
+}));
+
+vi.mock('swr/mutation', () => ({
+ __esModule: true,
+ default: () => ({
+ data: {
+ externalGatewayId: 'acct_123',
+ externalClientSecret: 'seti_123',
+ paymentMethodOrder: ['card'],
+ },
+ trigger: vi.fn().mockResolvedValue({
+ externalGatewayId: 'acct_123',
+ externalClientSecret: 'seti_123',
+ paymentMethodOrder: ['card'],
+ }),
+ }),
+}));
+
+describe('PaymentElement Localization', () => {
+ const mockCheckout = {
+ id: 'checkout_123',
+ needsPaymentMethod: true,
+ plan: {
+ id: 'plan_123',
+ name: 'Test Plan',
+ description: 'Test plan description',
+ fee: { amount: 1000, amountFormatted: '$10.00', currency: 'usd', currencySymbol: '$' },
+ annualFee: { amount: 10000, amountFormatted: '$100.00', currency: 'usd', currencySymbol: '$' },
+ annualMonthlyFee: { amount: 833, amountFormatted: '$8.33', currency: 'usd', currencySymbol: '$' },
+ currency: 'usd',
+ interval: 'month' as const,
+ intervalCount: 1,
+ maxAllowedInstances: 1,
+ trialDays: 0,
+ isAddon: false,
+ isPopular: false,
+ isPerSeat: false,
+ isUsageBased: false,
+ isFree: false,
+ isLegacy: false,
+ isDefault: false,
+ isRecurring: true,
+ hasBaseFee: true,
+ forPayerType: 'user' as const,
+ publiclyVisible: true,
+ slug: 'test-plan',
+ avatarUrl: '',
+ freeTrialDays: 0,
+ freeTrialEnabled: false,
+ pathRoot: '/',
+ reload: vi.fn(),
+ features: [],
+ limits: {},
+ metadata: {},
+ },
+ totals: {
+ subtotal: { amount: 1000, amountFormatted: '$10.00', currency: 'usd', currencySymbol: '$' },
+ grandTotal: { amount: 1000, amountFormatted: '$10.00', currency: 'usd', currencySymbol: '$' },
+ taxTotal: { amount: 0, amountFormatted: '$0.00', currency: 'usd', currencySymbol: '$' },
+ totalDueNow: { amount: 1000, amountFormatted: '$10.00', currency: 'usd', currencySymbol: '$' },
+ credit: { amount: 0, amountFormatted: '$0.00', currency: 'usd', currencySymbol: '$' },
+ pastDue: { amount: 0, amountFormatted: '$0.00', currency: 'usd', currencySymbol: '$' },
+ },
+ status: 'needs_confirmation' as const,
+ error: null,
+ fetchStatus: 'idle' as const,
+ confirm: vi.fn(),
+ start: vi.fn(),
+ clear: vi.fn(),
+ finalize: vi.fn(),
+ getState: vi.fn(),
+ isConfirming: false,
+ isStarting: false,
+ planPeriod: 'month' as const,
+ externalClientSecret: 'seti_123',
+ externalGatewayId: 'acct_123',
+ isImmediatePlanChange: false,
+ paymentMethodOrder: ['card'],
+ freeTrialEndsAt: null,
+ payer: {
+ id: 'payer_123',
+ createdAt: new Date('2023-01-01'),
+ updatedAt: new Date('2023-01-01'),
+ imageUrl: null,
+ userId: 'user_123',
+ email: 'test@example.com',
+ firstName: 'Test',
+ lastName: 'User',
+ organizationId: undefined,
+ organizationName: undefined,
+ pathRoot: '/',
+ reload: vi.fn(),
+ },
+ };
+
+ const renderWithLocale = (locale: string) => {
+ // Mock the __internal_getOption to return the expected localization
+ mockGetOption.mockImplementation(key => {
+ if (key === 'localization') {
+ return { locale };
+ }
+ return undefined;
+ });
+
+ const options = {
+ localization: { locale },
+ };
+
+ return render(
+ <OptionsContext.Provider value={options}>
+ <__experimental_PaymentElementProvider checkout={mockCheckout}>
+ <__experimental_PaymentElement fallback={<div>Loading...</div>} />
+ </__experimental_PaymentElementProvider>
+ </OptionsContext.Provider>,
+ );
+ };
+
+ it('should pass the correct locale to Stripe Elements', () => {
+ renderWithLocale('es');
+
+ const elements = screen.getByTestId('stripe-elements');
+ expect(elements.getAttribute('data-locale')).toBe('es');
+ });
+
+ it('should default to "en" when no locale is provided', () => {
+ // Mock the __internal_getOption to return undefined for localization
+ mockGetOption.mockImplementation(key => {
+ if (key === 'localization') {
+ return undefined;
+ }
+ return undefined;
+ });
+
+ const options = {};
+
+ render(
+ <OptionsContext.Provider value={options}>
+ <__experimental_PaymentElementProvider checkout={mockCheckout}>
+ <__experimental_PaymentElement fallback={<div>Loading...</div>} />
+ </__experimental_PaymentElementProvider>
+ </OptionsContext.Provider>,
+ );
+
+ const elements = screen.getByTestId('stripe-elements');
+ expect(elements.getAttribute('data-locale')).toBe('en');
+ });
+
+ it('should normalize full locale strings to 2-letter codes for Stripe', () => {
+ const testCases = [
+ { input: 'en', expected: 'en' },
+ { input: 'en-US', expected: 'en' },
+ { input: 'fr-FR', expected: 'fr' },
+ { input: 'es-ES', expected: 'es' },
+ { input: 'de-DE', expected: 'de' },
+ { input: 'it-IT', expected: 'it' },
+ { input: 'pt-BR', expected: 'pt' },
+ ];
+
+ testCases.forEach(({ input, expected }) => {
+ // Mock the __internal_getOption to return the expected localization
+ mockGetOption.mockImplementation(key => {
+ if (key === 'localization') {
+ return { locale: input };
+ }
+ return undefined;
+ });
+
+ const options = {
+ localization: { locale: input },
+ };
+
+ const { unmount } = render(
+ <OptionsContext.Provider value={options}>
+ <__experimental_PaymentElementProvider checkout={mockCheckout}>
+ <__experimental_PaymentElement fallback={<div>Loading...</div>} />
+ </__experimental_PaymentElementProvider>
+ </OptionsContext.Provider>,
+ );
+
+ const elements = screen.getByTestId('stripe-elements');
+ expect(elements.getAttribute('data-locale')).toBe(expected);
+
+ unmount();
+ });
+ });
+});

packages/shared/src/react/commerce.tsx

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/consistent-type-imports */
-import type { Stripe, StripeElements } from '@stripe/stripe-js';
+import type { Stripe, StripeElements, StripeElementsOptions } from '@stripe/stripe-js';
 import React, { type PropsWithChildren, type ReactNode, useCallback, useEffect, useMemo, useState } from 'react';
 import useSWR from 'swr';
 import useSWRMutation from 'swr/mutation';
@@ -62,6 +62,23 @@ const useInternalEnvironment = () => {
  return clerk.__unstable__environment as unknown as EnvironmentResource | null | undefined;
 };
 
+const useLocalization = () => {
+ const clerk = useClerk();
+
+ let locale = 'en';
+ try {
+ const localization = clerk.__internal_getOption('localization');
+ locale = localization?.locale || 'en';
+ } catch {
+ // ignore errors
+ }
+
+ // Normalize locale to 2-letter language code for Stripe compatibility
+ const normalizedLocale = locale.split('-')[0];
+
+ return normalizedLocale;
+};
+
 const usePaymentSourceUtils = (forResource: ForPayerType = 'user') => {
  const { organization } = useOrganization();
  const { user } = useUser();
@@ -206,6 +223,7 @@ const PaymentElementProvider = ({ children, ...props }: PropsWithChildren<Paymen
 
 const PaymentElementInternalRoot = (props: PropsWithChildren) => {
  const { stripe, externalClientSecret, stripeAppearance } = usePaymentElementContext();
+ const locale = useLocalization();
 
  if (stripe && externalClientSecret) {
  return (
@@ -219,6 +237,7 @@ const PaymentElementInternalRoot = (props: PropsWithChildren) => {
  appearance: {
  variables: stripeAppearance,
  },
+ locale: locale as StripeElementsOptions['locale'],
  }}
  >
  <ValidateStripeUtils>{props.children}</ValidateStripeUtils>

.changeset/cold-bottles-watch.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/shared': patch
+---
+
+Propagate locale from ClerkProvider to PaymentElement

packages/clerk-js/src/core/clerk.ts

@@ -2420,6 +2420,7 @@ export class Clerk implements ClerkInterface {
  ..._props,
  options: this.#initOptions({ ...this.#options, ..._props.options }),
  };
+
  return this.#componentControls?.ensureMounted().then(controls => controls.updateProps(props));
  };
 

packages/shared/src/react/__tests__/commerce.test.tsx

@@ -0,0 +1,250 @@
+import { render, screen } from '@testing-library/react';
+import React from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { __experimental_PaymentElement, __experimental_PaymentElementProvider } from '../commerce';
+import { OptionsContext } from '../contexts';
+
+// Mock the Stripe components
+vi.mock('../stripe-react', () => ({
+ Elements: ({ children, options }: { children: React.ReactNode; options: any }) => (
+ <div
+ data-testid='stripe-elements'
+ data-locale={options.locale}
+ >
+ {children}
+ </div>
+ ),
+ PaymentElement: ({ fallback }: { fallback?: React.ReactNode }) => <div>{fallback}</div>,
+ useElements: () => null,
+ useStripe: () => null,
+}));
+
+// Mock the hooks
+const mockGetOption = vi.fn();
+vi.mock('../hooks/useClerk', () => ({
+ useClerk: () => ({
+ __internal_loadStripeJs: vi.fn().mockResolvedValue(() => Promise.resolve({})),
+ __internal_getOption: mockGetOption,
+ __unstable__environment: {
+ commerceSettings: {
+ billing: {
+ stripePublishableKey: 'pk_test_123',
+ },
+ },
+ displayConfig: {
+ userProfileUrl: 'https://example.com/profile',
+ organizationProfileUrl: 'https://example.com/org-profile',
+ },
+ },
+ }),
+}));
+
+vi.mock('../hooks/useUser', () => ({
+ useUser: () => ({
+ user: {
+ id: 'user_123',
+ initializePaymentSource: vi.fn().mockResolvedValue({
+ externalGatewayId: 'acct_123',
+ externalClientSecret: 'seti_123',
+ paymentMethodOrder: ['card'],
+ }),
+ },
+ }),
+}));
+
+vi.mock('../hooks/useOrganization', () => ({
+ useOrganization: () => ({
+ organization: null,
+ }),
+}));
+
+vi.mock('swr', () => ({
+ __esModule: true,
+ default: () => ({ data: { loadStripe: vi.fn().mockResolvedValue({}) } }),
+}));
+
+vi.mock('swr/mutation', () => ({
+ __esModule: true,
+ default: () => ({
+ data: {
+ externalGatewayId: 'acct_123',
+ externalClientSecret: 'seti_123',
+ paymentMethodOrder: ['card'],
+ },
+ trigger: vi.fn().mockResolvedValue({
+ externalGatewayId: 'acct_123',
+ externalClientSecret: 'seti_123',
+ paymentMethodOrder: ['card'],
+ }),
+ }),
+}));
+
+describe('PaymentElement Localization', () => {
+ const mockCheckout = {
+ id: 'checkout_123',
+ needsPaymentMethod: true,
+ plan: {
+ id: 'plan_123',
+ name: 'Test Plan',
+ description: 'Test plan description',
+ fee: { amount: 1000, amountFormatted: '$10.00', currency: 'usd', currencySymbol: '$' },
+ annualFee: { amount: 10000, amountFormatted: '$100.00', currency: 'usd', currencySymbol: '$' },
+ annualMonthlyFee: { amount: 833, amountFormatted: '$8.33', currency: 'usd', currencySymbol: '$' },
+ currency: 'usd',
+ interval: 'month' as const,
+ intervalCount: 1,
+ maxAllowedInstances: 1,
+ trialDays: 0,
+ isAddon: false,
+ isPopular: false,
+ isPerSeat: false,
+ isUsageBased: false,
+ isFree: false,
+ isLegacy: false,
+ isDefault: false,
+ isRecurring: true,
+ hasBaseFee: true,
+ forPayerType: 'user' as const,
+ publiclyVisible: true,
+ slug: 'test-plan',
+ avatarUrl: '',
+ freeTrialDays: 0,
+ freeTrialEnabled: false,
+ pathRoot: '/',
+ reload: vi.fn(),
+ features: [],
+ limits: {},
+ metadata: {},
+ },
+ totals: {
+ subtotal: { amount: 1000, amountFormatted: '$10.00', currency: 'usd', currencySymbol: '$' },
+ grandTotal: { amount: 1000, amountFormatted: '$10.00', currency: 'usd', currencySymbol: '$' },
+ taxTotal: { amount: 0, amountFormatted: '$0.00', currency: 'usd', currencySymbol: '$' },
+ totalDueNow: { amount: 1000, amountFormatted: '$10.00', currency: 'usd', currencySymbol: '$' },
+ credit: { amount: 0, amountFormatted: '$0.00', currency: 'usd', currencySymbol: '$' },
+ pastDue: { amount: 0, amountFormatted: '$0.00', currency: 'usd', currencySymbol: '$' },
+ },
+ status: 'needs_confirmation' as const,
+ error: null,
+ fetchStatus: 'idle' as const,
+ confirm: vi.fn(),
+ start: vi.fn(),
+ clear: vi.fn(),
+ finalize: vi.fn(),
+ getState: vi.fn(),
+ isConfirming: false,
+ isStarting: false,
+ planPeriod: 'month' as const,
+ externalClientSecret: 'seti_123',
+ externalGatewayId: 'acct_123',
+ isImmediatePlanChange: false,
+ paymentMethodOrder: ['card'],
+ freeTrialEndsAt: null,
+ payer: {
+ id: 'payer_123',
+ createdAt: new Date('2023-01-01'),
+ updatedAt: new Date('2023-01-01'),
+ imageUrl: null,
+ userId: 'user_123',
+ email: 'test@example.com',
+ firstName: 'Test',
+ lastName: 'User',
+ organizationId: undefined,
+ organizationName: undefined,
+ pathRoot: '/',
+ reload: vi.fn(),
+ },
+ };
+
+ const renderWithLocale = (locale: string) => {
+ // Mock the __internal_getOption to return the expected localization
+ mockGetOption.mockImplementation(key => {
+ if (key === 'localization') {
+ return { locale };
+ }
+ return undefined;
+ });
+
+ const options = {
+ localization: { locale },
+ };
+
+ return render(
+ <OptionsContext.Provider value={options}>
+ <__experimental_PaymentElementProvider checkout={mockCheckout}>
+ <__experimental_PaymentElement fallback={<div>Loading...</div>} />
+ </__experimental_PaymentElementProvider>
+ </OptionsContext.Provider>,
+ );
+ };
+
+ it('should pass the correct locale to Stripe Elements', () => {
+ renderWithLocale('es');
+
+ const elements = screen.getByTestId('stripe-elements');
+ expect(elements.getAttribute('data-locale')).toBe('es');
+ });
+
+ it('should default to "en" when no locale is provided', () => {
+ // Mock the __internal_getOption to return undefined for localization
+ mockGetOption.mockImplementation(key => {
+ if (key === 'localization') {
+ return undefined;
+ }
+ return undefined;
+ });
+
+ const options = {};
+
+ render(
+ <OptionsContext.Provider value={options}>
+ <__experimental_PaymentElementProvider checkout={mockCheckout}>
+ <__experimental_PaymentElement fallback={<div>Loading...</div>} />
+ </__experimental_PaymentElementProvider>
+ </OptionsContext.Provider>,
+ );
+
+ const elements = screen.getByTestId('stripe-elements');
+ expect(elements.getAttribute('data-locale')).toBe('en');
+ });
+
+ it('should normalize full locale strings to 2-letter codes for Stripe', () => {
+ const testCases = [
+ { input: 'en', expected: 'en' },
+ { input: 'en-US', expected: 'en' },
+ { input: 'fr-FR', expected: 'fr' },
+ { input: 'es-ES', expected: 'es' },
+ { input: 'de-DE', expected: 'de' },
+ { input: 'it-IT', expected: 'it' },
+ { input: 'pt-BR', expected: 'pt' },
+ ];
+
+ testCases.forEach(({ input, expected }) => {
+ // Mock the __internal_getOption to return the expected localization
+ mockGetOption.mockImplementation(key => {
+ if (key === 'localization') {
+ return { locale: input };
+ }
+ return undefined;
+ });
+
+ const options = {
+ localization: { locale: input },
+ };
+
+ const { unmount } = render(
+ <OptionsContext.Provider value={options}>
+ <__experimental_PaymentElementProvider checkout={mockCheckout}>
+ <__experimental_PaymentElement fallback={<div>Loading...</div>} />
+ </__experimental_PaymentElementProvider>
+ </OptionsContext.Provider>,
+ );
+
+ const elements = screen.getByTestId('stripe-elements');
+ expect(elements.getAttribute('data-locale')).toBe(expected);
+
+ unmount();
+ });
+ });
+});

packages/shared/src/react/commerce.tsx

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/consistent-type-imports */
-import type { Stripe, StripeElements } from '@stripe/stripe-js';
+import type { Stripe, StripeElements, StripeElementsOptions } from '@stripe/stripe-js';
 import React, { type PropsWithChildren, type ReactNode, useCallback, useEffect, useMemo, useState } from 'react';
 import useSWR from 'swr';
 import useSWRMutation from 'swr/mutation';
@@ -62,6 +62,23 @@ const useInternalEnvironment = () => {
  return clerk.__unstable__environment as unknown as EnvironmentResource | null | undefined;
 };
 
+const useLocalization = () => {
+ const clerk = useClerk();
+
+ let locale = 'en';
+ try {
+ const localization = clerk.__internal_getOption('localization');
+ locale = localization?.locale || 'en';
+ } catch {
+ // ignore errors
+ }
+
+ // Normalize locale to 2-letter language code for Stripe compatibility
+ const normalizedLocale = locale.split('-')[0];
+
+ return normalizedLocale;
+};
+
 const usePaymentSourceUtils = (forResource: ForPayerType = 'user') => {
  const { organization } = useOrganization();
  const { user } = useUser();
@@ -206,6 +223,7 @@ const PaymentElementProvider = ({ children, ...props }: PropsWithChildren<Paymen
 
 const PaymentElementInternalRoot = (props: PropsWithChildren) => {
  const { stripe, externalClientSecret, stripeAppearance } = usePaymentElementContext();
+ const locale = useLocalization();
 
  if (stripe && externalClientSecret) {
  return (
@@ -219,6 +237,7 @@ const PaymentElementInternalRoot = (props: PropsWithChildren) => {
  appearance: {
  variables: stripeAppearance,
  },
+ locale: locale as StripeElementsOptions['locale'],
  }}
  >
  <ValidateStripeUtils>{props.children}</ValidateStripeUtils>

.changeset/cold-bottles-watch.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/shared': patch
+---
+
+Propagate locale from ClerkProvider to PaymentElement

packages/clerk-js/src/core/clerk.ts

@@ -2420,6 +2420,7 @@ export class Clerk implements ClerkInterface {
  ..._props,
  options: this.#initOptions({ ...this.#options, ..._props.options }),
  };
+
  return this.#componentControls?.ensureMounted().then(controls => controls.updateProps(props));
  };
 

packages/shared/src/react/__tests__/commerce.test.tsx

@@ -0,0 +1,250 @@
+import { render, screen } from '@testing-library/react';
+import React from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { __experimental_PaymentElement, __experimental_PaymentElementProvider } from '../commerce';
+import { OptionsContext } from '../contexts';
+
+// Mock the Stripe components
+vi.mock('../stripe-react', () => ({
+ Elements: ({ children, options }: { children: React.ReactNode; options: any }) => (
+ <div
+ data-testid='stripe-elements'
+ data-locale={options.locale}
+ >
+ {children}
+ </div>
+ ),
+ PaymentElement: ({ fallback }: { fallback?: React.ReactNode }) => <div>{fallback}</div>,
+ useElements: () => null,
+ useStripe: () => null,
+}));
+
+// Mock the hooks
+const mockGetOption = vi.fn();
+vi.mock('../hooks/useClerk', () => ({
+ useClerk: () => ({
+ __internal_loadStripeJs: vi.fn().mockResolvedValue(() => Promise.resolve({})),
+ __internal_getOption: mockGetOption,
+ __unstable__environment: {
+ commerceSettings: {
+ billing: {
+ stripePublishableKey: 'pk_test_123',
+ },
+ },
+ displayConfig: {
+ userProfileUrl: 'https://example.com/profile',
+ organizationProfileUrl: 'https://example.com/org-profile',
+ },
+ },
+ }),
+}));
+
+vi.mock('../hooks/useUser', () => ({
+ useUser: () => ({
+ user: {
+ id: 'user_123',
+ initializePaymentSource: vi.fn().mockResolvedValue({
+ externalGatewayId: 'acct_123',
+ externalClientSecret: 'seti_123',
+ paymentMethodOrder: ['card'],
+ }),
+ },
+ }),
+}));
+
+vi.mock('../hooks/useOrganization', () => ({
+ useOrganization: () => ({
+ organization: null,
+ }),
+}));
+
+vi.mock('swr', () => ({
+ __esModule: true,
+ default: () => ({ data: { loadStripe: vi.fn().mockResolvedValue({}) } }),
+}));
+
+vi.mock('swr/mutation', () => ({
+ __esModule: true,
+ default: () => ({
+ data: {
+ externalGatewayId: 'acct_123',
+ externalClientSecret: 'seti_123',
+ paymentMethodOrder: ['card'],
+ },
+ trigger: vi.fn().mockResolvedValue({
+ externalGatewayId: 'acct_123',
+ externalClientSecret: 'seti_123',
+ paymentMethodOrder: ['card'],
+ }),
+ }),
+}));
+
+describe('PaymentElement Localization', () => {
+ const mockCheckout = {
+ id: 'checkout_123',
+ needsPaymentMethod: true,
+ plan: {
+ id: 'plan_123',
+ name: 'Test Plan',
+ description: 'Test plan description',
+ fee: { amount: 1000, amountFormatted: '$10.00', currency: 'usd', currencySymbol: '$' },
+ annualFee: { amount: 10000, amountFormatted: '$100.00', currency: 'usd', currencySymbol: '$' },
+ annualMonthlyFee: { amount: 833, amountFormatted: '$8.33', currency: 'usd', currencySymbol: '$' },
+ currency: 'usd',
+ interval: 'month' as const,
+ intervalCount: 1,
+ maxAllowedInstances: 1,
+ trialDays: 0,
+ isAddon: false,
+ isPopular: false,
+ isPerSeat: false,
+ isUsageBased: false,
+ isFree: false,
+ isLegacy: false,
+ isDefault: false,
+ isRecurring: true,
+ hasBaseFee: true,
+ forPayerType: 'user' as const,
+ publiclyVisible: true,
+ slug: 'test-plan',
+ avatarUrl: '',
+ freeTrialDays: 0,
+ freeTrialEnabled: false,
+ pathRoot: '/',
+ reload: vi.fn(),
+ features: [],
+ limits: {},
+ metadata: {},
+ },
+ totals: {
+ subtotal: { amount: 1000, amountFormatted: '$10.00', currency: 'usd', currencySymbol: '$' },
+ grandTotal: { amount: 1000, amountFormatted: '$10.00', currency: 'usd', currencySymbol: '$' },
+ taxTotal: { amount: 0, amountFormatted: '$0.00', currency: 'usd', currencySymbol: '$' },
+ totalDueNow: { amount: 1000, amountFormatted: '$10.00', currency: 'usd', currencySymbol: '$' },
+ credit: { amount: 0, amountFormatted: '$0.00', currency: 'usd', currencySymbol: '$' },
+ pastDue: { amount: 0, amountFormatted: '$0.00', currency: 'usd', currencySymbol: '$' },
+ },
+ status: 'needs_confirmation' as const,
+ error: null,
+ fetchStatus: 'idle' as const,
+ confirm: vi.fn(),
+ start: vi.fn(),
+ clear: vi.fn(),
+ finalize: vi.fn(),
+ getState: vi.fn(),
+ isConfirming: false,
+ isStarting: false,
+ planPeriod: 'month' as const,
+ externalClientSecret: 'seti_123',
+ externalGatewayId: 'acct_123',
+ isImmediatePlanChange: false,
+ paymentMethodOrder: ['card'],
+ freeTrialEndsAt: null,
+ payer: {
+ id: 'payer_123',
+ createdAt: new Date('2023-01-01'),
+ updatedAt: new Date('2023-01-01'),
+ imageUrl: null,
+ userId: 'user_123',
+ email: 'test@example.com',
+ firstName: 'Test',
+ lastName: 'User',
+ organizationId: undefined,
+ organizationName: undefined,
+ pathRoot: '/',
+ reload: vi.fn(),
+ },
+ };
+
+ const renderWithLocale = (locale: string) => {
+ // Mock the __internal_getOption to return the expected localization
+ mockGetOption.mockImplementation(key => {
+ if (key === 'localization') {
+ return { locale };
+ }
+ return undefined;
+ });
+
+ const options = {
+ localization: { locale },
+ };
+
+ return render(
+ <OptionsContext.Provider value={options}>
+ <__experimental_PaymentElementProvider checkout={mockCheckout}>
+ <__experimental_PaymentElement fallback={<div>Loading...</div>} />
+ </__experimental_PaymentElementProvider>
+ </OptionsContext.Provider>,
+ );
+ };
+
+ it('should pass the correct locale to Stripe Elements', () => {
+ renderWithLocale('es');
+
+ const elements = screen.getByTestId('stripe-elements');
+ expect(elements.getAttribute('data-locale')).toBe('es');
+ });
+
+ it('should default to "en" when no locale is provided', () => {
+ // Mock the __internal_getOption to return undefined for localization
+ mockGetOption.mockImplementation(key => {
+ if (key === 'localization') {
+ return undefined;
+ }
+ return undefined;
+ });
+
+ const options = {};
+
+ render(
+ <OptionsContext.Provider value={options}>
+ <__experimental_PaymentElementProvider checkout={mockCheckout}>
+ <__experimental_PaymentElement fallback={<div>Loading...</div>} />
+ </__experimental_PaymentElementProvider>
+ </OptionsContext.Provider>,
+ );
+
+ const elements = screen.getByTestId('stripe-elements');
+ expect(elements.getAttribute('data-locale')).toBe('en');
+ });
+
+ it('should normalize full locale strings to 2-letter codes for Stripe', () => {
+ const testCases = [
+ { input: 'en', expected: 'en' },
+ { input: 'en-US', expected: 'en' },
+ { input: 'fr-FR', expected: 'fr' },
+ { input: 'es-ES', expected: 'es' },
+ { input: 'de-DE', expected: 'de' },
+ { input: 'it-IT', expected: 'it' },
+ { input: 'pt-BR', expected: 'pt' },
+ ];
+
+ testCases.forEach(({ input, expected }) => {
+ // Mock the __internal_getOption to return the expected localization
+ mockGetOption.mockImplementation(key => {
+ if (key === 'localization') {
+ return { locale: input };
+ }
+ return undefined;
+ });
+
+ const options = {
+ localization: { locale: input },
+ };
+
+ const { unmount } = render(
+ <OptionsContext.Provider value={options}>
+ <__experimental_PaymentElementProvider checkout={mockCheckout}>
+ <__experimental_PaymentElement fallback={<div>Loading...</div>} />
+ </__experimental_PaymentElementProvider>
+ </OptionsContext.Provider>,
+ );
+
+ const elements = screen.getByTestId('stripe-elements');
+ expect(elements.getAttribute('data-locale')).toBe(expected);
+
+ unmount();
+ });
+ });
+});

packages/shared/src/react/commerce.tsx

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/consistent-type-imports */
-import type { Stripe, StripeElements } from '@stripe/stripe-js';
+import type { Stripe, StripeElements, StripeElementsOptions } from '@stripe/stripe-js';
 import React, { type PropsWithChildren, type ReactNode, useCallback, useEffect, useMemo, useState } from 'react';
 import useSWR from 'swr';
 import useSWRMutation from 'swr/mutation';
@@ -62,6 +62,23 @@ const useInternalEnvironment = () => {
  return clerk.__unstable__environment as unknown as EnvironmentResource | null | undefined;
 };
 
+const useLocalization = () => {
+ const clerk = useClerk();
+
+ let locale = 'en';
+ try {
+ const localization = clerk.__internal_getOption('localization');
+ locale = localization?.locale || 'en';
+ } catch {
+ // ignore errors
+ }
+
+ // Normalize locale to 2-letter language code for Stripe compatibility
+ const normalizedLocale = locale.split('-')[0];
+
+ return normalizedLocale;
+};
+
 const usePaymentSourceUtils = (forResource: ForPayerType = 'user') => {
  const { organization } = useOrganization();
  const { user } = useUser();
@@ -206,6 +223,7 @@ const PaymentElementProvider = ({ children, ...props }: PropsWithChildren<Paymen
 
 const PaymentElementInternalRoot = (props: PropsWithChildren) => {
  const { stripe, externalClientSecret, stripeAppearance } = usePaymentElementContext();
+ const locale = useLocalization();
 
  if (stripe && externalClientSecret) {
  return (
@@ -219,6 +237,7 @@ const PaymentElementInternalRoot = (props: PropsWithChildren) => {
  appearance: {
  variables: stripeAppearance,
  },
+ locale: locale as StripeElementsOptions['locale'],
  }}
  >
  <ValidateStripeUtils>{props.children}</ValidateStripeUtils>

.changeset/cold-bottles-watch.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/shared': patch
+---
+
+Propagate locale from ClerkProvider to PaymentElement

packages/clerk-js/src/core/clerk.ts

@@ -2420,6 +2420,7 @@ export class Clerk implements ClerkInterface {
  ..._props,
  options: this.#initOptions({ ...this.#options, ..._props.options }),
  };
+
  return this.#componentControls?.ensureMounted().then(controls => controls.updateProps(props));
  };
 

packages/shared/src/react/__tests__/commerce.test.tsx

@@ -0,0 +1,250 @@
+import { render, screen } from '@testing-library/react';
+import React from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { __experimental_PaymentElement, __experimental_PaymentElementProvider } from '../commerce';
+import { OptionsContext } from '../contexts';
+
+// Mock the Stripe components
+vi.mock('../stripe-react', () => ({
+ Elements: ({ children, options }: { children: React.ReactNode; options: any }) => (
+ <div
+ data-testid='stripe-elements'
+ data-locale={options.locale}
+ >
+ {children}
+ </div>
+ ),
+ PaymentElement: ({ fallback }: { fallback?: React.ReactNode }) => <div>{fallback}</div>,
+ useElements: () => null,
+ useStripe: () => null,
+}));
+
+// Mock the hooks
+const mockGetOption = vi.fn();
+vi.mock('../hooks/useClerk', () => ({
+ useClerk: () => ({
+ __internal_loadStripeJs: vi.fn().mockResolvedValue(() => Promise.resolve({})),
+ __internal_getOption: mockGetOption,
+ __unstable__environment: {
+ commerceSettings: {
+ billing: {
+ stripePublishableKey: 'pk_test_123',
+ },
+ },
+ displayConfig: {
+ userProfileUrl: 'https://example.com/profile',
+ organizationProfileUrl: 'https://example.com/org-profile',
+ },
+ },
+ }),
+}));
+
+vi.mock('../hooks/useUser', () => ({
+ useUser: () => ({
+ user: {
+ id: 'user_123',
+ initializePaymentSource: vi.fn().mockResolvedValue({
+ externalGatewayId: 'acct_123',
+ externalClientSecret: 'seti_123',
+ paymentMethodOrder: ['card'],
+ }),
+ },
+ }),
+}));
+
+vi.mock('../hooks/useOrganization', () => ({
+ useOrganization: () => ({
+ organization: null,
+ }),
+}));
+
+vi.mock('swr', () => ({
+ __esModule: true,
+ default: () => ({ data: { loadStripe: vi.fn().mockResolvedValue({}) } }),
+}));
+
+vi.mock('swr/mutation', () => ({
+ __esModule: true,
+ default: () => ({
+ data: {
+ externalGatewayId: 'acct_123',
+ externalClientSecret: 'seti_123',
+ paymentMethodOrder: ['card'],
+ },
+ trigger: vi.fn().mockResolvedValue({
+ externalGatewayId: 'acct_123',
+ externalClientSecret: 'seti_123',
+ paymentMethodOrder: ['card'],
+ }),
+ }),
+}));
+
+describe('PaymentElement Localization', () => {
+ const mockCheckout = {
+ id: 'checkout_123',
+ needsPaymentMethod: true,
+ plan: {
+ id: 'plan_123',
+ name: 'Test Plan',
+ description: 'Test plan description',
+ fee: { amount: 1000, amountFormatted: '$10.00', currency: 'usd', currencySymbol: '$' },
+ annualFee: { amount: 10000, amountFormatted: '$100.00', currency: 'usd', currencySymbol: '$' },
+ annualMonthlyFee: { amount: 833, amountFormatted: '$8.33', currency: 'usd', currencySymbol: '$' },
+ currency: 'usd',
+ interval: 'month' as const,
+ intervalCount: 1,
+ maxAllowedInstances: 1,
+ trialDays: 0,
+ isAddon: false,
+ isPopular: false,
+ isPerSeat: false,
+ isUsageBased: false,
+ isFree: false,
+ isLegacy: false,
+ isDefault: false,
+ isRecurring: true,
+ hasBaseFee: true,
+ forPayerType: 'user' as const,
+ publiclyVisible: true,
+ slug: 'test-plan',
+ avatarUrl: '',
+ freeTrialDays: 0,
+ freeTrialEnabled: false,
+ pathRoot: '/',
+ reload: vi.fn(),
+ features: [],
+ limits: {},
+ metadata: {},
+ },
+ totals: {
+ subtotal: { amount: 1000, amountFormatted: '$10.00', currency: 'usd', currencySymbol: '$' },
+ grandTotal: { amount: 1000, amountFormatted: '$10.00', currency: 'usd', currencySymbol: '$' },
+ taxTotal: { amount: 0, amountFormatted: '$0.00', currency: 'usd', currencySymbol: '$' },
+ totalDueNow: { amount: 1000, amountFormatted: '$10.00', currency: 'usd', currencySymbol: '$' },
+ credit: { amount: 0, amountFormatted: '$0.00', currency: 'usd', currencySymbol: '$' },
+ pastDue: { amount: 0, amountFormatted: '$0.00', currency: 'usd', currencySymbol: '$' },
+ },
+ status: 'needs_confirmation' as const,
+ error: null,
+ fetchStatus: 'idle' as const,
+ confirm: vi.fn(),
+ start: vi.fn(),
+ clear: vi.fn(),
+ finalize: vi.fn(),
+ getState: vi.fn(),
+ isConfirming: false,
+ isStarting: false,
+ planPeriod: 'month' as const,
+ externalClientSecret: 'seti_123',
+ externalGatewayId: 'acct_123',
+ isImmediatePlanChange: false,
+ paymentMethodOrder: ['card'],
+ freeTrialEndsAt: null,
+ payer: {
+ id: 'payer_123',
+ createdAt: new Date('2023-01-01'),
+ updatedAt: new Date('2023-01-01'),
+ imageUrl: null,
+ userId: 'user_123',
+ email: 'test@example.com',
+ firstName: 'Test',
+ lastName: 'User',
+ organizationId: undefined,
+ organizationName: undefined,
+ pathRoot: '/',
+ reload: vi.fn(),
+ },
+ };
+
+ const renderWithLocale = (locale: string) => {
+ // Mock the __internal_getOption to return the expected localization
+ mockGetOption.mockImplementation(key => {
+ if (key === 'localization') {
+ return { locale };
+ }
+ return undefined;
+ });
+
+ const options = {
+ localization: { locale },
+ };
+
+ return render(
+ <OptionsContext.Provider value={options}>
+ <__experimental_PaymentElementProvider checkout={mockCheckout}>
+ <__experimental_PaymentElement fallback={<div>Loading...</div>} />
+ </__experimental_PaymentElementProvider>
+ </OptionsContext.Provider>,
+ );
+ };
+
+ it('should pass the correct locale to Stripe Elements', () => {
+ renderWithLocale('es');
+
+ const elements = screen.getByTestId('stripe-elements');
+ expect(elements.getAttribute('data-locale')).toBe('es');
+ });
+
+ it('should default to "en" when no locale is provided', () => {
+ // Mock the __internal_getOption to return undefined for localization
+ mockGetOption.mockImplementation(key => {
+ if (key === 'localization') {
+ return undefined;
+ }
+ return undefined;
+ });
+
+ const options = {};
+
+ render(
+ <OptionsContext.Provider value={options}>
+ <__experimental_PaymentElementProvider checkout={mockCheckout}>
+ <__experimental_PaymentElement fallback={<div>Loading...</div>} />
+ </__experimental_PaymentElementProvider>
+ </OptionsContext.Provider>,
+ );
+
+ const elements = screen.getByTestId('stripe-elements');
+ expect(elements.getAttribute('data-locale')).toBe('en');
+ });
+
+ it('should normalize full locale strings to 2-letter codes for Stripe', () => {
+ const testCases = [
+ { input: 'en', expected: 'en' },
+ { input: 'en-US', expected: 'en' },
+ { input: 'fr-FR', expected: 'fr' },
+ { input: 'es-ES', expected: 'es' },
+ { input: 'de-DE', expected: 'de' },
+ { input: 'it-IT', expected: 'it' },
+ { input: 'pt-BR', expected: 'pt' },
+ ];
+
+ testCases.forEach(({ input, expected }) => {
+ // Mock the __internal_getOption to return the expected localization
+ mockGetOption.mockImplementation(key => {
+ if (key === 'localization') {
+ return { locale: input };
+ }
+ return undefined;
+ });
+
+ const options = {
+ localization: { locale: input },
+ };
+
+ const { unmount } = render(
+ <OptionsContext.Provider value={options}>
+ <__experimental_PaymentElementProvider checkout={mockCheckout}>
+ <__experimental_PaymentElement fallback={<div>Loading...</div>} />
+ </__experimental_PaymentElementProvider>
+ </OptionsContext.Provider>,
+ );
+
+ const elements = screen.getByTestId('stripe-elements');
+ expect(elements.getAttribute('data-locale')).toBe(expected);
+
+ unmount();
+ });
+ });
+});

packages/shared/src/react/commerce.tsx

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/consistent-type-imports */
-import type { Stripe, StripeElements } from '@stripe/stripe-js';
+import type { Stripe, StripeElements, StripeElementsOptions } from '@stripe/stripe-js';
 import React, { type PropsWithChildren, type ReactNode, useCallback, useEffect, useMemo, useState } from 'react';
 import useSWR from 'swr';
 import useSWRMutation from 'swr/mutation';
@@ -62,6 +62,23 @@ const useInternalEnvironment = () => {
  return clerk.__unstable__environment as unknown as EnvironmentResource | null | undefined;
 };
 
+const useLocalization = () => {
+ const clerk = useClerk();
+
+ let locale = 'en';
+ try {
+ const localization = clerk.__internal_getOption('localization');
+ locale = localization?.locale || 'en';
+ } catch {
+ // ignore errors
+ }
+
+ // Normalize locale to 2-letter language code for Stripe compatibility
+ const normalizedLocale = locale.split('-')[0];
+
+ return normalizedLocale;
+};
+
 const usePaymentSourceUtils = (forResource: ForPayerType = 'user') => {
  const { organization } = useOrganization();
  const { user } = useUser();
@@ -206,6 +223,7 @@ const PaymentElementProvider = ({ children, ...props }: PropsWithChildren<Paymen
 
 const PaymentElementInternalRoot = (props: PropsWithChildren) => {
  const { stripe, externalClientSecret, stripeAppearance } = usePaymentElementContext();
+ const locale = useLocalization();
 
  if (stripe && externalClientSecret) {
  return (
@@ -219,6 +237,7 @@ const PaymentElementInternalRoot = (props: PropsWithChildren) => {
  appearance: {
  variables: stripeAppearance,
  },
+ locale: locale as StripeElementsOptions['locale'],
  }}
  >
  <ValidateStripeUtils>{props.children}</ValidateStripeUtils>

.changeset/cold-bottles-watch.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/shared': patch
+---
+
+Propagate locale from ClerkProvider to PaymentElement

packages/clerk-js/src/core/clerk.ts

@@ -2420,6 +2420,7 @@ export class Clerk implements ClerkInterface {
  ..._props,
  options: this.#initOptions({ ...this.#options, ..._props.options }),
  };
+
  return this.#componentControls?.ensureMounted().then(controls => controls.updateProps(props));
  };
 

packages/shared/src/react/__tests__/commerce.test.tsx

@@ -0,0 +1,250 @@
+import { render, screen } from '@testing-library/react';
+import React from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { __experimental_PaymentElement, __experimental_PaymentElementProvider } from '../commerce';
+import { OptionsContext } from '../contexts';
+
+// Mock the Stripe components
+vi.mock('../stripe-react', () => ({
+ Elements: ({ children, options }: { children: React.ReactNode; options: any }) => (
+ <div
+ data-testid='stripe-elements'
+ data-locale={options.locale}
+ >
+ {children}
+ </div>
+ ),
+ PaymentElement: ({ fallback }: { fallback?: React.ReactNode }) => <div>{fallback}</div>,
+ useElements: () => null,
+ useStripe: () => null,
+}));
+
+// Mock the hooks
+const mockGetOption = vi.fn();
+vi.mock('../hooks/useClerk', () => ({
+ useClerk: () => ({
+ __internal_loadStripeJs: vi.fn().mockResolvedValue(() => Promise.resolve({})),
+ __internal_getOption: mockGetOption,
+ __unstable__environment: {
+ commerceSettings: {
+ billing: {
+ stripePublishableKey: 'pk_test_123',
+ },
+ },
+ displayConfig: {
+ userProfileUrl: 'https://example.com/profile',
+ organizationProfileUrl: 'https://example.com/org-profile',
+ },
+ },
+ }),
+}));
+
+vi.mock('../hooks/useUser', () => ({
+ useUser: () => ({
+ user: {
+ id: 'user_123',
+ initializePaymentSource: vi.fn().mockResolvedValue({
+ externalGatewayId: 'acct_123',
+ externalClientSecret: 'seti_123',
+ paymentMethodOrder: ['card'],
+ }),
+ },
+ }),
+}));
+
+vi.mock('../hooks/useOrganization', () => ({
+ useOrganization: () => ({
+ organization: null,
+ }),
+}));
+
+vi.mock('swr', () => ({
+ __esModule: true,
+ default: () => ({ data: { loadStripe: vi.fn().mockResolvedValue({}) } }),
+}));
+
+vi.mock('swr/mutation', () => ({
+ __esModule: true,
+ default: () => ({
+ data: {
+ externalGatewayId: 'acct_123',
+ externalClientSecret: 'seti_123',
+ paymentMethodOrder: ['card'],
+ },
+ trigger: vi.fn().mockResolvedValue({
+ externalGatewayId: 'acct_123',
+ externalClientSecret: 'seti_123',
+ paymentMethodOrder: ['card'],
+ }),
+ }),
+}));
+
+describe('PaymentElement Localization', () => {
+ const mockCheckout = {
+ id: 'checkout_123',
+ needsPaymentMethod: true,
+ plan: {
+ id: 'plan_123',
+ name: 'Test Plan',
+ description: 'Test plan description',
+ fee: { amount: 1000, amountFormatted: '$10.00', currency: 'usd', currencySymbol: '$' },
+ annualFee: { amount: 10000, amountFormatted: '$100.00', currency: 'usd', currencySymbol: '$' },
+ annualMonthlyFee: { amount: 833, amountFormatted: '$8.33', currency: 'usd', currencySymbol: '$' },
+ currency: 'usd',
+ interval: 'month' as const,
+ intervalCount: 1,
+ maxAllowedInstances: 1,
+ trialDays: 0,
+ isAddon: false,
+ isPopular: false,
+ isPerSeat: false,
+ isUsageBased: false,
+ isFree: false,
+ isLegacy: false,
+ isDefault: false,
+ isRecurring: true,
+ hasBaseFee: true,
+ forPayerType: 'user' as const,
+ publiclyVisible: true,
+ slug: 'test-plan',
+ avatarUrl: '',
+ freeTrialDays: 0,
+ freeTrialEnabled: false,
+ pathRoot: '/',
+ reload: vi.fn(),
+ features: [],
+ limits: {},
+ metadata: {},
+ },
+ totals: {
+ subtotal: { amount: 1000, amountFormatted: '$10.00', currency: 'usd', currencySymbol: '$' },
+ grandTotal: { amount: 1000, amountFormatted: '$10.00', currency: 'usd', currencySymbol: '$' },
+ taxTotal: { amount: 0, amountFormatted: '$0.00', currency: 'usd', currencySymbol: '$' },
+ totalDueNow: { amount: 1000, amountFormatted: '$10.00', currency: 'usd', currencySymbol: '$' },
+ credit: { amount: 0, amountFormatted: '$0.00', currency: 'usd', currencySymbol: '$' },
+ pastDue: { amount: 0, amountFormatted: '$0.00', currency: 'usd', currencySymbol: '$' },
+ },
+ status: 'needs_confirmation' as const,
+ error: null,
+ fetchStatus: 'idle' as const,
+ confirm: vi.fn(),
+ start: vi.fn(),
+ clear: vi.fn(),
+ finalize: vi.fn(),
+ getState: vi.fn(),
+ isConfirming: false,
+ isStarting: false,
+ planPeriod: 'month' as const,
+ externalClientSecret: 'seti_123',
+ externalGatewayId: 'acct_123',
+ isImmediatePlanChange: false,
+ paymentMethodOrder: ['card'],
+ freeTrialEndsAt: null,
+ payer: {
+ id: 'payer_123',
+ createdAt: new Date('2023-01-01'),
+ updatedAt: new Date('2023-01-01'),
+ imageUrl: null,
+ userId: 'user_123',
+ email: 'test@example.com',
+ firstName: 'Test',
+ lastName: 'User',
+ organizationId: undefined,
+ organizationName: undefined,
+ pathRoot: '/',
+ reload: vi.fn(),
+ },
+ };
+
+ const renderWithLocale = (locale: string) => {
+ // Mock the __internal_getOption to return the expected localization
+ mockGetOption.mockImplementation(key => {
+ if (key === 'localization') {
+ return { locale };
+ }
+ return undefined;
+ });
+
+ const options = {
+ localization: { locale },
+ };
+
+ return render(
+ <OptionsContext.Provider value={options}>
+ <__experimental_PaymentElementProvider checkout={mockCheckout}>
+ <__experimental_PaymentElement fallback={<div>Loading...</div>} />
+ </__experimental_PaymentElementProvider>
+ </OptionsContext.Provider>,
+ );
+ };
+
+ it('should pass the correct locale to Stripe Elements', () => {
+ renderWithLocale('es');
+
+ const elements = screen.getByTestId('stripe-elements');
+ expect(elements.getAttribute('data-locale')).toBe('es');
+ });
+
+ it('should default to "en" when no locale is provided', () => {
+ // Mock the __internal_getOption to return undefined for localization
+ mockGetOption.mockImplementation(key => {
+ if (key === 'localization') {
+ return undefined;
+ }
+ return undefined;
+ });
+
+ const options = {};
+
+ render(
+ <OptionsContext.Provider value={options}>
+ <__experimental_PaymentElementProvider checkout={mockCheckout}>
+ <__experimental_PaymentElement fallback={<div>Loading...</div>} />
+ </__experimental_PaymentElementProvider>
+ </OptionsContext.Provider>,
+ );
+
+ const elements = screen.getByTestId('stripe-elements');
+ expect(elements.getAttribute('data-locale')).toBe('en');
+ });
+
+ it('should normalize full locale strings to 2-letter codes for Stripe', () => {
+ const testCases = [
+ { input: 'en', expected: 'en' },
+ { input: 'en-US', expected: 'en' },
+ { input: 'fr-FR', expected: 'fr' },
+ { input: 'es-ES', expected: 'es' },
+ { input: 'de-DE', expected: 'de' },
+ { input: 'it-IT', expected: 'it' },
+ { input: 'pt-BR', expected: 'pt' },
+ ];
+
+ testCases.forEach(({ input, expected }) => {
+ // Mock the __internal_getOption to return the expected localization
+ mockGetOption.mockImplementation(key => {
+ if (key === 'localization') {
+ return { locale: input };
+ }
+ return undefined;
+ });
+
+ const options = {
+ localization: { locale: input },
+ };
+
+ const { unmount } = render(
+ <OptionsContext.Provider value={options}>
+ <__experimental_PaymentElementProvider checkout={mockCheckout}>
+ <__experimental_PaymentElement fallback={<div>Loading...</div>} />
+ </__experimental_PaymentElementProvider>
+ </OptionsContext.Provider>,
+ );
+
+ const elements = screen.getByTestId('stripe-elements');
+ expect(elements.getAttribute('data-locale')).toBe(expected);
+
+ unmount();
+ });
+ });
+});

packages/shared/src/react/commerce.tsx

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/consistent-type-imports */
-import type { Stripe, StripeElements } from '@stripe/stripe-js';
+import type { Stripe, StripeElements, StripeElementsOptions } from '@stripe/stripe-js';
 import React, { type PropsWithChildren, type ReactNode, useCallback, useEffect, useMemo, useState } from 'react';
 import useSWR from 'swr';
 import useSWRMutation from 'swr/mutation';
@@ -62,6 +62,23 @@ const useInternalEnvironment = () => {
  return clerk.__unstable__environment as unknown as EnvironmentResource | null | undefined;
 };
 
+const useLocalization = () => {
+ const clerk = useClerk();
+
+ let locale = 'en';
+ try {
+ const localization = clerk.__internal_getOption('localization');
+ locale = localization?.locale || 'en';
+ } catch {
+ // ignore errors
+ }
+
+ // Normalize locale to 2-letter language code for Stripe compatibility
+ const normalizedLocale = locale.split('-')[0];
+
+ return normalizedLocale;
+};
+
 const usePaymentSourceUtils = (forResource: ForPayerType = 'user') => {
  const { organization } = useOrganization();
  const { user } = useUser();
@@ -206,6 +223,7 @@ const PaymentElementProvider = ({ children, ...props }: PropsWithChildren<Paymen
 
 const PaymentElementInternalRoot = (props: PropsWithChildren) => {
  const { stripe, externalClientSecret, stripeAppearance } = usePaymentElementContext();
+ const locale = useLocalization();
 
  if (stripe && externalClientSecret) {
  return (
@@ -219,6 +237,7 @@ const PaymentElementInternalRoot = (props: PropsWithChildren) => {
  appearance: {
  variables: stripeAppearance,
  },
+ locale: locale as StripeElementsOptions['locale'],
  }}
  >
  <ValidateStripeUtils>{props.children}</ValidateStripeUtils>

.changeset/cold-bottles-watch.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/shared': patch
+---
+
+Propagate locale from ClerkProvider to PaymentElement

packages/clerk-js/src/core/clerk.ts

@@ -2420,6 +2420,7 @@ export class Clerk implements ClerkInterface {
  ..._props,
  options: this.#initOptions({ ...this.#options, ..._props.options }),
  };
+
  return this.#componentControls?.ensureMounted().then(controls => controls.updateProps(props));
  };
 

packages/shared/src/react/__tests__/commerce.test.tsx

@@ -0,0 +1,250 @@
+import { render, screen } from '@testing-library/react';
+import React from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { __experimental_PaymentElement, __experimental_PaymentElementProvider } from '../commerce';
+import { OptionsContext } from '../contexts';
+
+// Mock the Stripe components
+vi.mock('../stripe-react', () => ({
+ Elements: ({ children, options }: { children: React.ReactNode; options: any }) => (
+ <div
+ data-testid='stripe-elements'
+ data-locale={options.locale}
+ >
+ {children}
+ </div>
+ ),
+ PaymentElement: ({ fallback }: { fallback?: React.ReactNode }) => <div>{fallback}</div>,
+ useElements: () => null,
+ useStripe: () => null,
+}));
+
+// Mock the hooks
+const mockGetOption = vi.fn();
+vi.mock('../hooks/useClerk', () => ({
+ useClerk: () => ({
+ __internal_loadStripeJs: vi.fn().mockResolvedValue(() => Promise.resolve({})),
+ __internal_getOption: mockGetOption,
+ __unstable__environment: {
+ commerceSettings: {
+ billing: {
+ stripePublishableKey: 'pk_test_123',
+ },
+ },
+ displayConfig: {
+ userProfileUrl: 'https://example.com/profile',
+ organizationProfileUrl: 'https://example.com/org-profile',
+ },
+ },
+ }),
+}));
+
+vi.mock('../hooks/useUser', () => ({
+ useUser: () => ({
+ user: {
+ id: 'user_123',
+ initializePaymentSource: vi.fn().mockResolvedValue({
+ externalGatewayId: 'acct_123',
+ externalClientSecret: 'seti_123',
+ paymentMethodOrder: ['card'],
+ }),
+ },
+ }),
+}));
+
+vi.mock('../hooks/useOrganization', () => ({
+ useOrganization: () => ({
+ organization: null,
+ }),
+}));
+
+vi.mock('swr', () => ({
+ __esModule: true,
+ default: () => ({ data: { loadStripe: vi.fn().mockResolvedValue({}) } }),
+}));
+
+vi.mock('swr/mutation', () => ({
+ __esModule: true,
+ default: () => ({
+ data: {
+ externalGatewayId: 'acct_123',
+ externalClientSecret: 'seti_123',
+ paymentMethodOrder: ['card'],
+ },
+ trigger: vi.fn().mockResolvedValue({
+ externalGatewayId: 'acct_123',
+ externalClientSecret: 'seti_123',
+ paymentMethodOrder: ['card'],
+ }),
+ }),
+}));
+
+describe('PaymentElement Localization', () => {
+ const mockCheckout = {
+ id: 'checkout_123',
+ needsPaymentMethod: true,
+ plan: {
+ id: 'plan_123',
+ name: 'Test Plan',
+ description: 'Test plan description',
+ fee: { amount: 1000, amountFormatted: '$10.00', currency: 'usd', currencySymbol: '$' },
+ annualFee: { amount: 10000, amountFormatted: '$100.00', currency: 'usd', currencySymbol: '$' },
+ annualMonthlyFee: { amount: 833, amountFormatted: '$8.33', currency: 'usd', currencySymbol: '$' },
+ currency: 'usd',
+ interval: 'month' as const,
+ intervalCount: 1,
+ maxAllowedInstances: 1,
+ trialDays: 0,
+ isAddon: false,
+ isPopular: false,
+ isPerSeat: false,
+ isUsageBased: false,
+ isFree: false,
+ isLegacy: false,
+ isDefault: false,
+ isRecurring: true,
+ hasBaseFee: true,
+ forPayerType: 'user' as const,
+ publiclyVisible: true,
+ slug: 'test-plan',
+ avatarUrl: '',
+ freeTrialDays: 0,
+ freeTrialEnabled: false,
+ pathRoot: '/',
+ reload: vi.fn(),
+ features: [],
+ limits: {},
+ metadata: {},
+ },
+ totals: {
+ subtotal: { amount: 1000, amountFormatted: '$10.00', currency: 'usd', currencySymbol: '$' },
+ grandTotal: { amount: 1000, amountFormatted: '$10.00', currency: 'usd', currencySymbol: '$' },
+ taxTotal: { amount: 0, amountFormatted: '$0.00', currency: 'usd', currencySymbol: '$' },
+ totalDueNow: { amount: 1000, amountFormatted: '$10.00', currency: 'usd', currencySymbol: '$' },
+ credit: { amount: 0, amountFormatted: '$0.00', currency: 'usd', currencySymbol: '$' },
+ pastDue: { amount: 0, amountFormatted: '$0.00', currency: 'usd', currencySymbol: '$' },
+ },
+ status: 'needs_confirmation' as const,
+ error: null,
+ fetchStatus: 'idle' as const,
+ confirm: vi.fn(),
+ start: vi.fn(),
+ clear: vi.fn(),
+ finalize: vi.fn(),
+ getState: vi.fn(),
+ isConfirming: false,
+ isStarting: false,
+ planPeriod: 'month' as const,
+ externalClientSecret: 'seti_123',
+ externalGatewayId: 'acct_123',
+ isImmediatePlanChange: false,
+ paymentMethodOrder: ['card'],
+ freeTrialEndsAt: null,
+ payer: {
+ id: 'payer_123',
+ createdAt: new Date('2023-01-01'),
+ updatedAt: new Date('2023-01-01'),
+ imageUrl: null,
+ userId: 'user_123',
+ email: 'test@example.com',
+ firstName: 'Test',
+ lastName: 'User',
+ organizationId: undefined,
+ organizationName: undefined,
+ pathRoot: '/',
+ reload: vi.fn(),
+ },
+ };
+
+ const renderWithLocale = (locale: string) => {
+ // Mock the __internal_getOption to return the expected localization
+ mockGetOption.mockImplementation(key => {
+ if (key === 'localization') {
+ return { locale };
+ }
+ return undefined;
+ });
+
+ const options = {
+ localization: { locale },
+ };
+
+ return render(
+ <OptionsContext.Provider value={options}>
+ <__experimental_PaymentElementProvider checkout={mockCheckout}>
+ <__experimental_PaymentElement fallback={<div>Loading...</div>} />
+ </__experimental_PaymentElementProvider>
+ </OptionsContext.Provider>,
+ );
+ };
+
+ it('should pass the correct locale to Stripe Elements', () => {
+ renderWithLocale('es');
+
+ const elements = screen.getByTestId('stripe-elements');
+ expect(elements.getAttribute('data-locale')).toBe('es');
+ });
+
+ it('should default to "en" when no locale is provided', () => {
+ // Mock the __internal_getOption to return undefined for localization
+ mockGetOption.mockImplementation(key => {
+ if (key === 'localization') {
+ return undefined;
+ }
+ return undefined;
+ });
+
+ const options = {};
+
+ render(
+ <OptionsContext.Provider value={options}>
+ <__experimental_PaymentElementProvider checkout={mockCheckout}>
+ <__experimental_PaymentElement fallback={<div>Loading...</div>} />
+ </__experimental_PaymentElementProvider>
+ </OptionsContext.Provider>,
+ );
+
+ const elements = screen.getByTestId('stripe-elements');
+ expect(elements.getAttribute('data-locale')).toBe('en');
+ });
+
+ it('should normalize full locale strings to 2-letter codes for Stripe', () => {
+ const testCases = [
+ { input: 'en', expected: 'en' },
+ { input: 'en-US', expected: 'en' },
+ { input: 'fr-FR', expected: 'fr' },
+ { input: 'es-ES', expected: 'es' },
+ { input: 'de-DE', expected: 'de' },
+ { input: 'it-IT', expected: 'it' },
+ { input: 'pt-BR', expected: 'pt' },
+ ];
+
+ testCases.forEach(({ input, expected }) => {
+ // Mock the __internal_getOption to return the expected localization
+ mockGetOption.mockImplementation(key => {
+ if (key === 'localization') {
+ return { locale: input };
+ }
+ return undefined;
+ });
+
+ const options = {
+ localization: { locale: input },
+ };
+
+ const { unmount } = render(
+ <OptionsContext.Provider value={options}>
+ <__experimental_PaymentElementProvider checkout={mockCheckout}>
+ <__experimental_PaymentElement fallback={<div>Loading...</div>} />
+ </__experimental_PaymentElementProvider>
+ </OptionsContext.Provider>,
+ );
+
+ const elements = screen.getByTestId('stripe-elements');
+ expect(elements.getAttribute('data-locale')).toBe(expected);
+
+ unmount();
+ });
+ });
+});

packages/shared/src/react/commerce.tsx

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/consistent-type-imports */
-import type { Stripe, StripeElements } from '@stripe/stripe-js';
+import type { Stripe, StripeElements, StripeElementsOptions } from '@stripe/stripe-js';
 import React, { type PropsWithChildren, type ReactNode, useCallback, useEffect, useMemo, useState } from 'react';
 import useSWR from 'swr';
 import useSWRMutation from 'swr/mutation';
@@ -62,6 +62,23 @@ const useInternalEnvironment = () => {
  return clerk.__unstable__environment as unknown as EnvironmentResource | null | undefined;
 };
 
+const useLocalization = () => {
+ const clerk = useClerk();
+
+ let locale = 'en';
+ try {
+ const localization = clerk.__internal_getOption('localization');
+ locale = localization?.locale || 'en';
+ } catch {
+ // ignore errors
+ }
+
+ // Normalize locale to 2-letter language code for Stripe compatibility
+ const normalizedLocale = locale.split('-')[0];
+
+ return normalizedLocale;
+};
+
 const usePaymentSourceUtils = (forResource: ForPayerType = 'user') => {
  const { organization } = useOrganization();
  const { user } = useUser();
@@ -206,6 +223,7 @@ const PaymentElementProvider = ({ children, ...props }: PropsWithChildren<Paymen
 
 const PaymentElementInternalRoot = (props: PropsWithChildren) => {
  const { stripe, externalClientSecret, stripeAppearance } = usePaymentElementContext();
+ const locale = useLocalization();
 
  if (stripe && externalClientSecret) {
  return (
@@ -219,6 +237,7 @@ const PaymentElementInternalRoot = (props: PropsWithChildren) => {
  appearance: {
  variables: stripeAppearance,
  },
+ locale: locale as StripeElementsOptions['locale'],
  }}
  >
  <ValidateStripeUtils>{props.children}</ValidateStripeUtils>