5.2 KiB
@suaveplan/i18n-backend-fs-multifile - Server-tier multi-file Node fs/promises translation backend for the @suaveplan/i18n family. Reads //. (nested), /.. (flat), or a caller-supplied glob pattern. JSON built-in; YAML and JSON5 auto-detected via dynamic import. Optional fs.watch loop emits loaded events through the catalog event bus. AbortSignal cancellation, OpenTelemetry instrumentation under i18n.backend.fs_multifile.*. Server-only — uses node:fs/promises; browser consumers should use @suaveplan/i18n-backend-http or @suaveplan/i18n-backend-storage.
Summary
Server-tier package — uses
node:fs/promises. For browser consumers, use@suaveplan/i18n-backend-httpor@suaveplan/i18n-backend-storage.
Server-tier translation backend for the @suaveplan/i18n family. Reads
locale + namespace catalogs from the local filesystem in three wire layouts,
optionally watches the root directory for changes, and emits loaded events
into the catalog event bus so React Suspense / HMR consumers refresh without
polling. JSON is built in; YAML and JSON5 are auto-detected via dynamic
import() so the package stays lean and the consumer picks the parser.
The backend implements the universal Backend contract from
@suaveplan/types — capabilities matrix { canRead, canReadMulti: false, canSave, canTrackModification, canWatch } — and conforms to the
runBackendConformance harness shipped from
@suaveplan/i18n-shared/testing. Errors are surfaced via I18nError from
@suaveplan/i18n-shared: ENOENT/ENOTDIR map to
BACKEND_LOCALE_NOT_AVAILABLE (so a chained-backend can fall through to
the next layer), other errno codes map to BACKEND_READ_FAILED, and a
pre-aborted AbortSignal short-circuits with BACKEND_TIMEOUT without
touching the filesystem. OpenTelemetry instruments are emitted under the
i18n.backend.fs_multifile.* prefix with a layout attribute.
Documentation tree
- backend — (no submodules)
- backend — (no submodules)
- factory — (no submodules)
- factory — (no submodules)
- observability — (no submodules)
- observability — (no submodules)
Modules
| Module | Doc |
|---|---|
MultiFileFsBackend class + Zod options schema |
src/backend/backend.md |
multiFileFsBackend() factory |
src/factory/factory.md |
| OTel instruments + state ring | src/observability/observability.md |
Quick example
import { multiFileFsBackend } from "@suaveplan/i18n-backend-fs-multifile";
const backend = multiFileFsBackend({ root: "./locales", layout: "nested" });
const record = await backend.read("en", "auth");
See the linked module docs for the advanced examples (watch mode, glob layout, YAML peer detection, AbortSignal cancellation).