# @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`.