# 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.