chore(clerk-js, localizations): Improve type safety of localizationKeys() with params (#6108)

panteliselef · web-flow · commit c3fa15d60642 · 2025-06-17T12:57:30.000+03:00
diff --git a/.changeset/cold-turtles-press.md b/.changeset/cold-turtles-press.md
@@ -0,0 +1,5 @@
+---
+'@clerk/types': minor
+---
+
+Expose `__internal_LocalizationResource` which now includes metadata for which keys require interpolation.
diff --git a/packages/clerk-js/bundlewatch.config.json b/packages/clerk-js/bundlewatch.config.json
@@ -4,7 +4,7 @@
     { "path": "./dist/clerk.browser.js", "maxSize": "70.16KB" },
     { "path": "./dist/clerk.legacy.browser.js", "maxSize": "113KB" },
     { "path": "./dist/clerk.headless*.js", "maxSize": "53.06KB" },
-    { "path": "./dist/ui-common*.js", "maxSize": "108.36KB" },
+    { "path": "./dist/ui-common*.js", "maxSize": "108.4KB" },
     { "path": "./dist/vendors*.js", "maxSize": "40.2KB" },
     { "path": "./dist/coinbase*.js", "maxSize": "38KB" },
     { "path": "./dist/createorganization*.js", "maxSize": "5KB" },
diff --git a/packages/clerk-js/src/ui/components/ApiKeys/RevokeAPIKeyConfirmationModal.tsx b/packages/clerk-js/src/ui/components/ApiKeys/RevokeAPIKeyConfirmationModal.tsx
@@ -15,7 +15,7 @@ type RevokeAPIKeyConfirmationModalProps = {
   onOpen: () => void;
   onClose: () => void;
   apiKeyId?: string;
-  apiKeyName?: string;
+  apiKeyName: string;
   modalRoot?: React.MutableRefObject<HTMLElement | null>;
 };
 
diff --git a/packages/clerk-js/src/ui/components/OrganizationProfile/ActionConfirmationPage.tsx b/packages/clerk-js/src/ui/components/OrganizationProfile/ActionConfirmationPage.tsx
@@ -49,13 +49,13 @@ export const LeaveOrganizationForm = (props: LeaveOrganizationFormProps) => {
 
   return (
     <ActionConfirmationPage
-      organizationName={organization?.name}
+      organizationName={organization.name}
       title={localizationKeys('organizationProfile.profilePage.dangerSection.leaveOrganization.title')}
       messageLine1={localizationKeys('organizationProfile.profilePage.dangerSection.leaveOrganization.messageLine1')}
       messageLine2={localizationKeys('organizationProfile.profilePage.dangerSection.leaveOrganization.messageLine2')}
       actionDescription={localizationKeys(
         'organizationProfile.profilePage.dangerSection.leaveOrganization.actionDescription',
-        { organizationName: organization?.name },
+        { organizationName: organization.name },
       )}
       submitLabel={localizationKeys('organizationProfile.profilePage.dangerSection.leaveOrganization.title')}
       successMessage={localizationKeys(
@@ -79,13 +79,13 @@ export const DeleteOrganizationForm = (props: DeleteOrganizationFormProps) => {
 
   return (
     <ActionConfirmationPage
-      organizationName={organization?.name}
+      organizationName={organization.name}
       title={localizationKeys('organizationProfile.profilePage.dangerSection.deleteOrganization.title')}
       messageLine1={localizationKeys('organizationProfile.profilePage.dangerSection.deleteOrganization.messageLine1')}
       messageLine2={localizationKeys('organizationProfile.profilePage.dangerSection.deleteOrganization.messageLine2')}
       actionDescription={localizationKeys(
         'organizationProfile.profilePage.dangerSection.deleteOrganization.actionDescription',
-        { organizationName: organization?.name },
+        { organizationName: organization.name },
       )}
       submitLabel={localizationKeys('organizationProfile.profilePage.dangerSection.deleteOrganization.title')}
       successMessage={localizationKeys(
@@ -101,7 +101,7 @@ type ActionConfirmationPageProps = FormProps & {
   title: LocalizationKey;
   messageLine1: LocalizationKey;
   messageLine2: LocalizationKey;
-  actionDescription?: LocalizationKey;
+  actionDescription: LocalizationKey;
   organizationName?: string;
   successMessage: LocalizationKey;
   submitLabel: LocalizationKey;
@@ -128,9 +128,7 @@ const ActionConfirmationPage = withCardStateProvider((props: ActionConfirmationP
 
   const confirmationField = useFormControl('deleteOrganizationConfirmation', '', {
     type: 'text',
-    label:
-      actionDescription ||
-      localizationKeys('organizationProfile.profilePage.dangerSection.leaveOrganization.actionDescription'),
+    label: actionDescription,
     isRequired: true,
     placeholder: organizationName,
   });
diff --git a/packages/clerk-js/src/ui/components/OrganizationProfile/RemoveDomainForm.tsx b/packages/clerk-js/src/ui/components/OrganizationProfile/RemoveDomainForm.tsx
@@ -62,7 +62,7 @@ export const RemoveDomainForm = (props: RemoveDomainFormProps) => {
     <RemoveResourceForm
       title={localizationKeys('organizationProfile.removeDomainPage.title')}
       messageLine1={localizationKeys('organizationProfile.removeDomainPage.messageLine1', {
-        domain: ref.current?.name,
+        domain: ref.current?.name || '',
       })}
       messageLine2={localizationKeys('organizationProfile.removeDomainPage.messageLine2')}
       deleteResource={() =>
diff --git a/packages/clerk-js/src/ui/components/OrganizationProfile/VerifiedDomainForm.tsx b/packages/clerk-js/src/ui/components/OrganizationProfile/VerifiedDomainForm.tsx
@@ -129,10 +129,10 @@ export const VerifiedDomainForm = withCardStateProvider((props: VerifiedDomainFo
   }, [domain?.id]);
 
   const title = localizationKeys('organizationProfile.verifiedDomainPage.title', {
-    domain: domain?.name,
+    domain: domain?.name || '',
   });
   const subtitle = localizationKeys('organizationProfile.verifiedDomainPage.subtitle', {
-    domain: domain?.name,
+    domain: domain?.name || '',
   });
 
   const calloutLabel = useCalloutLabel(domain, {
diff --git a/packages/clerk-js/src/ui/components/OrganizationProfile/VerifyDomainForm.tsx b/packages/clerk-js/src/ui/components/OrganizationProfile/VerifyDomainForm.tsx
@@ -50,7 +50,7 @@ export const VerifyDomainForm = withCardStateProvider((props: VerifyDomainFormPr
   const subtitleVerificationCodeScreen = localizationKeys(
     'organizationProfile.verifyDomainPage.subtitleVerificationCodeScreen',
     {
-      emailAddress: affiliationEmailAddressRef.current,
+      emailAddress: affiliationEmailAddressRef.current || '',
     },
   );
 
diff --git a/packages/clerk-js/src/ui/components/PricingTable/PricingTableDefault.tsx b/packages/clerk-js/src/ui/components/PricingTable/PricingTableDefault.tsx
@@ -247,11 +247,13 @@ function Card(props: CardProps) {
               order: ctaPosition === 'top' ? -1 : undefined,
             })}
           >
-            {shouldShowFooterNotice ? (
+            {shouldShowFooterNotice && subscription ? (
               <Text
                 elementDescriptor={descriptors.pricingTableCardFooterNotice}
                 variant={isCompact ? 'buttonSmall' : 'buttonLarge'}
-                localizationKey={localizationKeys('badge__startsAt', { date: subscription?.periodStart })}
+                localizationKey={localizationKeys('badge__startsAt', {
+                  date: subscription?.periodStart,
+                })}
                 colorScheme='secondary'
                 sx={t => ({
                   paddingBlock: t.space.$1x5,
diff --git a/packages/clerk-js/src/ui/components/SignIn/SignInFactorOneAlternativePhoneCodeCard.tsx b/packages/clerk-js/src/ui/components/SignIn/SignInFactorOneAlternativePhoneCodeCard.tsx
@@ -15,7 +15,7 @@ export const SignInFactorOneAlternativePhoneCodeCard = (props: SignInFactorOneAl
       <SignInFactorOneAlternativeChannelCodeForm
         {...props}
         cardTitle={localizationKeys('signIn.alternativePhoneCodeProvider.title', {
-          provider: getAlternativePhoneCodeProviderData(props.factor.channel)?.name,
+          provider: getAlternativePhoneCodeProviderData(props.factor.channel)?.name || '',
         })}
         cardSubtitle={localizationKeys('signIn.alternativePhoneCodeProvider.subtitle')}
         inputLabel={localizationKeys('signIn.alternativePhoneCodeProvider.formTitle')}
diff --git a/packages/clerk-js/src/ui/components/SignUp/SignUpPhoneCodeCard.tsx b/packages/clerk-js/src/ui/components/SignUp/SignUpPhoneCodeCard.tsx
@@ -58,8 +58,10 @@ export const SignUpPhoneCodeCard = withCardStateProvider(() => {
 
   if (isAlternativePhoneCodeProvider) {
     const provider = getAlternativePhoneCodeProviderData(channel)?.name;
-    cardTitleKey = localizationKeys('signUp.alternativePhoneCodeProvider.title', { provider });
-    cardSubtitleKey = localizationKeys('signUp.alternativePhoneCodeProvider.subtitle', { provider });
+    cardTitleKey = localizationKeys('signUp.alternativePhoneCodeProvider.title', { provider: provider || '' });
+    cardSubtitleKey = localizationKeys('signUp.alternativePhoneCodeProvider.subtitle', {
+      provider: provider || '',
+    });
     resendButtonKey = localizationKeys('signUp.alternativePhoneCodeProvider.resendButton');
   }
 
diff --git a/packages/clerk-js/src/ui/components/SignUp/SignUpStartAlternativePhoneCodePhoneNumberCard.tsx b/packages/clerk-js/src/ui/components/SignUp/SignUpStartAlternativePhoneCodePhoneNumberCard.tsx
@@ -75,7 +75,9 @@ export const SignUpStartAlternativePhoneCodePhoneNumberCard = (props: SignUpForm
               <Form.ControlRow elementId='phoneNumber'>
                 <Form.PhoneInput
                   {...formState.phoneNumber.props}
-                  label={localizationKeys('signUp.start.alternativePhoneCodeProvider.label', { provider })}
+                  label={localizationKeys('signUp.start.alternativePhoneCodeProvider.label', {
+                    provider: provider || '',
+                  })}
                   isRequired
                   isOptional={false}
                   actionLabel={undefined}
diff --git a/packages/clerk-js/src/ui/components/UserProfile/EmailForm.tsx b/packages/clerk-js/src/ui/components/UserProfile/EmailForm.tsx
@@ -86,7 +86,7 @@ export const EmailForm = withCardStateProvider((props: EmailFormProps) => {
       <FormContainer
         headerTitle={localizationKeys('userProfile.emailAddressPage.verifyTitle')}
         headerSubtitle={localizationKeys(`${translationKey}.formSubtitle`, {
-          identifier: emailAddressRef.current?.emailAddress,
+          identifier: emailAddressRef.current?.emailAddress || '',
         })}
       >
         {strategy === 'email_link' && (
diff --git a/packages/clerk-js/src/ui/components/UserProfile/MfaPhoneCodeScreen.tsx b/packages/clerk-js/src/ui/components/UserProfile/MfaPhoneCodeScreen.tsx
@@ -151,7 +151,7 @@ export const MFAVerifyPhone = (props: MFAVerifyPhoneProps) => {
     <FormContainer
       headerTitle={title}
       headerSubtitle={localizationKeys('userProfile.phoneNumberPage.verifySubtitle', {
-        identifier: resourceRef.current?.phoneNumber,
+        identifier: resourceRef.current?.phoneNumber || '',
       })}
     >
       <VerifyWithCode
diff --git a/packages/clerk-js/src/ui/components/UserProfile/PhoneForm.tsx b/packages/clerk-js/src/ui/components/UserProfile/PhoneForm.tsx
@@ -130,7 +130,7 @@ export const VerifyPhone = (props: VerifyPhoneProps) => {
     <FormContainer
       headerTitle={title}
       headerSubtitle={localizationKeys('userProfile.phoneNumberPage.verifySubtitle', {
-        identifier: resourceRef.current?.phoneNumber,
+        identifier: resourceRef.current?.phoneNumber || '',
       })}
     >
       <VerifyWithCode
diff --git a/packages/clerk-js/src/ui/components/UserProfile/RemoveResourceForm.tsx b/packages/clerk-js/src/ui/components/UserProfile/RemoveResourceForm.tsx
@@ -100,11 +100,11 @@ export const RemoveConnectedAccountForm = (props: ConnectedAccountFormProps) =>
     <RemoveResourceForm
       title={localizationKeys('userProfile.connectedAccountPage.removeResource.title')}
       messageLine1={localizationKeys('userProfile.connectedAccountPage.removeResource.messageLine1', {
-        identifier: providerToDisplayData[ref.current]?.name,
+        identifier: providerToDisplayData[ref.current]?.name || '',
       })}
       messageLine2={localizationKeys('userProfile.connectedAccountPage.removeResource.messageLine2')}
       successMessage={localizationKeys('userProfile.connectedAccountPage.removeResource.successMessage', {
-        connectedAccount: providerToDisplayData[ref.current]?.name,
+        connectedAccount: providerToDisplayData[ref.current]?.name || '',
       })}
       deleteResource={() => Promise.resolve(resource?.destroy())}
       onSuccess={onSuccess}
@@ -212,7 +212,7 @@ export const RemovePasskeyForm = (props: RemovePasskeyFormProps) => {
     <RemoveResourceForm
       title={localizationKeys('userProfile.passkeyScreen.removeResource.title')}
       messageLine1={localizationKeys('userProfile.passkeyScreen.removeResource.messageLine1', {
-        name: passkey.name,
+        name: passkey.name || '',
       })}
       deleteResource={passkey.delete}
       onSuccess={onSuccess}
diff --git a/packages/clerk-js/src/ui/components/UserProfile/VerifyWithCode.tsx b/packages/clerk-js/src/ui/components/UserProfile/VerifyWithCode.tsx
@@ -45,7 +45,9 @@ export const VerifyWithCode = (props: VerifyWithCodeProps) => {
       <Form.OTPInput
         {...otp}
         label={localizationKeys('userProfile.emailAddressPage.emailCode.formTitle')}
-        description={localizationKeys('userProfile.emailAddressPage.emailCode.formSubtitle', { identifier })}
+        description={localizationKeys('userProfile.emailAddressPage.emailCode.formSubtitle', {
+          identifier: identifier || '',
+        })}
         resendButton={localizationKeys('userProfile.emailAddressPage.emailCode.resendButton')}
         centerAlign={false}
       />
diff --git a/packages/clerk-js/src/ui/elements/LegalConsentCheckbox.tsx b/packages/clerk-js/src/ui/elements/LegalConsentCheckbox.tsx
@@ -23,16 +23,16 @@ const LegalCheckboxLabel = (props: { termsUrl?: string; privacyPolicyUrl?: strin
 
   if (termsUrl && privacyPolicyUrl) {
     localizationKey = localizationKeys('signUp.legalConsent.checkbox.label__termsOfServiceAndPrivacyPolicy', {
-      termsOfServiceLink: props.termsUrl,
-      privacyPolicyLink: props.privacyPolicyUrl,
+      termsOfServiceLink: termsUrl,
+      privacyPolicyLink: privacyPolicyUrl,
     });
   } else if (termsUrl) {
     localizationKey = localizationKeys('signUp.legalConsent.checkbox.label__onlyTermsOfService', {
-      termsOfServiceLink: props.termsUrl,
+      termsOfServiceLink: termsUrl,
     });
   } else if (privacyPolicyUrl) {
     localizationKey = localizationKeys('signUp.legalConsent.checkbox.label__onlyPrivacyPolicy', {
-      privacyPolicyLink: props.privacyPolicyUrl,
+      privacyPolicyLink: privacyPolicyUrl,
     });
   }
 
diff --git a/packages/clerk-js/src/ui/localization/localizationKeys.ts b/packages/clerk-js/src/ui/localization/localizationKeys.ts
@@ -1,6 +1,4 @@
-import type { PathValue, RecordToPath } from '@clerk/types';
-
-import type { defaultResource } from './defaultEnglishResource';
+import type { __internal_LocalizationResource, PathValue, RecordToPath } from '@clerk/types';
 
 type Value = string | number | boolean | Date;
 type Whitespace = ' ' | '\t' | '\n' | '\r';
@@ -61,20 +59,19 @@ export type GetICUArgs<Text extends string, T extends RemovePipeUtils<Text>> = T
   T extends readonly string[] ? TupleFindBlocks<T> : FindBlocks<T>
 >;
 
-type DefaultLocalizationKey = RecordToPath<typeof defaultResource>;
-type LocalizationKeyToValue<P extends DefaultLocalizationKey> = PathValue<typeof defaultResource, P>;
-
-// @ts-ignore
-type LocalizationKeyToParams<P extends DefaultLocalizationKey> = GetICUArgs<LocalizationKeyToValue<P>>;
+type DefaultLocalizationKey = RecordToPath<__internal_LocalizationResource>;
+type LocalizationKeyToValue<P extends DefaultLocalizationKey> = PathValue<__internal_LocalizationResource, P>;
 
 export type LocalizationKey = {
   key: string;
   params: Record<string, any> | undefined;
 };
 
-export const localizationKeys = <Key extends DefaultLocalizationKey, Params extends LocalizationKeyToParams<Key>>(
+type ExtractArgsFromValue<Value> = Value extends { __params: any } ? [params: Value['__params']] : [];
+
+export const localizationKeys = <Key extends DefaultLocalizationKey, Value extends LocalizationKeyToValue<Key>>(
   key: Key,
-  params?: keyof Params extends never ? never : Params,
+  ...args: ExtractArgsFromValue<Value>
 ): LocalizationKey => {
-  return { key, params } as LocalizationKey;
+  return { key, params: args[0] } as LocalizationKey;
 };
diff --git a/packages/types/src/localization.ts b/packages/types/src/localization.ts

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@clerk/types': minor
 +---
++
 +Expose `__internal_LocalizationResource` which now includes metadata for which keys require interpolation.
Original file line number	Diff line number	Diff line change
`@@ -50,7 +50,7 @@ export const VerifyDomainForm = withCardStateProvider((props: VerifyDomainFormPr`
`50`	`50`	`const subtitleVerificationCodeScreen = localizationKeys(`
`51`	`51`	`'organizationProfile.verifyDomainPage.subtitleVerificationCodeScreen',`
`52`	`52`	`{`
`53`		`- emailAddress: affiliationEmailAddressRef.current,`
	`53`	`+ emailAddress: affiliationEmailAddressRef.current \|\| '',`
`54`	`54`	`},`
`55`	`55`	`);`
`56`	`56`