# defaultDetectorChain

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## 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

```ts
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

```ts
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.