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

fallbackDetector

(no submodules)

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

import { fallbackDetector } from "@suaveplan/react-i18n/detector/fallback/fallback";
import { createDetectorChain } from "@suaveplan/i18n/detector";

const chain = createDetectorChain([fallbackDetector("en-GB")]);

Usage: Advanced Example

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.