first commit

docs/localization/i18n/react-i18n/src/detector/fallback/fallback.md

@@ -0,0 +1,67 @@
+# fallbackDetector
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`fallbackDetector` is the unconditional terminal entry of every locale
+detector chain. It always returns the configured fallback locale, so the
+chain runner never resolves to `null` once the fallback detector has
+been installed. The constructor rejects empty or whitespace-only
+locales up-front so misconfigurations surface at build time rather than
+at the first chain invocation.
+
+The fallback detector is non-persisting — the chain runner never
+invokes `cache(...)` on it (and the spec scenario "switcher selection
+walks every persisting detector" explicitly excludes it from the
+walk).
+
+## Features
+
+- Always returns the configured locale (never `null`)
+- Constructor validates the input (throws for empty/whitespace/non-string)
+- `environment: "both"` — eligible everywhere
+- Non-persisting (no `cache` method)
+
+## Usage: Basic Example
+
+```ts
+import { fallbackDetector } from "@suaveplan/react-i18n/detector/fallback/fallback";
+import { createDetectorChain } from "@suaveplan/i18n/detector";
+
+const chain = createDetectorChain([fallbackDetector("en-GB")]);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { fallbackDetector } from "@suaveplan/react-i18n/detector/fallback/fallback";
+import { defaultDetectorChain } from "@suaveplan/react-i18n/detector/default-chain/default-chain";
+
+// `defaultDetectorChain` already installs the fallback as the last
+// entry; for ad-hoc chains assemble the same shape manually.
+const chain = [...defaultDetectorChain({ fallback: "en-GB" }).slice(0, -1), fallbackDetector("ja-JP")];
+```
+
+## API Reference
+
+### `fallbackDetector(locale: string): LocaleDetector`
+
+Returns a `LocaleDetector` with `name: "fallback"` and
+`environment: "both"`. Throws `Error("fallbackDetector requires a
+non-empty locale string")` when the supplied locale is empty,
+whitespace-only, or not a string.
+
+## Implementation Notes
+
+- The validation runs once, at construction time, so the per-detect
+  hot path is allocation-free.
+- The detector trims the supplied locale so consumers can safely pass
+  values from configuration files where surrounding whitespace is
+  common.
+- The detector exists as a separate first-class detector (rather than
+  a hard-coded property on the chain runner) so consumers can build
+  custom chains that omit the fallback step entirely — useful for
+  diagnostic UIs that want the chain to surface an explicit
+  "unresolved" state rather than fall back silently.