first commit

docs/ui/react/react-ui/src/locales/augmentation.md

@@ -0,0 +1,74 @@
+# `augmentation` — `ContributedTranslationKeys` registration
+
+## Purpose
+
+Side-effect-only TypeScript module that augments
+`@suaveplan/react-i18n`'s `ContributedTranslationKeys` interface with
+every key shipped by the `@suaveplan/react-ui` chassis. The
+augmentation runs purely in TypeScript's type space — there is no
+runtime value to import — but the file is included as a side-effect
+import from `src/locales/index.ts` so consumers' `tsconfig` picks it
+up automatically when they `import "@suaveplan/react-ui"`.
+
+## Features
+
+- Module augmentation that registers every chassis translation key
+  into the branded `TranslationKey` union
+- Side-effect-only — zero runtime cost
+- Mirror of the canonical `en-GB.json` source-of-truth bundle so
+  consumer autocomplete in IDEs lists the chassis keys without
+  manually importing or copying them
+
+## Usage: Basic example
+
+```ts
+// In a consumer app:
+import "@suaveplan/react-ui";
+import { useTranslation } from "@suaveplan/react-i18n";
+
+function Toolbar() {
+    const { t } = useTranslation();
+    return <button>{t("react-ui.themeToggle.label")}</button>; // typechecks
+}
+```
+
+## Usage: Advanced example
+
+```ts
+// Compile-time error path:
+import "@suaveplan/react-ui";
+
+const key = "react-ui.dialog.cloze"; // typo; not in ContributedTranslationKeys
+t(key); // Type error: argument of type '"react-ui.dialog.cloze"' is not
+        // assignable to parameter of type 'TranslationKey'
+```
+
+## API Reference
+
+This file exposes no runtime values. Its sole effect is to extend the
+TypeScript type space:
+
+```ts
+declare module "@suaveplan/react-i18n" {
+    interface ContributedTranslationKeys {
+        readonly "react-ui.themeToggle.label": true;
+        // … one entry per key in en-GB.json
+    }
+}
+```
+
+After the augmentation lands, `TranslationKey` (defined in
+`@suaveplan/react-i18n` as `string & { ... } & (keyof AppTranslationKeys
+| keyof ContributedTranslationKeys)`) accepts the chassis keys as legal
+literal values.
+
+## Implementation notes
+
+The file is hand-edited in this version to mirror the canonical
+`en-GB.json` exactly. A future generator
+(`scripts/generate-translation-types.ts` from `@suaveplan/react-i18n`)
+will rewrite this file from the JSON whenever keys change so the type
+augmentation never drifts from runtime catalog contents. The empty
+`export {}` at the end is required so TypeScript treats the file as a
+module (not a script) — without it, the `declare module` block would
+be parsed in script mode and silently merged into the global scope.