first commit

docs/ui/react/react-auth/src/translations/cy-gb.md

@@ -0,0 +1,37 @@
+# `cy-gb`
+
+## Purpose
+
+`cy-gb.ts` ships the Welsh (Cymraeg, `cy-GB`) translation pack for the auth surface. The file conforms structurally to `AuthTranslationPack` — every key present in `en-gb.ts` MUST be present here, otherwise `tsc` fails the typecheck gate. This guarantees Wave 2 form components can resolve any key in any locale without locale-specific guards. Pure data; no runtime code.
+
+## Features
+
+- Welsh copy across all 10 functional groups.
+- Compile-time conformance to `AuthTranslationPack`.
+- Default-exported for direct consumption (`import cyGb from "@suaveplan/react-auth/translations"`).
+
+## Usage: Basic
+
+```ts
+import { cyGb } from "@suaveplan/react-auth";
+console.log(cyGb.auth.login.title); // "Mewngofnodi"
+```
+
+## Usage: Advanced
+
+```ts
+import { authTranslations } from "@suaveplan/react-auth";
+
+function detectLocaleAndResolve(prefersWelsh: boolean) {
+    const locale = prefersWelsh ? "cy-gb" : "en-gb";
+    return authTranslations[locale].auth.login.forgotPassword;
+}
+```
+
+## API Reference
+
+- `default` — the Welsh translation pack of type `AuthTranslationPack`.
+
+## Implementation Notes
+
+Translations are reviewed by a fluent Welsh speaker before each release; the strings here are the verbatim upstream copy. When a string would mention a date or a number, the Wave 2 form components will inject ICU-formatted values through `@suaveplan/i18n-icu-parser` — the strings stored here intentionally avoid pre-formatted numerics. Punctuation conventions (e.g. apostrophe usage, full-stop placement in error messages) follow standard editorial conventions for Welsh, matching the upstream pack.

docs/ui/react/react-auth/src/translations/en-gb.md

@@ -0,0 +1,44 @@
+# `en-gb`
+
+## Purpose
+
+`en-gb.ts` ships the British-English string table consumed by the Wave 2 forms and Wave 3 page components. The file also defines the canonical `AuthTranslationPack` shape (broken into 10 named sub-interfaces — login, register, forgotPassword, resetPassword, emailVerification, profile, validation, errors, success, loading — so every locale conforms to the same structural contract). The default-exported object literal serves as both the production string source and the structural baseline against which `cy-gb` and `zh-cn` are checked at compile time. No runtime code; pure data.
+
+## Features
+
+- `AuthTranslationPack` interface (and 10 sub-interfaces) — structural shape every locale conforms to.
+- Default-exported object literal with British-English copy across 10 functional groups.
+- Compile-time pin: a missing or extra key in any locale fails `tsc`.
+
+## Usage: Basic
+
+```ts
+import enGb from "@suaveplan/react-auth";
+
+console.log(enGb.auth.login.title); // "Sign In"
+```
+
+## Usage: Advanced
+
+Resolve a translation key from the active locale by walking the typed map:
+
+```ts
+import { authTranslations, type AuthTranslationPack } from "@suaveplan/react-auth";
+
+type LocaleKey = "en-gb" | "cy-gb" | "zh-cn";
+
+function tLogin(locale: LocaleKey, key: keyof AuthTranslationPack["auth"]["login"]) {
+    return authTranslations[locale].auth.login[key];
+}
+```
+
+## API Reference
+
+- `interface AuthLoginStrings` / `AuthRegisterStrings` / `AuthForgotPasswordStrings` / `AuthResetPasswordStrings` / `AuthEmailVerificationStrings` / `AuthProfileStrings` / `AuthValidationStrings` / `AuthErrorStrings` / `AuthSuccessStrings` / `AuthLoadingStrings` — section interfaces.
+- `interface AuthStrings` — aggregate of the section interfaces.
+- `interface AuthTranslationPack` — `{ auth: AuthStrings }`.
+- `default` — the British-English translation pack.
+
+## Implementation Notes
+
+The interface is defined here (not in `types/`) because it co-locates with the canonical source-of-truth string set. The compile-time conformance check on `cy-gb` and `zh-cn` works because each locale annotates its module-level constant with `: AuthTranslationPack`; if a section is missing or a typo introduces an extra field, `tsc` fails the typecheck gate. The `as const` pattern is deliberately avoided here — using a structural interface (not literal narrowing) lets translators ship variant copy without retyping the schema, and prevents the cross-locale assignment errors seen in upstream's first port.

docs/ui/react/react-auth/src/translations/zh-cn.md

@@ -0,0 +1,36 @@
+# `zh-cn`
+
+## Purpose
+
+`zh-cn.ts` ships the Simplified-Chinese (`zh-CN`) translation pack for the auth surface. The file conforms structurally to `AuthTranslationPack`; every key from `en-gb.ts` is present, otherwise the typecheck gate fails. Wave 2 form components resolve keys against this pack identically to any other locale. Pure data; no runtime code.
+
+## Features
+
+- Simplified-Chinese copy across all 10 functional groups.
+- Compile-time conformance to `AuthTranslationPack`.
+- Default-exported for direct consumption.
+
+## Usage: Basic
+
+```ts
+import { zhCn } from "@suaveplan/react-auth";
+console.log(zhCn.auth.login.title); // "登录"
+```
+
+## Usage: Advanced
+
+```ts
+import { authTranslations } from "@suaveplan/react-auth";
+
+function localisedRegister() {
+    return authTranslations["zh-cn"].auth.register;
+}
+```
+
+## API Reference
+
+- `default` — the Simplified-Chinese translation pack of type `AuthTranslationPack`.
+
+## Implementation Notes
+
+Translations are reviewed by a native speaker before each release. Punctuation follows Simplified-Chinese conventions: full-width commas (`，`) and full stops (`。`) where the English source uses ASCII punctuation, and quotation marks rendered as ASCII double-quotes only when wrapping a literal token like `"DELETE"`. Numerals stay ASCII for downstream ICU formatting. The pack is sized to match `en-gb` byte-for-byte structurally — translators add or remove copy by editing the upstream `en-gb.ts` first and propagating the schema change here.