skills/docs/localization/i18n/react-i18n/src/detector/default-chain/default-chain.md

defaultDetectorChain

(no submodules)

Purpose

defaultDetectorChain is the canonical factory for the locale-detector chain consumed by <TranslationProvider> and the useLocaleDetection hook. It returns the standard 9-entry (or 8-entry, when userPreferenceEndpoint is omitted) detector list in the order mandated by the spec — explicit user intent (querystring) first, then per-user persistence (userPreference, cookie, localStorage), then shell hints (htmlLang), then platform negotiation (acceptLanguage, navigator), then geo (cloudflareIpGeo), and finally the unconditional fallback.

The factory is the single source of truth for chain ordering. Custom chains SHOULD start from this list and apply filter / map rather than re-implementing the order, so future chain additions land in every consumer automatically.

Features

• 9-entry chain when userPreferenceEndpoint is provided
• 8-entry chain when it is omitted (or empty)
• Fresh array on every call (mutating the result is safe)
• Fallback locale validation at construction time

Usage: Basic Example

import { defaultDetectorChain } from "@suaveplan/react-i18n/detector/default-chain/default-chain";
import { createDetectorChain } from "@suaveplan/i18n/detector";

const chain = createDetectorChain(
    defaultDetectorChain({ fallback: "en-GB" })
);

Usage: Advanced Example

import { defaultDetectorChain } from "@suaveplan/react-i18n/detector/default-chain/default-chain";
import { createDetectorChain } from "@suaveplan/i18n/detector";

// Skip Cloudflare in non-edge deployments and replace the default
// querystring param name with `?locale=`.
import { querystringDetector } from "@suaveplan/react-i18n/detector/querystring/querystring";

const detectors = defaultDetectorChain({
    fallback: "en-GB",
    userPreferenceEndpoint: "/api/me/locale",
})
    .filter((d) => d.name !== "cloudflareIpGeo")
    .map((d) =>
        d.name === "querystring"
            ? querystringDetector({ paramName: "locale" })
            : d
    );

const chain = createDetectorChain(detectors);

API Reference

defaultDetectorChain(options: DefaultDetectorChainOptions): LocaleDetector[]

Returns a fresh array of LocaleDetector objects in the canonical order. Throws if options.fallback is empty (the fallback detector's constructor performs the check).

DefaultDetectorChainOptions

Field	Type	Default	Description
fallback	string	—	Required. Locale used by the terminal fallbackDetector.
userPreferenceEndpoint	string	(omit)	URL passed to userPreferenceDetector. When absent (or empty) the userPreference detector is skipped.

Implementation Notes

• The chain is returned as a fresh array on every call so consumers can filter / map without affecting subsequent invocations or shared state.
• Empty userPreferenceEndpoint strings are treated identically to the field being omitted — a defensive guard for callers that produce the options bag from environment variables (process.env values default to empty strings, not undefined, in many runtimes).
• The factory deliberately exposes the canonical order only — there is no priority/weight mechanism on individual detectors. Consumers who need a different order should compose their own array.