first commit

docs/localization/i18n/i18n-backend-http/README.md

@@ -0,0 +1,96 @@
+# @suaveplan/i18n-backend-http - Universal translation backend backed by injectable fetch. Read-only; maps HTTP 404 to BACKEND_LOCALE_NOT_AVAILABLE (chain fallthrough) and HTTP 5xx / network / parse failures to BACKEND_READ_FAILED (chain stop). Pluggable parsePayload + customHeaders + retry policy + AbortSignal cancellation, OpenTelemetry instrumentation under i18n.backend.http.*. Zero runtime dependencies on @suaveplan/i18n core.
+
+## Summary
+
+Universal translation backend for the `@suaveplan/i18n` family,
+backed by an injectable `fetch`. Read-only by design: maps HTTP 404 to
+`BACKEND_LOCALE_NOT_AVAILABLE` (the chained-backend fallthrough signal)
+and HTTP 5xx, network failures, and parse failures to
+`BACKEND_READ_FAILED` (a chain-stopping signal that prevents silent
+degradation when the transport is broken). Pluggable `parsePayload`,
+`customHeaders`, `requestOptions`, `crossDomain` shorthand, retry-policy
+injection (structurally compatible with `@suaveplan/retry`'s
+`RetryPolicy`), `AbortSignal` cancellation, and OpenTelemetry
+instrumentation under `i18n.backend.http.*`. Zero runtime dependency on
+`@suaveplan/i18n` core.
+
+<!-- begin:auto-docs -->
+## Documentation tree
+
+- [backend](./src/backend/backend.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+  - [backend](./src/backend/backend.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+- [factory](./src/factory/factory.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+  - [factory](./src/factory/factory.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+- [observability](./src/observability/observability.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+  - [observability](./src/observability/observability.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
+<!-- end:auto-docs -->  - [backend](./src/backend/backend.md) — <!-- begin:auto-docs --> _(no submodules)_- [factory](./src/factory/factory.md) — <!-- begin:auto-docs --> _(no submodules)_- [factory](./src/factory/factory.md) — <!-- begin:auto-docs --> _(no submodules)_- [observability](./src/observability/observability.md) — <!-- begin:auto-docs --> _(no submodules)_- [observability](./src/observability/observability.md) — <!-- begin:auto-docs --> _(no submodules)_- [backend](./src/backend/backend.md) — <!-- begin:auto-docs --> _(no submodules)_- [factory](./src/factory/factory.md) — <!-- begin:auto-docs --> _(no submodules)_- [factory](./src/factory/factory.md) — <!-- begin:auto-docs --> _(no submodules)_- [observability](./src/observability/observability.md) — <!-- begin:auto-docs --> _(no submodules)_- [observability](./src/observability/observability.md) — <!-- begin:auto-docs --> _(no submodules)_- [backend](./src/backend/backend.md) — <!-- begin:auto-docs --> _(no submodules)_- [factory](./src/factory/factory.md) — <!-- begin:auto-docs --> _(no submodules)_- [factory](./src/factory/factory.md) — <!-- begin:auto-docs --> _(no submodules)_- [observability](./src/observability/observability.md) — <!-- begin:auto-docs --> _(no submodules)_- [observability](./src/observability/observability.md) — <!-- begin:auto-docs --> _(no submodules)_- [backend](./src/backend/backend.md) — <!-- begin:auto-docs --> _(no submodules)_- [factory](./src/factory/factory.md) — <!-- begin:auto-docs --> _(no submodules)_  - [factory](./src/factory/factory.md) — <!-- begin:auto-docs --> _(no submodules)_- [observability](./src/observability/observability.md) — <!-- begin:auto-docs --> _(no submodules)_  - [observability](./src/observability/observability.md) — <!-- begin:auto-docs --> _(no submodules)_
+## Why this exists
+
+The Wave 5 modular split lifts each backend out of the
+`@suaveplan/i18n` monolith into its own sibling so consumers can install
+only the backends they need. The HTTP backend is the canonical
+production source for browser-tier and edge consumers fetching
+translations from a CDN, an internal i18n service, or a pre-signed
+storage URL. Keeping it in its own package avoids dragging
+`@suaveplan/storage` (storage backend) or `node:fs` (multifile-fs
+backend) into browser bundles.
+
+## Install
+
+```bash
+bun add @suaveplan/i18n-backend-http
+```
+
+## Quick Start
+
+```ts
+import { httpBackend } from "@suaveplan/i18n-backend-http";
+
+const backend = httpBackend({
+    loadPath: "/i18n/{locale}/{namespace}.json",
+});
+
+const record = await backend.read("en", "auth");
+```
+
+## Modules
+
+| Subpath | Module |
+| --- | --- |
+| `@suaveplan/i18n-backend-http/backend` | [`HttpBackend`](./src/backend/backend.md) |
+| `@suaveplan/i18n-backend-http/factory` | [`httpBackend`](./src/factory/factory.md) |
+| `@suaveplan/i18n-backend-http/observability` | [OTel instruments](./src/observability/observability.md) |
+
+## Capabilities
+
+```ts
+{
+    canRead: true,
+    canReadMulti: false,
+    canSave: false,
+    canTrackModification: false,
+    canWatch: false,
+}
+```
+
+## Error semantics
+
+- HTTP 404 → `I18nError(I18N.BACKEND_LOCALE_NOT_AVAILABLE)` — chained
+  backend SHOULD fall through.
+- HTTP 5xx / non-2xx non-404 → `I18nError(I18N.BACKEND_READ_FAILED)` —
+  chained backend MUST propagate.
+- Network failure (`TypeError` from `fetch`) →
+  `I18nError(I18N.BACKEND_READ_FAILED)`.
+- AbortError mid-flight → `I18nError(I18N.BACKEND_TIMEOUT)`.
+- Pre-aborted `signal` → `I18nError(I18N.BACKEND_TIMEOUT)` (no
+  network request issued).
+- Parse failure → `I18nError(I18N.BACKEND_READ_FAILED)`.
+- Invalid options → `I18nError(I18N.INVALID_OPTIONS)` at construction.
+
+## Tier
+
+Universal — runs in browsers, Bun, and Node.js >= 18. On older Node
+runtimes lacking `globalThis.fetch`, `defaultFetch()` returns a stub
+that throws `BACKEND_READ_FAILED` with an explicit message instructing
+consumers to inject `fetchFn`.
+