58 lines
5.2 KiB
Markdown
58 lines
5.2 KiB
Markdown
# @suaveplan/i18n-backend-fs-multifile - Server-tier multi-file Node fs/promises translation backend for the @suaveplan/i18n family. Reads <root>/<locale>/<namespace>.<ext> (nested), <root>/<locale>.<namespace>.<ext> (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-http`](../i18n-backend-http) or
|
|
> [`@suaveplan/i18n-backend-storage`](../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.
|
|
|
|
<!-- 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)_
|
|
## Modules
|
|
|
|
| Module | Doc |
|
|
|---|---|
|
|
| `MultiFileFsBackend` class + Zod options schema | [`src/backend/backend.md`](./src/backend/backend.md) |
|
|
| `multiFileFsBackend()` factory | [`src/factory/factory.md`](./src/factory/factory.md) |
|
|
| OTel instruments + state ring | [`src/observability/observability.md`](./src/observability/observability.md) |
|
|
|
|
## Quick example
|
|
|
|
```ts
|
|
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).
|
|
|