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

Author: alexcarpenter

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

@@ -0,0 +1,5 @@
+---
+'@clerk/mosaic': patch
+---
+
+Nest localization keys under the component they appear in, for example `userProfileMfa.label` is now `userProfile.mfa.label`. Update any `localization` overrides that use the old keys; TypeScript flags each one.

packages/mosaic/ARCHITECTURE.md

@@ -208,8 +208,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.
 
@@ -247,6 +249,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))}