skills/plugins/document-navigator/docs/localization/i18n/i18n-backend-http

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

Documentation tree

• backend — (no submodules)
  • backend — (no submodules)
• factory — (no submodules)
  • factory — (no submodules)
• observability — (no submodules)
  • observability — (no submodules)

- [backend](./src/backend/backend.md) — _(no submodules)_- [factory](./src/factory/factory.md) — _(no submodules)_- [factory](./src/factory/factory.md) — _(no submodules)_- [observability](./src/observability/observability.md) — _(no submodules)_- [observability](./src/observability/observability.md) — _(no submodules)_- [backend](./src/backend/backend.md) — _(no submodules)_- [factory](./src/factory/factory.md) — _(no submodules)_- [factory](./src/factory/factory.md) — _(no submodules)_- [observability](./src/observability/observability.md) — _(no submodules)_- [observability](./src/observability/observability.md) — _(no submodules)_- [backend](./src/backend/backend.md) — _(no submodules)_- [factory](./src/factory/factory.md) — _(no submodules)_- [factory](./src/factory/factory.md) — _(no submodules)_- [observability](./src/observability/observability.md) — _(no submodules)_- [observability](./src/observability/observability.md) — _(no submodules)_- [backend](./src/backend/backend.md) — _(no submodules)_- [factory](./src/factory/factory.md) — _(no submodules)_ - [factory](./src/factory/factory.md) — _(no submodules)_- [observability](./src/observability/observability.md) — _(no submodules)_ - [observability](./src/observability/observability.md) — _(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

bun add @suaveplan/i18n-backend-http

Quick Start

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
@suaveplan/i18n-backend-http/factory	httpBackend
@suaveplan/i18n-backend-http/observability	OTel instruments

Capabilities

{
    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.