SuavePlan/skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
admin
2026-05-29 08:20:56 +01:00
commit 949299f58d
6368 changed files with 527176 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

57
docs/localization/i18n/i18n-backend-fs-multifile/README.md Normal file
View File

@@ -0,0 +1,57 @@
# @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).