docs(mosaic): document how localization keys are named and placed

Author: alexcarpenter

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

@@ -2,4 +2,4 @@
 '@clerk/mosaic': minor
 ---
 
-Reorganize localization keys under the component they belong to. Section and dialog strings now nest under their component instead of sitting at the top level, for example `userProfileMfa.label` is now `userProfile.mfa.label`, `membersTableTab.title` is now `organizationProfile.members.list.title`, and `apiKeysTable.search` is now `apiKeys.search`. Email and phone strings moved from `userProfileContact.email` and `userProfileContact.phone` to `userProfile.email` and `userProfile.phone`. Update any `localization` overrides that use the old keys; TypeScript flags each one.
+Reorganize localization keys under the component they belong to. Section and dialog strings now nest under their component instead of sitting at the top level, for example `userProfileMfa.label` is now `userProfile.mfa.label`, `membersTableTab.title` is now `organizationProfile.members.list.title`, and `apiKeysTable.search` is now `apiKeys.search`. Email and phone strings moved from `userProfileContact.email` and `userProfileContact.phone` to `userProfile.email` and `userProfile.phone`. Reverification keys now use plain names, for example `reverification.alternativeMethods.blockButton__password` is now `reverification.methods.password` and `reverification.formButtonPrimary` is now `reverification.continue`; keys no reverification screen rendered were removed. Update any `localization` overrides that use the old keys; TypeScript flags each one.

packages/mosaic/ARCHITECTURE.md

@@ -245,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.