first commit

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

@@ -0,0 +1,91 @@
+# 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.