refactor(mosaic): nest localization keys under their public component

.changeset/mosaic-localization-key-tree.md

@@ -0,0 +1,2 @@
+---
+---

packages/mosaic/ARCHITECTURE.md

@@ -204,8 +204,10 @@ user-button.styles.ts        // `stylex.create` atoms (see the StyleX authoring
 model nor the view owns it, and the two cannot drift.
 
 `*.messages.ts` holds strings only, exported as one `<feature>Messages` object
-declared `as const` and registered under a namespace in `src/localization/registry.ts`.
-Views read their namespace inside the component with `useMessages('userButton')`, so
+declared `as const` and mounted in `src/localization/registry.ts` under the public
+component it belongs to, such as `userProfile.mfa.backupCodes`. A root is a public
+component or a shared block, never a file name. Views read their root inside the
+component with `useMessages('userProfile').mfa`, so
 the `localization` prop on `MosaicProvider` can replace any string; a module-level
 helper takes the messages as a parameter rather than importing them.
 
@@ -243,6 +245,19 @@ so a consumer's overrides type-check against the real keys, as a dot path
 Renaming or moving a key breaks every override that names it; treat it like renaming
 a prop.
 
+The key tree follows what the user sees, so a key can be found from the screen:
+
+- A root is a public component (`userProfile`) or a shared block (`form`, `errors`).
+  There is no `common` root. The same English in two components is two keys,
+  because a translation may need to differ by context.
+- Below the root, keys nest by section, then by the dialog or step inside it:
+  `userProfile.email.addDialog`, `userProfile.email.removeDialog`.
+- Copy that several views render through one shared component belongs to that
+  component (`userProfile.contact` for the row both email and phone use).
+- Every segment is camelCase. A map keyed by data ids (`errors`, `roles`,
+  `userProfile.mfa.methods`) keeps the ids as its keys;
+  `src/localization/__tests__/registry.test.ts` lists those maps and checks the rest.
+
 ### Composition
 
 Two shapes, chosen by whether the slice fetches its own data.

packages/mosaic/docs/views.md

@@ -48,13 +48,26 @@ Every string a view renders comes from the feature's `*.messages.ts`, shaped the
 way `@clerk/i18n` takes a base definition. A plural message is its forms; a
 parameterized one is its template.
 
-Register the file as a namespace in `src/localization/registry.ts`, then read it
-with `useMessages` in the view or controller that renders it:
+To add copy for a new section, step or dialog:
+
+1. Put the strings in the `*.messages.ts` next to the view that renders them. Name
+   each key for what the string is (`label`, `resend`, `confirm`), not where it
+   sits in the markup.
+2. Mount the object in `src/localization/registry.ts` under the public component
+   the user sees it in: a section of `UserProfile` goes at `userProfile.<section>`,
+   and a dialog inside it at `userProfile.<section>.addDialog` or `.removeDialog`.
+   Copy two views share goes under the component that renders it, never under a
+   new `common` root.
+3. Read it with `useMessages` and the root, in the view or controller that
+   renders it:
 
 ```tsx
-const m = useMessages('userButton');
+const m = useMessages('userProfile').mfa;
 ```
 
+The rules behind these steps are in [ARCHITECTURE.md](../ARCHITECTURE.md), and
+`src/localization/__tests__/registry.test.ts` fails on a key that is not camelCase.
+
 Never import a `*.messages.ts` directly. A direct import skips the customer's
 locale and overrides, so the copy can't be localized.
 

packages/mosaic/src/features/api-keys/__tests__/api-keys-table.feature.test.tsx

@@ -247,9 +247,9 @@ describe('APIKeysTable', () => {
         <MosaicProvider
           localization={{
             overrides: {
-              'apiKeysTable.search': 'Find a key',
-              'apiKeysTable.expires': 'Expiration: {expiresDate}',
-              'apiKeysTable.revokeTitle': 'Retirer {name} ?',
+              'apiKeys.search': 'Find a key',
+              'apiKeys.expires': 'Expiration: {expiresDate}',
+              'apiKeys.revokeTitle': 'Retirer {name} ?',
             },
           }}
         >

packages/mosaic/src/features/api-keys/api-keys-table.messages.ts

@@ -69,7 +69,7 @@ export const apiKeysTableMessages = {
 } as const;
 
 export function resolveAPIKeysTableMessages(
-  catalog: MosaicMessages['apiKeysTable'],
+  catalog: MosaicMessages['apiKeys'],
   subjectKind: APIKeysTableSubjectKind,
   overrides?: Partial<APIKeysTableMessages>,
 ): APIKeysTableMessages {

packages/mosaic/src/features/api-keys/api-keys-table.tsx

@@ -38,7 +38,7 @@ function SubjectAPIKeysTable({
   fallback,
 }: APIKeysTableProps) {
   const messages = resolveAPIKeysTableMessages(
-    useMessages('apiKeysTable'),
+    useMessages('apiKeys'),
     isOrganizationId(subject) ? 'organization' : 'user',
     overrides,
   );

packages/mosaic/src/features/api-keys/api-keys-table.types.ts

@@ -20,7 +20,7 @@ export type APIKeysTableSubjectKind = 'user' | 'organization';
 
 type Strings<T> = { readonly [K in keyof T]: T[K] extends string ? string : Strings<T[K]> };
 
-export type APIKeysTableMessages = Strings<Omit<MosaicMessages['apiKeysTable'], 'noKeysDescription'>> & {
+export type APIKeysTableMessages = Strings<Omit<MosaicMessages['apiKeys'], 'noKeysDescription'>> & {
   readonly noKeysDescription: string;
 };
 

packages/mosaic/src/features/organization-profile/organization-profile-danger-section/organization-profile-danger-section.view.tsx

@@ -17,7 +17,7 @@ export function OrganizationProfileDangerSectionView({
   leave,
   destroy,
 }: OrganizationProfileDangerSectionViewProps) {
-  const m = useMessages('organizationProfileDangerSection');
+  const m = useMessages('organizationProfile').danger;
   const locale = useLocale();
 
   if (!leave && !destroy) {
@@ -78,7 +78,7 @@ function DangerRow({
   dialogTitle: string;
   dialogDescription: string;
 }) {
-  const m = useMessages('organizationProfileDangerSection');
+  const m = useMessages('organizationProfile').danger;
 
   return (
     <Section.Row>

packages/mosaic/src/features/organization-profile/organization-profile-members-panel/invitations-table-tab.controller.ts

@@ -12,7 +12,7 @@ export function useInvitationsTableController(
 ): InvitationsTableTabViewProps {
   const locale = useLocale();
   const roleNames = useMessages('roles');
-  const m = useMessages('invitationsTableTab');
+  const m = useMessages('organizationProfile').members.invitations;
   const invitations = model.rows.map(({ id, emailAddress, createdAt, role, roleName }) => ({
     id,
     email: emailAddress,

packages/mosaic/src/features/organization-profile/organization-profile-members-panel/invitations-table-tab.skeleton.tsx

@@ -44,7 +44,7 @@ export function InvitationsTableTabSkeleton({
   hasRevoke: boolean;
   hasBulkAction: boolean;
 }) {
-  const m = useMessages('invitationsTableTab');
+  const m = useMessages('organizationProfile').members.invitations;
   return (
     <div
       {...mergeStyleProps(themeProps('invitations-table-tab'), stylex.props(tableTabStyles.root))}

packages/mosaic/src/features/organization-profile/organization-profile-members-panel/invitations-table-tab.view.tsx

@@ -38,7 +38,7 @@ export function InvitationsTableTabView({
   isError = false,
   onRetry,
 }: InvitationsTableTabViewProps) {
-  const m = useMessages('invitationsTableTab');
+  const m = useMessages('organizationProfile').members.invitations;
   const showPagination = Math.ceil(totalCount / pageSize) > 1;
   return (
     <>
@@ -136,7 +136,7 @@ function InvitationsTableBody({
   onRevokeClick?: (invitation: OrganizationProfileInvitation) => void;
   registerTrigger: (id: string) => Ref<HTMLButtonElement>;
 }) {
-  const m = useMessages('invitationsTableTab');
+  const m = useMessages('organizationProfile').members.invitations;
   return (
     <Table.Body
       items={invitations}

packages/mosaic/src/features/organization-profile/organization-profile-members-panel/members-table-tab.controller.ts

@@ -15,7 +15,7 @@ export function useMembersTableController(
   { roles, isLoading: isLoadingRoles }: MembersRolesState,
 ) {
   const locale = useLocale();
-  const messages = useMessages('membersTableTab');
+  const messages = useMessages('organizationProfile').members.list;
   const roleNames = useMessages('roles');
   const roleAction = usePendingAction({ errorFallback: messages.roleChangeError });
   const members = model.rows.map(({ joinedAt, ...member }) => ({

packages/mosaic/src/features/organization-profile/organization-profile-members-panel/members-table-tab.skeleton.tsx

@@ -51,7 +51,7 @@ export function MembersTableTabSkeleton({
   hasRemove: boolean;
   hasBulkAction: boolean;
 }) {
-  const m = useMessages('membersTableTab');
+  const m = useMessages('organizationProfile').members.list;
   return (
     <div {...mergeStyleProps(themeProps('members-table-tab'), stylex.props(tableTabStyles.root))}>
       <VisuallyHidden role='status'>{m.loading}</VisuallyHidden>

packages/mosaic/src/features/organization-profile/organization-profile-members-panel/members-table-tab.view.tsx

@@ -51,7 +51,7 @@ export function MembersTableTabView({
   isChangingRole = false,
   roleError,
 }: MembersTableTabViewProps) {
-  const m = useMessages('membersTableTab');
+  const m = useMessages('organizationProfile').members.list;
   const query = searchValue.trim();
   const showPagination = Math.ceil(totalCount / pageSize) > 1;
   return (
@@ -148,7 +148,7 @@ function MembersTableNotices({
   hasRoleSetMigration,
   roleError,
 }: Pick<MembersTableTabViewProps, 'hasRoleSetMigration' | 'roleError'>) {
-  const m = useMessages('membersTableTab');
+  const m = useMessages('organizationProfile').members.list;
   return (
     <>
       {hasRoleSetMigration ? (
@@ -194,7 +194,7 @@ function MembersTableBody({
   onRemoveClick?: (member: OrganizationProfileMember) => void;
   registerTrigger: (id: string) => Ref<HTMLButtonElement>;
 }) {
-  const m = useMessages('membersTableTab');
+  const m = useMessages('organizationProfile').members.list;
   return (
     <Table.Body
       items={members}
@@ -253,7 +253,7 @@ function MemberRow({
   onRemoveClick?: () => void;
   triggerRef?: Ref<HTMLButtonElement>;
 }) {
-  const m = useMessages('membersTableTab');
+  const m = useMessages('organizationProfile').members.list;
   const manageable = canManageMember(member);
   return (
     <Table.Row

packages/mosaic/src/features/organization-profile/organization-profile-members-panel/organization-profile-invite-members.controller.ts

@@ -20,7 +20,7 @@ export interface InviteMembersControllerOptions {
 }
 
 export function useInviteMembersController({ roles, defaultRole, invite }: InviteMembersControllerOptions) {
-  const m = useMessages('organizationProfileInviteMembers');
+  const m = useMessages('organizationProfile').members.invite;
   const roleNames = useMessages('roles');
   const locale = useLocale();
   const toast = useToastManager();

packages/mosaic/src/features/organization-profile/organization-profile-members-panel/organization-profile-invite-members.dialog.tsx

@@ -46,7 +46,7 @@ export function OrganizationProfileInviteMembersDialog({
   error,
   onSubmit,
 }: OrganizationProfileInviteMembersDialogProps) {
-  const m = useMessages('organizationProfileInviteMembers');
+  const m = useMessages('organizationProfile').members.invite;
   const formId = useId();
   const emailInput = useRef<HTMLInputElement>(null);
   const isValid = (value: string) => isEmail(value) && !rejectedEmailAddresses.includes(value);

packages/mosaic/src/features/organization-profile/organization-profile-members-panel/organization-profile-members-panel.view.tsx

@@ -31,9 +31,9 @@ export function OrganizationProfileMembersPanelView({
   inviteDialog,
 }: OrganizationProfileMembersPanelViewProps) {
   const m = useMessages('organizationProfile');
-  const membersMessages = useMessages('membersTableTab');
-  const invitationsMessages = useMessages('invitationsTableTab');
-  const requestsMessages = useMessages('requestsTableTab');
+  const membersMessages = useMessages('organizationProfile').members.list;
+  const invitationsMessages = useMessages('organizationProfile').members.invitations;
+  const requestsMessages = useMessages('organizationProfile').members.requests;
   const tabs = [
     {
       id: 'members',

packages/mosaic/src/features/organization-profile/organization-profile-members-panel/requests-table-tab.skeleton.tsx

@@ -47,7 +47,7 @@ export function RequestsTableTabSkeleton({
   hasDecline: boolean;
   hasBulkAction: boolean;
 }) {
-  const m = useMessages('requestsTableTab');
+  const m = useMessages('organizationProfile').members.requests;
   const hasActions = hasAccept || hasDecline;
   return (
     <div

packages/mosaic/src/features/organization-profile/organization-profile-members-panel/requests-table-tab.view.tsx

@@ -42,7 +42,7 @@ export function RequestsTableTabView({
   isError = false,
   onRetry,
 }: RequestsTableTabViewProps) {
-  const m = useMessages('requestsTableTab');
+  const m = useMessages('organizationProfile').members.requests;
   const showPagination = Math.ceil(totalCount / pageSize) > 1;
   const hasActions = Boolean(onAccept || onDecline);
   return (
@@ -137,7 +137,7 @@ function RequestsTableBody({
   registerAcceptTrigger?: (id: string) => Ref<HTMLButtonElement>;
   registerDeclineTrigger?: (id: string) => Ref<HTMLButtonElement>;
 }) {
-  const m = useMessages('requestsTableTab');
+  const m = useMessages('organizationProfile').members.requests;
   return (
     <Table.Body
       items={requests}
@@ -218,7 +218,7 @@ function RequestActions({
   registerAcceptTrigger?: (id: string) => Ref<HTMLButtonElement>;
   registerDeclineTrigger?: (id: string) => Ref<HTMLButtonElement>;
 }) {
-  const m = useMessages('requestsTableTab');
+  const m = useMessages('organizationProfile').members.requests;
   const [acceptRef] = useState(() => registerAcceptTrigger?.(request.id));
   const [declineRef] = useState(() => registerDeclineTrigger?.(request.id));
   const actions = usePendingAction<'accept' | 'decline'>();

packages/mosaic/src/features/organization-profile/organization-profile-profile-section/organization-profile-edit-name.dialog.tsx

@@ -28,7 +28,7 @@ export function OrganizationProfileEditNameDialog({
   trigger,
   form,
 }: OrganizationProfileEditNameDialogProps) {
-  const m = useMessages('organizationProfileProfileSection');
+  const m = useMessages('organizationProfile').profile;
   const inputRef = useRef<HTMLInputElement>(null);
   const { feedback } = form.fields.name;
   const { ref, ...control } = form.register('name');

packages/mosaic/src/features/organization-profile/organization-profile-profile-section/organization-profile-edit-slug.dialog.tsx

@@ -28,7 +28,7 @@ export function OrganizationProfileEditSlugDialog({
   trigger,
   form,
 }: OrganizationProfileEditSlugDialogProps) {
-  const m = useMessages('organizationProfileProfileSection');
+  const m = useMessages('organizationProfile').profile;
   const inputRef = useRef<HTMLInputElement>(null);
   const { feedback } = form.fields.slug;
   const { ref, ...control } = form.register('slug');

packages/mosaic/src/features/organization-profile/organization-profile-profile-section/organization-profile-logo-row.view.tsx

@@ -39,7 +39,7 @@ export function OrganizationProfileLogoRowView({
   onReject,
   onRemove,
 }: OrganizationProfileLogoRowViewProps) {
-  const m = useMessages('organizationProfileProfileSection');
+  const m = useMessages('organizationProfile').profile;
   const errorText = useErrorText();
   const logo = useOrganizationProfileLogoController({ onChange, onRemove });
   const [rejection, setRejection] = useState<LocalizableError>();
@@ -115,7 +115,7 @@ function LogoActions({
   canChange: boolean;
   onRemove?: () => Promise<void>;
 }) {
-  const m = useMessages('organizationProfileProfileSection');
+  const m = useMessages('organizationProfile').profile;
   const { openFilePicker } = FileUpload.useFileUpload();
   const actions: ActionMenuAction[] = [];
 

packages/mosaic/src/features/organization-profile/organization-profile-profile-section/organization-profile-name-row.view.tsx

@@ -10,7 +10,7 @@ interface OrganizationProfileNameRowViewProps {
 }
 
 export function OrganizationProfileNameRowView({ name, onSubmit }: OrganizationProfileNameRowViewProps) {
-  const m = useMessages('organizationProfileProfileSection');
+  const m = useMessages('organizationProfile').profile;
   return (
     <Section.Row>
       <Section.Item>
@@ -32,7 +32,7 @@ export function OrganizationProfileNameRowView({ name, onSubmit }: OrganizationP
 }
 
 function EditName({ name, onSubmit }: { name: string; onSubmit: (name: string) => Promise<void> }) {
-  const m = useMessages('organizationProfileProfileSection');
+  const m = useMessages('organizationProfile').profile;
   const controller = useOrganizationProfileEditNameController({ name, onSubmit });
 
   return (

packages/mosaic/src/features/organization-profile/organization-profile-profile-section/organization-profile-profile-section.view.tsx

@@ -28,7 +28,7 @@ export function OrganizationProfileProfileSectionView({
   onSubmitName,
   onSubmitSlug,
 }: OrganizationProfileProfileSectionViewProps) {
-  const m = useMessages('organizationProfileProfileSection');
+  const m = useMessages('organizationProfile').profile;
 
   return (
     <Section.Root>

packages/mosaic/src/features/organization-profile/organization-profile-profile-section/organization-profile-slug-row.view.tsx

@@ -15,7 +15,7 @@ interface OrganizationProfileSlugRowViewProps {
 }
 
 export function OrganizationProfileSlugRowView({ slug, onSubmit }: OrganizationProfileSlugRowViewProps) {
-  const m = useMessages('organizationProfileProfileSection');
+  const m = useMessages('organizationProfile').profile;
   return (
     <Section.Row>
       <Section.Item>
@@ -52,7 +52,7 @@ export function OrganizationProfileSlugRowView({ slug, onSubmit }: OrganizationP
 }
 
 function EditSlug({ slug, onSubmit }: { slug: string; onSubmit: (slug: string) => Promise<void> }) {
-  const m = useMessages('organizationProfileProfileSection');
+  const m = useMessages('organizationProfile').profile;
   const controller = useOrganizationProfileEditSlugController({ slug, onSubmit });
 
   return (

packages/mosaic/src/features/reverification/__tests__/reverification.feature.test.tsx

@@ -1666,7 +1666,7 @@ describe('Reverification', () => {
         guardedAction(),
         verificationSeed({ firstFactors: [passwordFactor] }),
         {
-          messages: { 'reverification.unstable__errors__generic': 'Something custom went wrong' },
+          messages: { 'reverification.attemptFailed': 'Something custom went wrong' },
         },
       );
       const user = await startVerification();

packages/mosaic/src/features/reverification/reverification.controller.ts

@@ -495,7 +495,7 @@ function useReverificationState(model: ReverificationModel): ReverificationContr
       direction: context.direction,
       value: context.inputValue,
       onValueChange: (value: string) => send({ type: 'TYPE', value }),
-      errorMessage: context.error ? (context.error.detail ?? m.unstable__errors__generic) : undefined,
+      errorMessage: context.error ? (context.error.detail ?? m.attemptFailed) : undefined,
       isPending: pendingStates.has(state),
       onSubmit: () => send({ type: 'SUBMIT' }),
       onShowMethods: () => send({ type: 'SHOW_METHODS' }),