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