97 lines
5.7 KiB
Markdown
97 lines
5.7 KiB
Markdown
# @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`.
|
|
|