fix(clerk-js): Ensure localizations fallback to english locale when key is undefined

.changeset/cute-gifts-call.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Fix locale fallback logic to render English values when localization keys are `undefined`.

packages/clerk-js/src/ui/localization/__tests__/parseLocalization.test.tsx

@@ -37,4 +37,65 @@ describe('Localization parsing and replacing', () => {
     const localizedValue = result.current.t(localizationKeys('backButton'));
     expect(localizedValue).toBe('test');
   });
+
+  it('falls back to English when user locale has undefined value for a key', async () => {
+    const { wrapper: Wrapper } = await createFixtures();
+    const wrapperBefore = ({ children }) => (
+      <Wrapper>
+        <OptionsProvider
+          value={{
+            localization: {
+              backButton: undefined, // Explicitly undefined should fall back to English
+              formButtonPrimary: 'Translated', // Non-undefined should override
+            },
+          }}
+        >
+          {children}
+        </OptionsProvider>
+      </Wrapper>
+    );
+
+    const { result } = renderHook(() => useLocalizations(), { wrapper: wrapperBefore });
+
+    // undefined value should fall back to English
+    const backButtonValue = result.current.t(localizationKeys('backButton'));
+    expect(backButtonValue).toBe(defaultResource.backButton);
+
+    // Non-undefined value should use the translation
+    const formButtonValue = result.current.t(localizationKeys('formButtonPrimary'));
+    expect(formButtonValue).toBe('Translated');
+  });
+
+  it('falls back to English for nested keys with undefined values', async () => {
+    const { wrapper: Wrapper } = await createFixtures();
+    const wrapperBefore = ({ children }) => (
+      <Wrapper>
+        <OptionsProvider
+          value={{
+            localization: {
+              signIn: {
+                start: {
+                  title: undefined, // Should fall back to English
+                  subtitle: 'Custom subtitle', // Non-undefined should override
+                },
+              },
+            },
+          }}
+        >
+          {children}
+        </OptionsProvider>
+      </Wrapper>
+    );
+
+    const { result } = renderHook(() => useLocalizations(), { wrapper: wrapperBefore });
+
+    // undefined nested value should fall back to English (tokens get replaced by t())
+    const titleValue = result.current.t(localizationKeys('signIn.start.title'));
+    // The English default is 'Sign in to {{applicationName}}', tokens get replaced
+    expect(titleValue).toContain('Sign in to');
+
+    // Non-undefined nested value should use the translation
+    const subtitleValue = result.current.t(localizationKeys('signIn.start.subtitle'));
+    expect(subtitleValue).toBe('Custom subtitle');
+  });
 });

packages/clerk-js/src/ui/localization/parseLocalization.ts

@@ -1,5 +1,5 @@
 import type { DeepPartial, LocalizationResource } from '@clerk/shared/types';
-import { fastDeepMergeAndReplace } from '@clerk/shared/utils';
+import { fastDeepMergeAndKeep, fastDeepMergeAndReplace } from '@clerk/shared/utils';
 import { dequal as deepEqual } from 'dequal';
 
 import { useOptions } from '../contexts';
@@ -15,8 +15,10 @@ const parseLocalizationResource = (
   if (!cache || (!!prev && prev !== userDefined && !deepEqual(userDefined, prev))) {
     prev = userDefined;
     const res = {} as LocalizationResource;
-    fastDeepMergeAndReplace(base, res);
+    // Merge user-defined first (may contain undefined values)
     fastDeepMergeAndReplace(userDefined, res);
+    // Fill in missing/undefined values from base (English)
+    fastDeepMergeAndKeep(base, res);
     cache = res;
     return cache;
   }