first commit

docs/localization/i18n/react-i18n/src/components/i18n-suspense/fallback-bundle.md

@@ -0,0 +1,72 @@
+# `react-i18n.suspense.*` fallback bundle
+
+## Purpose
+
+Ships the strings that `<I18nSuspense>` needs before the active catalog
+loads its own copies. Consumers can override these keys by adding entries
+under the same dotted path in their own catalog (the catalog's `t()` will
+prefer the consumer-provided value). Without this bundle the screen-
+reader-only loading label would either be hardcoded English (violating
+the package-wide no-hardcoded-strings rule) or empty (a poor a11y
+experience while a backend round-trip is in flight).
+
+The bundle is intentionally tiny — only the strings rendered inside the
+React-i18n package itself live here. Application-facing copy belongs in
+the consumer's own catalog.
+
+## Features
+
+- One frozen object: `REACT_I18N_FALLBACK_BUNDLE`
+- Two-token interface: `ReactI18nFallbackKey` enumerates every key
+- Stringly-typed values: zero runtime cost, plain JSON
+- Consumer override: any key the active catalog defines wins
+
+## Usage: Basic Example
+
+```ts
+import {
+    REACT_I18N_FALLBACK_BUNDLE,
+    type ReactI18nFallbackKey,
+} from "@suaveplan/react-i18n/components/i18n-suspense/fallback-bundle";
+
+const label = REACT_I18N_FALLBACK_BUNDLE["react-i18n.suspense.loading"];
+//    ^? string
+```
+
+## Usage: Advanced Example
+
+Resolving a fallback key with the consumer-provided override taking
+precedence over the bundled default:
+
+```ts
+import { REACT_I18N_FALLBACK_BUNDLE } from "@suaveplan/react-i18n/components/i18n-suspense/fallback-bundle";
+
+function resolveLoading(i18n: { catalog: { has(k: string): boolean; t(k: string): string } }): string {
+    const key = "react-i18n.suspense.loading";
+    return i18n.catalog.has(key)
+        ? i18n.catalog.t(key)
+        : REACT_I18N_FALLBACK_BUNDLE[key];
+}
+```
+
+## API Reference
+
+### `REACT_I18N_FALLBACK_BUNDLE: Record<ReactI18nFallbackKey, string>`
+
+Frozen mapping of fallback keys to their default English strings.
+
+### `ReactI18nFallbackKey`
+
+Union of every legal key in the bundle. Currently:
+
+- `'react-i18n.suspense.loading'`
+
+## Implementation Notes
+
+- The bundle ships in source form (no JSON parse cost) so there is zero
+  runtime initialisation overhead.
+- New keys added here MUST be documented in this file and surfaced
+  through the public exports of the consuming module so consumers know
+  which keys are eligible for override.
+- The strings are deliberately concise. Suspense fallbacks are short-lived;
+  long sentences confuse screen-reader users who navigate by character.