@stealthscale/vite-plugin-i18n 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stealth Scale B.V.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# @stealthscale/vite-plugin-i18n
+
+`@stealthscale/vite-plugin-i18n` finds every catalogue an application can reach, types their keys,
+and serves the module it loads them from. A package keeps its words beside its code and ships them.
+The application reaches every catalogue without listing one.
+
+## Install
+
+```bash
+pnpm add -D @stealthscale/vite-plugin-i18n
+```
+
+The package peers on `vite` and `@stealthscale/vite-plugin-base`. Most repositories reach it through
+`@stealthscale/vite-config-i18n` rather than adding it by hand.
+
+```ts
+import { i18n } from "@stealthscale/vite-plugin-i18n";
+
+export default defineConfig({ plugins: [i18n()] });
+```
+
+## Catalogue layout
+
+A package keeps its catalogues under `locales/<language>/<namespace>.json`, or the same in YAML.
+
+```
+locales/en/menu.json
+locales/en/menu/sections.json
+locales/nl/menu.json
+```
+
+The namespace is the first path segment under the language. Split one namespace across files by
+putting them in a directory: `menu/sections.json` contributes its keys under `sections`. A namespace
+is always fetched as one module, whatever it is split into.
+
+## The search
+
+The search starts at the application and follows every package it depends on, through runtime
+dependencies, peers, and its own development dependencies. Only packages under the application's
+scope are followed, because a walk that read every dependency of a rendering engine would open
+hundreds of manifests to find no catalogue in any of them. Pass `scopes` to follow others.
+
+Packages are read deepest first and the application last, so where two name the same language and
+namespace the application's words win. A package is resolved the way its import is, so a workspace
+link and an installed copy are found alike.
+
+## virtual:i18n
+
+```ts
+import { catalogues } from "virtual:i18n";
+```
+
+`catalogues` carries the languages and namespaces found, the fallback language's words inlined so
+the first paint has them, and a loader that fetches any other language's namespace as one module.
+Set `eager` to inline every language and fetch nothing.
+
+Add the types with a triple-slash directive from a file the project already compiles.
+
+```ts
+/// <reference types="@stealthscale/vite-plugin-i18n/client" />
+```
+
+## Generated types
+
+The plugin writes `src/i18n.gen.d.ts`, which adds every namespace to the foundation's `Resources`
+interface with each word as the string literal it is. A key that does not exist and a placeholder
+left out of a call are both errors in the editor. Set `types` to another path, or to `false` to
+write none.
+
+## The build gate
+
+A build fails on any of three faults:
+
+- A key the fallback does not define.
+- A placeholder a translation drops.
+- One owner declaring a key in two files.
+
+A dev server reports all three and keeps serving.
+
+A plural form is checked against any form of the same key, and may write the count out in words:
+`één pagina` is accepted against `{{count}} page`. Every other placeholder is still required.
+
+## Hot updates
+
+On a dev server a changed catalogue is sent to the page as an `i18n:catalogue` event carrying the
+pair merged afresh. The foundation replaces the words in place, so the page keeps its state. A
+catalogue appearing or disappearing regenerates the types as well.
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).

package/client.d.ts

@@ -0,0 +1,59 @@
+/**
+ * What the catalogue plugin emits, declared so that importing it type-checks.
+ *
+ * @remarks
+ *   An application reaches this with a triple-slash directive naming
+ *   `@stealthscale/vite-plugin-i18n/client`, from a file it already compiles. The module exists
+ *   only in a build the plugin takes part in.
+ */
+
+declare module "virtual:i18n" {
+  /**
+   * Describes what one catalogue holds: keys to words, nested as deep as the author likes.
+   */
+  export interface Words {
+    readonly [key: string]: string | Words;
+  }
+
+  /**
+   * Describes the catalogues an application loads its words from.
+   */
+  export interface Catalogues {
+    /**
+     * The words inlined, by language then namespace: the fallback language's, or every language's
+     * where the plugin was told to be eager.
+     */
+    readonly bundled: Readonly<Record<string, Readonly<Record<string, Words>>>>;
+
+    /**
+     * The fallback language's words, every namespace merged, inlined so the first paint has them.
+     */
+    readonly defaults: Readonly<Record<string, Words>>;
+
+    /**
+     * The language every key is defined in.
+     */
+    readonly fallback: string;
+
+    /**
+     * Every language a catalogue was found for.
+     */
+    readonly languages: readonly string[];
+
+    /**
+     * Loads one language's namespace, every file naming the pair merged, or nothing where none
+     * does.
+     */
+    readonly load: (language: string, namespace: string) => Promise<undefined | Words>;
+
+    /**
+     * Every namespace found.
+     */
+    readonly namespaces: readonly string[];
+  }
+
+  /**
+   * The catalogues found.
+   */
+  export const catalogues: Catalogues;
+}

package/dist/cyclonedx/bom.json

@@ -0,0 +1 @@
+{"$schema":"http://cyclonedx.org/schema/bom-1.7.schema.json","bomFormat":"CycloneDX","specVersion":"1.7","version":1,"metadata":{"lifecycles":[{"phase":"build"}],"tools":{"components":[{"type":"application","name":"rolldown","version":"1.2.7"},{"type":"application","name":"vite","version":"8.2.2"},{"type":"library","name":"core","group":"@arethetypeswrong","version":"0.18.5","bom-ref":"pkg:npm/%40arethetypeswrong/core@0.18.5","author":"Andrew Branch","description":"The API behind arethetypeswrong.github.io","hashes":[{"alg":"SHA-512","content":"f72b63cc6c318e6f54cfb23d6af7dbb79be542deae93db914444b3263aabce797a58abc8e9dc184e8faf277534d96aeafe64778aa97f3f386f1e129d2480230d"}],"licenses":[{"license":{"id":"MIT"}}],"purl":"pkg:npm/%40arethetypeswrong/core@0.18.5","externalReferences":[{"url":"https://github.com/arethetypeswrong/arethetypeswrong.github.io.git#packages/core","type":"vcs","comment":"as detected from PackageJson property \"repository.url\" and \"repository.directory\""}],"properties":[{"name":"cdx:npm:package:constraint:engine:node","value":">=20"}]},{"type":"library","name":"testing-config","group":"@stealthscale","version":"0.3.0","bom-ref":"pkg:npm/%40stealthscale/testing-config@0.3.0","description":"Lists every part of the house contract a config, plugin or library package breaks.","licenses":[{"license":{"id":"MIT"}}],"purl":"pkg:npm/%40stealthscale/testing-config@0.3.0","externalReferences":[{"url":"https://github.com/stealth-scale/config/issues","type":"issue-tracker","comment":"as detected from PackageJson property \"bugs\""},{"url":"git+https://github.com/stealth-scale/config.git#packages/testing-config","type":"vcs","comment":"as detected from PackageJson property \"repository.url\" and \"repository.directory\""},{"url":"https://github.com/stealth-scale/config/tree/main/packages/testing-config#readme","type":"website","comment":"as detected from PackageJson property \"homepage\""}],"properties":[{"name":"cdx:npm:package:constraint:engine:node","value":">=26.0.0"}]},{"type":"library","name":"testing","group":"@stealthscale","version":"0.3.0","bom-ref":"pkg:npm/%40stealthscale/testing@0.3.0","description":"Supplies the scratch workspaces, manifests, element measurements and plugin drivers a specification needs.","licenses":[{"license":{"id":"MIT"}}],"purl":"pkg:npm/%40stealthscale/testing@0.3.0","externalReferences":[{"url":"git+https://github.com/stealth-scale/config.git#packages/testing","type":"vcs","comment":"as detected from PackageJson property \"repository.url\" and \"repository.directory\""}],"properties":[{"name":"cdx:npm:package:constraint:engine:node","value":">=26.0.0"}]},{"type":"library","name":"vite-config-typescript","group":"@stealthscale","version":"0.3.0","bom-ref":"pkg:npm/%40stealthscale/vite-config-typescript@0.3.0","description":"Sets the TypeScript options every stealthscale package compiles with.","licenses":[{"license":{"id":"MIT"}}],"purl":"pkg:npm/%40stealthscale/vite-config-typescript@0.3.0","externalReferences":[{"url":"https://github.com/stealth-scale/config/issues","type":"issue-tracker","comment":"as detected from PackageJson property \"bugs\""},{"url":"git+https://github.com/stealth-scale/config.git#packages/vite-config-typescript","type":"vcs","comment":"as detected from PackageJson property \"repository.url\" and \"repository.directory\""},{"url":"https://github.com/stealth-scale/config/tree/main/packages/vite-config-typescript#readme","type":"website","comment":"as detected from PackageJson property \"homepage\""}],"properties":[{"name":"cdx:npm:package:constraint:engine:node","value":">=26.0.0"}]},{"type":"library","name":"vite-config","group":"@stealthscale","version":"0.6.0","bom-ref":"pkg:npm/%40stealthscale/vite-config@0.6.0","description":"Configures a package from five Vite+ tiers and a named layer for every block.","licenses":[{"license":{"id":"MIT"}}],"purl":"pkg:npm/%40stealthscale/vite-config@0.6.0","externalReferences":[{"url":"https://github.com/stealth-scale/config/issues","type":"issue-tracker","comment":"as detected from PackageJson property \"bugs\""},{"url":"git+https://github.com/stealth-scale/config.git#packages/vite-config","type":"vcs","comment":"as detected from PackageJson property \"repository.url\" and \"repository.directory\""},{"url":"https://github.com/stealth-scale/config/tree/main/packages/vite-config#readme","type":"website","comment":"as detected from PackageJson property \"homepage\""}],"properties":[{"name":"cdx:npm:package:constraint:engine:node","value":">=26.0.0"}]},{"type":"library","name":"vite-plugin-base","group":"@stealthscale","version":"0.2.0","bom-ref":"pkg:npm/%40stealthscale/vite-plugin-base@0.2.0","description":"Turns a name and one write step into a bundler plugin that reads the module graph.","licenses":[{"license":{"id":"MIT"}}],"purl":"pkg:npm/%40stealthscale/vite-plugin-base@0.2.0","externalReferences":[{"url":"https://github.com/stealth-scale/config/issues","type":"issue-tracker","comment":"as detected from PackageJson property \"bugs\""},{"url":"git+https://github.com/stealth-scale/config.git#packages/vite-plugin-base","type":"vcs","comment":"as detected from PackageJson property \"repository.url\" and \"repository.directory\""},{"url":"https://github.com/stealth-scale/config/tree/main/packages/vite-plugin-base#readme","type":"website","comment":"as detected from PackageJson property \"homepage\""}],"properties":[{"name":"cdx:npm:package:constraint:engine:node","value":">=26.0.0"}]},{"type":"library","name":"node","group":"@types","version":"26.5.1","bom-ref":"pkg:npm/%40types/node@26.5.1","description":"TypeScript definitions for node","hashes":[{"alg":"SHA-512","content":"0b3366d857b35b8551fcb8c6eb251d88480b13fac043d4a58f9802bbf0b656b75c5bb2346a1359f0345b1d3ef3399eabdce36077f6ec4087926a80c6addd42ea"}],"licenses":[{"license":{"id":"MIT"}}],"purl":"pkg:npm/%40types/node@26.5.1","externalReferences":[{"url":"https://github.com/DefinitelyTyped/DefinitelyTyped.git#types/node","type":"vcs","comment":"as detected from PackageJson property \"repository.url\" and \"repository.directory\""},{"url":"https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/node","type":"website","comment":"as detected from PackageJson property \"homepage\""}]},{"type":"library","name":"coverage-v8","group":"@vitest","version":"4.1.11","bom-ref":"pkg:npm/%40vitest/coverage-v8@4.1.11","author":"Anthony Fu <anthonyfu117@hotmail.com>","description":"V8 coverage provider for Vitest","hashes":[{"alg":"SHA-512","content":"f0c5461059c921c7468dc6df2a67aaf33d296471f426556da15647f50feac14a7ac3216710950132bc3d0c26a3fab6b7bd28469a16af8da94c2213cdc5901473"}],"licenses":[{"license":{"id":"MIT"}}],"purl":"pkg:npm/%40vitest/coverage-v8@4.1.11","externalReferences":[{"url":"https://github.com/vitest-dev/vitest/issues","type":"issue-tracker","comment":"as detected from PackageJson property \"bugs.url\""},{"url":"git+https://github.com/vitest-dev/vitest.git#packages/coverage-v8","type":"vcs","comment":"as detected from PackageJson property \"repository.url\" and \"repository.directory\""},{"url":"https://vitest.dev/guide/coverage","type":"website","comment":"as detected from PackageJson property \"homepage\""}]},{"type":"library","name":"vite-plus-core","group":"@voidzero-dev","version":"0.3.1","bom-ref":"pkg:npm/%40voidzero-dev/vite-plus-core@0.3.1","author":"VoidZero Inc.","description":"The Unified Toolchain for the Web","licenses":[{"license":{"id":"MIT"}}],"purl":"pkg:npm/%40voidzero-dev/vite-plus-core@0.3.1","externalReferences":[{"url":"https://github.com/voidzero-dev/vite-plus/issues","type":"issue-tracker","comment":"as detected from PackageJson property \"bugs.url\""},{"url":"git+https://github.com/voidzero-dev/vite-plus.git#packages/core","type":"vcs","comment":"as detected from PackageJson property \"repository.url\" and \"repository.directory\""},{"url":"https://viteplus.dev/guide","type":"website","comment":"as detected from PackageJson property \"homepage\""}],"properties":[{"name":"cdx:npm:package:constraint:engine:node","value":"^20.19.0 || ^22.18.0 || >=24.11.0"}]},{"type":"library","name":"typescript","version":"7.0.2","bom-ref":"pkg:npm/typescript@7.0.2","author":"Microsoft Corp.","description":"TypeScript is a language for application scale JavaScript development","hashes":[{"alg":"SHA-512","content":"f0561abbdea8dcd28e85b8ca8bfa8dbc6fd6e63873c646dd9b9b23f406d9ff94f9b16aa7de12602df1b1dbbb11299593bf2cc23fc74b4414dfe6d05349155434"}],"licenses":[{"license":{"id":"Apache-2.0"}}],"purl":"pkg:npm/typescript@7.0.2","externalReferences":[{"url":"https://github.com/microsoft/TypeScript/issues","type":"issue-tracker","comment":"as detected from PackageJson property \"bugs.url\""},{"url":"https://github.com/microsoft/TypeScript.git","type":"vcs","comment":"as detected from PackageJson property \"repository.url\""},{"url":"https://www.typescriptlang.org/","type":"website","comment":"as detected from PackageJson property \"homepage\""}],"properties":[{"name":"cdx:npm:package:constraint:engine:node","value":">=16.20.0"}]},{"type":"library","name":"vitest","version":"4.1.11","bom-ref":"pkg:npm/vitest@4.1.11","author":"Anthony Fu <anthonyfu117@hotmail.com>","description":"Next generation testing framework powered by Vite","hashes":[{"alg":"SHA-512","content":"7e1002acd5d489d21b19206be4595bb8190eed5582d59c8b9740cee025360eb42800fc57f3862cc6cf877864298a2e656565754388016534eee3d985f80e8477"}],"licenses":[{"license":{"id":"MIT"}}],"purl":"pkg:npm/vitest@4.1.11","externalReferences":[{"url":"https://github.com/vitest-dev/vitest/issues","type":"issue-tracker","comment":"as detected from PackageJson property \"bugs.url\""},{"url":"git+https://github.com/vitest-dev/vitest.git#packages/vitest","type":"vcs","comment":"as detected from PackageJson property \"repository.url\" and \"repository.directory\""},{"url":"https://vitest.dev","type":"website","comment":"as detected from PackageJson property \"homepage\""}],"properties":[{"name":"cdx:npm:package:constraint:engine:node","value":"^20.0.0 || ^22.0.0 || >=24.0.0"}]}]},"component":{"type":"library","name":"vite-plugin-i18n","group":"@stealthscale","version":"0.0.0","bom-ref":"pkg:npm/%40stealthscale/vite-plugin-i18n@0.0.0","description":"Finds every catalogue an application can reach, types their keys, and answers the module it loads them from.","licenses":[{"license":{"id":"MIT"}}],"purl":"pkg:npm/%40stealthscale/vite-plugin-i18n@0.0.0","externalReferences":[{"url":"https://github.com/stealth-scale/config/issues","type":"issue-tracker","comment":"as detected from PackageJson property \"bugs\""},{"url":"git+https://github.com/stealth-scale/config.git#packages/vite-plugin-i18n","type":"vcs","comment":"as detected from PackageJson property \"repository.url\" and \"repository.directory\""},{"url":"https://github.com/stealth-scale/config/tree/main/packages/vite-plugin-i18n#readme","type":"website","comment":"as detected from PackageJson property \"homepage\""}],"properties":[{"name":"cdx:npm:package:constraint:engine:node","value":">=26.0.0"}],"evidence":{"licenses":[{"license":{"name":"file: LICENSE","text":{"content":"TUlUIExpY2Vuc2UKCkNvcHlyaWdodCAoYykgMjAyNiBTdGVhbHRoIFNjYWxlIEIuVi4KClBlcm1pc3Npb24gaXMgaGVyZWJ5IGdyYW50ZWQsIGZyZWUgb2YgY2hhcmdlLCB0byBhbnkgcGVyc29uIG9idGFpbmluZyBhIGNvcHkKb2YgdGhpcyBzb2Z0d2FyZSBhbmQgYXNzb2NpYXRlZCBkb2N1bWVudGF0aW9uIGZpbGVzICh0aGUgIlNvZnR3YXJlIiksIHRvIGRlYWwKaW4gdGhlIFNvZnR3YXJlIHdpdGhvdXQgcmVzdHJpY3Rpb24sIGluY2x1ZGluZyB3aXRob3V0IGxpbWl0YXRpb24gdGhlIHJpZ2h0cwp0byB1c2UsIGNvcHksIG1vZGlmeSwgbWVyZ2UsIHB1Ymxpc2gsIGRpc3RyaWJ1dGUsIHN1YmxpY2Vuc2UsIGFuZC9vciBzZWxsCmNvcGllcyBvZiB0aGUgU29mdHdhcmUsIGFuZCB0byBwZXJtaXQgcGVyc29ucyB0byB3aG9tIHRoZSBTb2Z0d2FyZSBpcwpmdXJuaXNoZWQgdG8gZG8gc28sIHN1YmplY3QgdG8gdGhlIGZvbGxvd2luZyBjb25kaXRpb25zOgoKVGhlIGFib3ZlIGNvcHlyaWdodCBub3RpY2UgYW5kIHRoaXMgcGVybWlzc2lvbiBub3RpY2Ugc2hhbGwgYmUgaW5jbHVkZWQgaW4gYWxsCmNvcGllcyBvciBzdWJzdGFudGlhbCBwb3J0aW9ucyBvZiB0aGUgU29mdHdhcmUuCgpUSEUgU09GVFdBUkUgSVMgUFJPVklERUQgIkFTIElTIiwgV0lUSE9VVCBXQVJSQU5UWSBPRiBBTlkgS0lORCwgRVhQUkVTUyBPUgpJTVBMSUVELCBJTkNMVURJTkcgQlVUIE5PVCBMSU1JVEVEIFRPIFRIRSBXQVJSQU5USUVTIE9GIE1FUkNIQU5UQUJJTElUWSwKRklUTkVTUyBGT1IgQSBQQVJUSUNVTEFSIFBVUlBPU0UgQU5EIE5PTklORlJJTkdFTUVOVC4gSU4gTk8gRVZFTlQgU0hBTEwgVEhFCkFVVEhPUlMgT1IgQ09QWVJJR0hUIEhPTERFUlMgQkUgTElBQkxFIEZPUiBBTlkgQ0xBSU0sIERBTUFHRVMgT1IgT1RIRVIKTElBQklMSVRZLCBXSEVUSEVSIElOIEFOIEFDVElPTiBPRiBDT05UUkFDVCwgVE9SVCBPUiBPVEhFUldJU0UsIEFSSVNJTkcgRlJPTSwKT1VUIE9GIE9SIElOIENPTk5FQ1RJT04gV0lUSCBUSEUgU09GVFdBUkUgT1IgVEhFIFVTRSBPUiBPVEhFUiBERUFMSU5HUyBJTiBUSEUKU09GVFdBUkUuCg==","contentType":"text/plain","encoding":"base64"}}}]}},"supplier":{"name":"Stealth Scale B.V.","url":["https://stealthscale.io"]}},"components":[],"dependencies":[{"ref":"pkg:npm/%40stealthscale/vite-plugin-i18n@0.0.0"}]}

package/dist/index.d.mts

@@ -0,0 +1,222 @@
+import { Plugin } from "vite";
+//#region src/find.d.ts
+/**
+ * Locates every `locales/<language>/<namespace>.json` an application and its dependencies ship.
+ *
+ * @remarks
+ *   A namespace is the first path segment under the language. `menu.json` and
+ *   `menu/sections/billing.json` both belong to the namespace `menu`, and the second contributes
+ *   its keys under `sections.billing`. A namespace is fetched as one module whatever it is split
+ *   into.
+ */
+/**
+ * One catalogue file, with the language, namespace and package it belongs to.
+ */
+interface Catalogue {
+  /**
+   * The absolute path of the file, with forward slashes.
+   */
+  readonly file: string;
+  /**
+   * The BCP 47 tag the directory is named after, such as `en` or `nl-BE`.
+   */
+  readonly language: string;
+  /**
+   * The first path segment under the language, without its extension. `menu.json` and
+   * `menu/sections.json` both give `menu`.
+   */
+  readonly namespace: string;
+  /**
+   * True when the application owns the file, false when a dependency ships it.
+   */
+  readonly own: boolean;
+  /**
+   * The name of the package the file came from.
+   */
+  readonly owner: string;
+  /**
+   * The path below the namespace, joined with dots. `menu/sections/billing.json` gives
+   * `sections.billing`, and a file that is the namespace itself gives an empty string.
+   */
+  readonly prefix: string;
+}
+/**
+ * The directory a package keeps its catalogues in.
+ */
+export declare const LOCALES = "locales";
+/**
+ * Returns every catalogue an application can reach, its dependencies' first and its own last.
+ *
+ * @remarks
+ *   When two packages declare the same language and namespace, the one later in the result wins the
+ *   merge, which puts the application last. Each package is resolved the way an import of it
+ *   resolves, so a workspace link and an installed copy are found alike.
+ * @param root - The application directory.
+ * @param scopes - The scopes to follow. Defaults to the application's own scope.
+ * @returns The catalogues in merge order.
+ */
+export declare function found(root: string, scopes?: readonly string[]): readonly Catalogue[];
+//#endregion
+//#region src/emit.d.ts
+/**
+ * The specifier an application imports to reach its catalogues.
+ */
+export declare const ID = "virtual:i18n";
+/**
+ * Builds the specifier one language's namespace is fetched under.
+ *
+ * @remarks
+ *   Neither a language tag nor a namespace contains a slash, so `pairOfId` splits the result back
+ *   without ambiguity.
+ * @param language - The BCP 47 tag.
+ * @param namespace - The namespace name.
+ * @returns A specifier such as `virtual:i18n/nl/menu`.
+ */
+export declare function pairId(language: string, namespace: string): string;
+/**
+ * One language and one namespace, which together address a single module.
+ */
+type Pair = Pick<Catalogue, "language" | "namespace">;
+/**
+ * Splits a pair module's specifier back into its language and namespace.
+ *
+ * @param id - A specifier, with or without the resolution prefix.
+ * @returns The pair, or undefined when the specifier addresses something else.
+ */
+export declare function pairOfId(id: string): Pair | undefined;
+/**
+ * The contents of one catalogue: keys mapped to strings, nested to any depth.
+ */
+interface Words {
+  readonly [key: string]: string | Words;
+}
+/**
+ * Catalogue files indexed by language, then by namespace, each list in merge order.
+ */
+type CatalogueIndex = ReadonlyMap<string, ReadonlyMap<string, readonly Catalogue[]>>;
+/**
+ * Indexes catalogues by language and namespace, preserving the order they were found in.
+ *
+ * @param catalogues - Every catalogue found.
+ */
+export declare function indexed(catalogues: readonly Catalogue[]): CatalogueIndex;
+/**
+ * Generates the module an application imports its catalogues from.
+ *
+ * @remarks
+ *   The fallback language is inlined so the first paint needs no request. Every other language is
+ *   reached through the loader. Under `eager` every language is inlined instead and the loader
+ *   fetches nothing, which costs one larger bundle and saves a request per language.
+ * @param index - The indexed catalogues.
+ * @param fallback - The language that defines every key.
+ * @param eager - Inlines every language when true.
+ * @returns The module as JavaScript source.
+ */
+export declare function cataloguesModule(index: CatalogueIndex, fallback: string, eager?: boolean): string;
+//#endregion
+//#region src/check.d.ts
+/**
+ * One fault found in a catalogue.
+ */
+interface Problem {
+  /**
+   * The absolute path of the file holding the fault.
+   */
+  readonly file: string;
+  /**
+   * The dotted key, or an empty string when the fault is about the whole file.
+   */
+  readonly key: string;
+  /**
+   * The fault, phrased as a clause that follows the key.
+   */
+  readonly says: string;
+}
+/**
+ * Validates every catalogue: the fallback's files against each other, then each translation against
+ * the fallback.
+ *
+ * @param index - The indexed catalogues.
+ * @param fallback - The language that defines every key.
+ * @returns Every fault, the fallback's first, then in file order.
+ */
+export declare function problems(index: CatalogueIndex, fallback: string): readonly Problem[];
+//#endregion
+//#region src/plugin.d.ts
+/**
+ * The custom event name a changed catalogue is sent to the page under.
+ *
+ * @remarks
+ *   The foundation listens for the same string. Neither package imports the other, so the name is a
+ *   contract between them rather than a shared constant.
+ */
+export declare const EVENT = "i18n:catalogue";
+/**
+ * The payload the change event carries.
+ */
+interface Changed {
+  /**
+   * The BCP 47 tag of the language that changed.
+   */
+  readonly language: string;
+  /**
+   * The namespace.
+   */
+  readonly namespace: string;
+  /**
+   * Every file of the pair merged, so an override survives a change to the package it overrides.
+   */
+  readonly words: Readonly<Record<string, unknown>>;
+}
+/**
+ * Configures the catalogues.
+ */
+interface Options {
+  /**
+   * Inlines every language rather than the fallback alone, so nothing is fetched. Off by default.
+   */
+  readonly eager?: boolean | undefined;
+  /**
+   * The language every key is defined in, which is inlined for the first paint. `en` by default.
+   */
+  readonly fallback?: string | undefined;
+  /**
+   * Decides which namespaces to keep, given each name. Keeps every one by default.
+   */
+  readonly namespaces?: ((namespace: string) => boolean) | undefined;
+  /**
+   * The scopes whose packages are searched. The application's own scope by default.
+   */
+  readonly scopes?: readonly string[] | undefined;
+  /**
+   * Where to write the types, against the project root, or false to write none.
+   * `src/i18n.gen.d.ts` by default, which the house treats as generated and excludes from coverage.
+   */
+  readonly types?: false | string | undefined;
+}
+/**
+ * Builds the plugin that finds the catalogues, types their keys, and serves `virtual:i18n`.
+ *
+ * @remarks
+ *   On a dev server a catalogue change is pushed to the page as an event rather than a reload, so
+ *   the page keeps its state. In a build an invalid catalogue throws instead.
+ * @param options - Where to search and what to write. `Options` documents every member.
+ * @returns The plugin.
+ */
+export declare function i18n(options?: Options): Plugin;
+//#endregion
+//#region src/typegen.d.ts
+/**
+ * The package whose `Resources` interface the types are added to.
+ */
+export declare const FOUNDATION = "@stealthscale/provider-i18n";
+/**
+ * Renders the augmentation that adds every namespace to the foundation's `Resources`.
+ *
+ * @param index - The indexed catalogues.
+ * @param fallback - The language whose strings type the keys.
+ * @returns The declaration file as TypeScript source.
+ */
+export declare function declared(index: CatalogueIndex, fallback: string): string;
+//#endregion
+export type { Catalogue, CatalogueIndex, Changed, Options, Pair, Problem, Words };

package/dist/index.mjs

@@ -0,0 +1,788 @@
+import { existsSync, globSync, readFileSync } from "node:fs";
+import { parse } from "yaml";
+import { basename, dirname, join, resolve } from "node:path";
+import { normalizePath } from "vite";
+import { manifestAt, packageAt, text, writeIfChanged } from "@stealthscale/vite-plugin-base";
+//#region src/find.ts
+/**
+* Locates every `locales/<language>/<namespace>.json` an application and its dependencies ship.
+*
+* @remarks
+*   A namespace is the first path segment under the language. `menu.json` and
+*   `menu/sections/billing.json` both belong to the namespace `menu`, and the second contributes
+*   its keys under `sections.billing`. A namespace is fetched as one module whatever it is split
+*   into.
+*/
+/**
+* The directory a package keeps its catalogues in.
+*/
+const LOCALES = "locales";
+/**
+* Matches the extensions a catalogue may use: `.json`, `.yaml` and `.yml`.
+*/
+const EXTENSION = /\.(?:json|ya?ml)$/u;
+/**
+* Returns the namespace a file belongs to.
+*
+* @remarks
+*   The first path segment, with the extension stripped when the file is the namespace itself.
+* @param relative - The file's path under the language directory.
+*/
+function namespaceOf(relative) {
+	const at = relative.indexOf("/");
+	return at === -1 ? relative.replace(EXTENSION, "") : relative.slice(0, at);
+}
+/**
+* Returns the prefix a file's keys are nested under.
+*
+* @remarks
+*   The path below the namespace with the extension stripped and each separator replaced by a dot.
+* @param relative - The file's path under the language directory.
+* @returns The prefix, or an empty string when the file is the namespace itself.
+*/
+function prefixOf(relative) {
+	const at = relative.indexOf("/");
+	return at === -1 ? "" : relative.slice(at + 1).replace(EXTENSION, "").replaceAll("/", ".");
+}
+/**
+* Lists every catalogue file under one directory's `locales`, at any depth.
+*
+* @param directory - The package or application directory to search.
+* @param owner - The package name to record on each result.
+* @param own - True when the directory is the application's own.
+* @returns The catalogues sorted by path, so the result is stable between runs.
+*/
+function cataloguesIn(directory, owner, own) {
+	const root = join(directory, LOCALES);
+	if (!existsSync(root)) return [];
+	return globSync("*/**/*.{json,yaml,yml}", { cwd: root }).map((relative) => normalizePath(relative)).toSorted().map((relative) => {
+		const at = relative.indexOf("/");
+		const rest = relative.slice(at + 1);
+		return {
+			file: normalizePath(join(root, relative)),
+			language: relative.slice(0, at),
+			namespace: namespaceOf(rest),
+			own,
+			owner,
+			prefix: prefixOf(rest)
+		};
+	});
+}
+/**
+* Returns the scope a package name carries.
+*
+* @param name - The package name, or undefined when the manifest declares none.
+* @returns The scope such as `@stealthscale`, or undefined for an unscoped name.
+*/
+function scopeOf(name) {
+	return name?.startsWith("@") === true ? name.slice(0, name.indexOf("/")) : void 0;
+}
+/**
+* Lists the package names the walk follows out of one manifest.
+*
+* @remarks
+*   `dependencies` and `peerDependencies` both count, because a component package declares its
+*   siblings as peers. The application's `devDependencies` count too, because an example declares
+*   the packages it demonstrates there.
+* @param manifest - The parsed package.json.
+* @param own - True for the application's own manifest.
+*/
+function namesIn(manifest, own) {
+	return [
+		"dependencies",
+		"peerDependencies",
+		...own ? ["devDependencies"] : []
+	].flatMap((field) => {
+		const declared = manifest[field];
+		return typeof declared === "object" && declared !== null ? Object.keys(declared) : [];
+	});
+}
+/**
+* Visits a directory's dependencies depth first, so a package precedes whatever depends on it.
+*
+* @remarks
+*   Only packages under one of the scopes are followed. Following every dependency of a rendering
+*   engine would read hundreds of manifests and find no catalogue in any of them.
+* @param directory - The directory to start from.
+* @param walk - The scopes to follow and the directories already visited.
+* @param own - True for the application's own directory.
+* @returns Each package with its manifest, the starting directory last.
+*/
+function walked(directory, walk, own) {
+	if (walk.seen.has(directory)) return [];
+	walk.seen.add(directory);
+	const manifest = manifestAt(directory);
+	if (manifest === void 0) return [];
+	return [...namesIn(manifest, own).filter((name) => walk.scopes.has(scopeOf(name) ?? "")).map((name) => packageAt(name, directory)).filter((at) => at !== void 0).flatMap((at) => walked(at, walk, false)), {
+		at: directory,
+		manifest
+	}];
+}
+/**
+* Returns every catalogue an application can reach, its dependencies' first and its own last.
+*
+* @remarks
+*   When two packages declare the same language and namespace, the one later in the result wins the
+*   merge, which puts the application last. Each package is resolved the way an import of it
+*   resolves, so a workspace link and an installed copy are found alike.
+* @param root - The application directory.
+* @param scopes - The scopes to follow. Defaults to the application's own scope.
+* @returns The catalogues in merge order.
+*/
+function found(root, scopes) {
+	const own = manifestAt(root);
+	const named = own === void 0 ? void 0 : text(own, "name");
+	return walked(root, {
+		scopes: new Set(scopes ?? [scopeOf(named)].filter((scope) => scope !== void 0)),
+		seen: /* @__PURE__ */ new Set()
+	}, true).flatMap((one) => cataloguesIn(one.at, text(one.manifest, "name") ?? basename(one.at), one.at === root));
+}
+//#endregion
+//#region src/emit.ts
+/**
+* Generates the module an application imports its catalogues from, and one module per pair.
+*/
+/**
+* The specifier an application imports to reach its catalogues.
+*/
+const ID = "virtual:i18n";
+/**
+* Builds the specifier one language's namespace is fetched under.
+*
+* @remarks
+*   Neither a language tag nor a namespace contains a slash, so `pairOfId` splits the result back
+*   without ambiguity.
+* @param language - The BCP 47 tag.
+* @param namespace - The namespace name.
+* @returns A specifier such as `virtual:i18n/nl/menu`.
+*/
+function pairId(language, namespace) {
+	return `${ID}/${language}/${namespace}`;
+}
+/**
+* Splits a pair module's specifier back into its language and namespace.
+*
+* @param id - A specifier, with or without the resolution prefix.
+* @returns The pair, or undefined when the specifier addresses something else.
+*/
+function pairOfId(id) {
+	const [head, language, namespace, ...rest] = id.replace(/^\0/u, "").split("/");
+	return head === "virtual:i18n" && language !== void 0 && namespace !== void 0 && rest.length === 0 ? {
+		language,
+		namespace
+	} : void 0;
+}
+/**
+* Indexes catalogues by language and namespace, preserving the order they were found in.
+*
+* @param catalogues - Every catalogue found.
+*/
+function indexed(catalogues) {
+	const byLanguage = /* @__PURE__ */ new Map();
+	for (const catalogue of catalogues) {
+		const byNamespace = byLanguage.get(catalogue.language) ?? /* @__PURE__ */ new Map();
+		const files = byNamespace.get(catalogue.namespace) ?? [];
+		files.push(catalogue);
+		byNamespace.set(catalogue.namespace, files);
+		byLanguage.set(catalogue.language, byNamespace);
+	}
+	return byLanguage;
+}
+/**
+* Returns one language's catalogues indexed by namespace.
+*
+* @param index - The indexed catalogues.
+* @param language - The BCP 47 tag.
+* @returns The files per namespace, or an empty map when the language has no catalogue.
+*/
+function ofLanguage(index, language) {
+	return index.get(language) ?? /* @__PURE__ */ new Map();
+}
+/**
+* Returns every file that belongs to one pair.
+*
+* @param index - The indexed catalogues.
+* @param language - The BCP 47 tag.
+* @param namespace - The namespace name.
+* @returns The files in merge order, or an empty array when no file belongs to the pair.
+*/
+function filesOf(index, language, namespace) {
+	return ofLanguage(index, language).get(namespace) ?? [];
+}
+/**
+* Returns true when a parsed value is an object whose every leaf is a string.
+*
+* @param value - The parsed file contents.
+*/
+function isWords(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) && Object.values(value).every((leaf) => typeof leaf === "string" || isWords(leaf));
+}
+/**
+* Parses one catalogue file, as JSON or as YAML according to its extension.
+*
+* @param catalogue - The file to read.
+* @returns Its contents, nested as written.
+* @throws {@link Error} When the file does not parse to an object of strings.
+*/
+function wordsOf(catalogue) {
+	const text = readFileSync(catalogue.file, "utf8");
+	const parsed = catalogue.file.endsWith(".json") ? JSON.parse(text) : parse(text);
+	if (!isWords(parsed)) throw new Error(`${catalogue.file} does not parse to an object of strings.`);
+	return parsed;
+}
+/**
+* Parses one catalogue file and nests its contents under the file's prefix.
+*
+* @remarks
+*   A `title` key in `menu/sections/billing.json` comes back as `sections.billing.title`.
+* @param catalogue - The file to read.
+*/
+function nested(catalogue) {
+	return catalogue.prefix.split(".").filter((segment) => segment !== "").reduceRight((inner, segment) => ({ [segment]: inner }), wordsOf(catalogue));
+}
+/**
+* Merges two sets of contents key by key, so the later one overwrites only the keys it declares.
+*
+* @param under - The contents merged so far.
+* @param over - The contents to apply on top.
+*/
+function merged(under, over) {
+	const result = { ...under };
+	for (const [key, value] of Object.entries(over)) {
+		const existing = result[key];
+		result[key] = typeof value === "object" && typeof existing === "object" ? merged(existing, value) : value;
+	}
+	return result;
+}
+/**
+* Parses and merges every file of one pair, each nested under its own prefix.
+*
+* @param files - The files in merge order, the last one winning each key.
+*/
+function mergedWords(files) {
+	return files.reduce((words, file) => merged(words, nested(file)), {});
+}
+/**
+* Generates the module one pair is fetched as, holding every file of the pair merged.
+*
+* @param files - The files in merge order.
+*/
+function pairModule(files) {
+	return `export default ${JSON.stringify(mergedWords(files))};\n`;
+}
+/**
+* Generates the loader table: one dynamic import per pair, so a namespace costs one request.
+*
+* @param index - The indexed catalogues.
+* @returns The table as JavaScript source.
+*/
+function loaders(index) {
+	return `{\n${[...index.entries()].map(([language, byNamespace]) => {
+		const imports = [...byNamespace.keys()].map((namespace) => `    ${JSON.stringify(namespace)}: () => import(${JSON.stringify(pairId(language, namespace))})`);
+		return `  ${JSON.stringify(language)}: {\n${imports.join(",\n")},\n  }`;
+	}).join(",\n")},\n}`;
+}
+/**
+* Merges each namespace of one language, for inlining into the module.
+*
+* @param index - The indexed catalogues.
+* @param language - The BCP 47 tag.
+*/
+function inlined(index, language) {
+	return Object.fromEntries([...ofLanguage(index, language).entries()].map(([namespace, files]) => [namespace, mergedWords(files)]));
+}
+/**
+* Lists every namespace any language declares, sorted.
+*
+* @param index - The indexed catalogues.
+*/
+function namespacesIn(index) {
+	const names = /* @__PURE__ */ new Set();
+	for (const byNamespace of index.values()) for (const namespace of byNamespace.keys()) names.add(namespace);
+	return [...names].toSorted();
+}
+/**
+* Generates the module an application imports its catalogues from.
+*
+* @remarks
+*   The fallback language is inlined so the first paint needs no request. Every other language is
+*   reached through the loader. Under `eager` every language is inlined instead and the loader
+*   fetches nothing, which costs one larger bundle and saves a request per language.
+* @param index - The indexed catalogues.
+* @param fallback - The language that defines every key.
+* @param eager - Inlines every language when true.
+* @returns The module as JavaScript source.
+*/
+function cataloguesModule(index, fallback, eager = false) {
+	const languages = [...index.keys()].toSorted();
+	const bundled = Object.fromEntries((eager ? languages : [fallback]).map((language) => [language, inlined(index, language)]));
+	return [
+		`export const fallback = ${JSON.stringify(fallback)};`,
+		`export const languages = ${JSON.stringify(languages)};`,
+		`export const namespaces = ${JSON.stringify(namespacesIn(index))};`,
+		`export const bundled = ${JSON.stringify(bundled)};`,
+		`export const defaults = bundled[fallback] ?? {};`,
+		`const loaders = ${eager ? "{}" : loaders(index)};`,
+		"",
+		"export async function load(language, namespace) {",
+		"  const loader = loaders[language]?.[namespace];",
+		"  if (loader === undefined) return undefined;",
+		"  return (await loader()).default;",
+		"}",
+		"",
+		"export const catalogues = { bundled, defaults, fallback, languages, load, namespaces };",
+		""
+	].join("\n");
+}
+//#endregion
+//#region src/check.ts
+/**
+* Validates every catalogue against the fallback language.
+*
+* @remarks
+*   An undefined key, a dropped placeholder and a key one package declares twice are all invisible
+*   to a translator, so the build reports them instead.
+*/
+/**
+* Matches an i18next placeholder, `{{name}}` or `{{name, format}}`.
+*/
+const PLACEHOLDER = /\{\{\s*([^,}\s]+)/gu;
+/**
+* Matches a plural suffix, which is one of the six categories CLDR defines.
+*/
+const PLURAL = /_(?:zero|one|two|few|many|other)$/u;
+/**
+* Flattens nested contents to the dotted keys i18next addresses them by.
+*
+* @param words - The contents, nested as the file stores them.
+* @param prefix - The path down to these contents, empty at the top level.
+*/
+function flattened(words, prefix = "") {
+	const flat = /* @__PURE__ */ new Map();
+	for (const [key, value] of Object.entries(words)) {
+		const at = prefix === "" ? key : `${prefix}.${key}`;
+		if (typeof value === "string") flat.set(at, value);
+		else for (const [inner, word] of flattened(value, at)) flat.set(inner, word);
+	}
+	return flat;
+}
+/**
+* Lists the placeholder names one string carries.
+*
+* @param word - One translated string.
+* @returns Each name once, sorted.
+*/
+function placeholdersOf(word) {
+	return [...new Set([...word.matchAll(PLACEHOLDER)].flatMap((match) => match.slice(1, 2)))].toSorted();
+}
+/**
+* Strips a plural or context suffix, so `pages_one` can be checked against any `pages_*`.
+*
+* @param key - A dotted key, with or without a suffix.
+*/
+function stem(key) {
+	const at = key.lastIndexOf("_");
+	return at === -1 ? key : key.slice(0, at);
+}
+/**
+* Lists the placeholders a translation has to carry.
+*
+* @remarks
+*   Every placeholder the fallback carries, except `count` in a plural form. Some languages spell
+*   the number out for one of their forms, so `één pagina` is valid against `{{count}} page`.
+* @param key - The translated key.
+* @param against - The fallback string for that key.
+*/
+function wanted(key, against) {
+	const names = placeholdersOf(against);
+	return PLURAL.test(key) ? names.filter((name) => name !== "count") : names;
+}
+/**
+* Reports a placeholder a restated key drops.
+*
+* @param file - The file restating the key.
+* @param key - The key being restated.
+* @param word - The string this file gives it.
+* @param against - The string the fallback gives it.
+* @returns One problem, or an empty array when every placeholder survives.
+*/
+function placeholdersChecked(file, key, word, against) {
+	const carried = placeholdersOf(word);
+	const missing = wanted(key, against).filter((name) => !carried.includes(name));
+	return missing.length === 0 ? [] : [{
+		file: file.file,
+		key,
+		says: `leaves out the placeholder ${missing.map((name) => `{{${name}}}`).join(", ")}`
+	}];
+}
+/**
+* Validates one translation against the fallback's definition of its namespace.
+*
+* @param file - The translation to check.
+* @param defined - The fallback's contents for that namespace, flattened.
+*/
+function checked(file, defined) {
+	const stems = new Set([...defined.keys()].map((key) => stem(key)));
+	const found = [];
+	for (const [key, word] of flattened(nested(file))) {
+		const against = defined.get(key) ?? defined.get(`${stem(key)}_other`);
+		if (against === void 0) {
+			if (!stems.has(stem(key))) found.push({
+				file: file.file,
+				key,
+				says: "names a key the fallback does not define"
+			});
+			continue;
+		}
+		found.push(...placeholdersChecked(file, key, word, against));
+	}
+	return found;
+}
+/**
+* Builds the fallback's definition of one namespace, collecting faults as it merges.
+*
+* @remarks
+*   A package defines whatever keys it ships. Another package may override one, and the override is
+*   checked for placeholders. The application may override too, but may not add a key to a
+*   namespace a package owns, because a key nobody else defines is a typo. One owner declaring a
+*   key in two files is a fault wherever it happens, because the merge would silently pick one.
+* @param files - The fallback files of the namespace, in merge order.
+* @param found - The array faults are pushed onto.
+* @returns The namespace's contents, flattened.
+*/
+function definition(files, found) {
+	const defined = /* @__PURE__ */ new Map();
+	const packaged = files.some((file) => !file.own);
+	for (const file of files) for (const [key, word] of flattened(nested(file))) {
+		const earlier = defined.get(key);
+		if (earlier === void 0) {
+			if (file.own && packaged && ![...defined.keys()].some((by) => stem(by) === stem(key))) {
+				found.push({
+					file: file.file,
+					key,
+					says: "names a key the fallback does not define"
+				});
+				continue;
+			}
+		} else if (earlier.file.owner === file.owner) found.push({
+			file: file.file,
+			key,
+			says: `is also declared in ${earlier.file.file}`
+		});
+		else found.push(...placeholdersChecked(file, key, word, earlier.word));
+		defined.set(key, {
+			file,
+			word
+		});
+	}
+	return new Map([...defined].map(([key, { word }]) => [key, word]));
+}
+/**
+* Validates every catalogue: the fallback's files against each other, then each translation against
+* the fallback.
+*
+* @param index - The indexed catalogues.
+* @param fallback - The language that defines every key.
+* @returns Every fault, the fallback's first, then in file order.
+*/
+function problems(index, fallback) {
+	const defining = index.get(fallback);
+	if (defining === void 0) return [];
+	const found = [];
+	const definitions = new Map([...defining].map(([namespace, files]) => [namespace, definition(files, found)]));
+	for (const [language, byNamespace] of index) {
+		if (language === fallback) continue;
+		for (const [namespace, files] of byNamespace) {
+			const words = definitions.get(namespace);
+			if (words === void 0) {
+				found.push(...files.map((file) => ({
+					file: file.file,
+					key: "",
+					says: `names a namespace the ${fallback} catalogues do not define`
+				})));
+				continue;
+			}
+			for (const file of files) found.push(...checked(file, words));
+		}
+	}
+	return found;
+}
+//#endregion
+//#region src/typegen.ts
+/**
+* Generates the declaration file that types every namespace's keys.
+*
+* @remarks
+*   Each string becomes a string literal type, so an unknown key and a dropped placeholder are both
+*   editor errors.
+*/
+/**
+* The package whose `Resources` interface the types are added to.
+*/
+const FOUNDATION = "@stealthscale/provider-i18n";
+/**
+* The header the generated file opens with, telling a reader not to edit it.
+*/
+const HEADER = [
+	"// Generated by @stealthscale/vite-plugin-i18n from the catalogues found. Do not edit: change",
+	"// the words in locales/<language>/<namespace>.json and this file follows.",
+	"",
+	"export {};",
+	""
+].join("\n");
+/**
+* Renders one namespace's contents as an object type, nested as the contents are.
+*
+* @param words - The contents, nested as the catalogue stores them.
+* @param depth - The current nesting level, which sets the indentation.
+* @returns The object type as TypeScript source.
+*/
+function typed(words, depth) {
+	const pad = "  ".repeat(depth);
+	return `{\n${Object.entries(words).toSorted(([one], [other]) => one.localeCompare(other)).map(([key, value]) => `${pad}  ${JSON.stringify(key)}: ${typeof value === "string" ? JSON.stringify(value) : typed(value, depth + 1)};`).join("\n")}\n${pad}}`;
+}
+/**
+* Renders the augmentation that adds every namespace to the foundation's `Resources`.
+*
+* @param index - The indexed catalogues.
+* @param fallback - The language whose strings type the keys.
+* @returns The declaration file as TypeScript source.
+*/
+function declared(index, fallback) {
+	const members = [...ofLanguage(index, fallback).entries()].toSorted(([one], [other]) => one.localeCompare(other)).map(([namespace, files]) => `    ${JSON.stringify(namespace)}: ${typed(mergedWords(files), 2)};`);
+	return `${HEADER}declare module ${JSON.stringify(FOUNDATION)} {\n  interface Resources {\n${members.join("\n")}\n  }\n}\n`;
+}
+//#endregion
+//#region src/plugin.ts
+/**
+* The plugin itself: it finds the catalogues, serves the module an application loads them from,
+* writes their types, and pushes a changed string to a running page.
+*/
+/**
+* The resolved identifier, whose leading NUL marks the module as this plugin's.
+*/
+const RESOLVED = `\0${ID}`;
+/**
+* The custom event name a changed catalogue is sent to the page under.
+*
+* @remarks
+*   The foundation listens for the same string. Neither package imports the other, so the name is a
+*   contract between them rather than a shared constant.
+*/
+const EVENT = "i18n:catalogue";
+/**
+* The default language that defines every key.
+*/
+const FALLBACK = "en";
+/**
+* The default path the generated types are written to, against the project root.
+*/
+const TYPES = "src/i18n.gen.d.ts";
+/**
+* Searches for the catalogues again and indexes them, keeping the namespaces the options accept.
+*
+* @param state - The state to write the result into.
+* @param options - Where to search and which namespaces to keep.
+*/
+function refound(state, options) {
+	const wanted = options.namespaces ?? (() => true);
+	state.catalogues = found(state.resolved.root, options.scopes).filter((one) => wanted(one.namespace));
+	state.index = indexed(state.catalogues);
+}
+/**
+* Writes the generated types, unless the options turn them off.
+*
+* @param state - The catalogues found.
+* @param options - Where to write and which language types the keys.
+* @returns True when the file changed.
+*/
+function retyped(state, options) {
+	if (options.types === false) return false;
+	return writeIfChanged(resolve(state.resolved.root, options.types ?? TYPES), declared(state.index, options.fallback ?? FALLBACK));
+}
+/**
+* Formats each fault in the catalogues as one line.
+*
+* @param state - The catalogues found.
+* @param options - Which language defines the keys.
+*/
+function wrong(state, options) {
+	return problems(state.index, options.fallback ?? FALLBACK).map(({ file: at, key, says }) => `${at}${key === "" ? "" : `: ${key}`} ${says}`);
+}
+/**
+* Reads the pair a catalogue file belongs to out of its path.
+*
+* @param path - A normalised path under a `locales` directory.
+* @returns The pair, or undefined when no language directory sits under `locales`.
+*/
+function pairOf(path) {
+	const rest = path.slice(path.lastIndexOf(`/${LOCALES}/`) + 7 + 2);
+	const at = rest.indexOf("/");
+	if (at === -1) return void 0;
+	return {
+		language: rest.slice(0, at),
+		namespace: namespaceOf(rest.slice(at + 1))
+	};
+}
+/**
+* Returns true when a path is a catalogue file.
+*
+* @param path - A normalised path.
+*/
+function catalogued(path) {
+	return EXTENSION.test(path) && path.includes(`/locales/`);
+}
+/**
+* Invalidates a module when the graph holds it, and does nothing when nothing imported it.
+*
+* @param graph - The module graph.
+* @param id - The module's resolved identifier.
+*/
+function stale(graph, id) {
+	const node = graph.getModuleById(id);
+	if (node !== void 0) graph.invalidateModule?.(node);
+}
+/**
+* Pushes a changed pair to a running page and invalidates the modules holding the old strings.
+*
+* @remarks
+*   The catalogues module is invalidated as well, because the fallback language is inlined in it,
+*   so a page loaded after the change gets the current strings.
+* @param state - The catalogues found.
+* @param options - Which language defines the keys, for the validation that follows.
+* @param pair - The language and namespace that changed.
+* @param watching - The environment the file changed in.
+*/
+function resent(state, options, pair, watching) {
+	stale(watching.environment.moduleGraph, `\0${pairId(pair.language, pair.namespace)}`);
+	stale(watching.environment.moduleGraph, RESOLVED);
+	watching.environment.hot.send(EVENT, {
+		language: pair.language,
+		namespace: pair.namespace,
+		words: mergedWords(filesOf(state.index, pair.language, pair.namespace))
+	});
+	for (const line of wrong(state, options)) globalThis.console.warn(line);
+}
+/**
+* Handles a catalogue file that was added or deleted.
+*
+* @remarks
+*   The search and the types run again, because the set of languages may have changed. The module
+*   is invalidated rather than sent, because sending it would refresh the component tree when only
+*   the strings changed.
+* @param state - The catalogues found.
+* @param options - Where to search.
+* @param path - The file that appeared or disappeared.
+* @param watching - The environment the file changed in.
+*/
+function refollowed(state, options, path, watching) {
+	refound(state, options);
+	retyped(state, options);
+	const pair = pairOf(path);
+	if (pair === void 0) stale(watching.environment.moduleGraph, RESOLVED);
+	else resent(state, options, pair, watching);
+}
+/**
+* Builds the plugin that finds the catalogues, types their keys, and serves `virtual:i18n`.
+*
+* @remarks
+*   On a dev server a catalogue change is pushed to the page as an event rather than a reload, so
+*   the page keeps its state. In a build an invalid catalogue throws instead.
+* @param options - Where to search and what to write. `Options` documents every member.
+* @returns The plugin.
+*/
+function i18n(options = {}) {
+	const state = {
+		catalogues: [],
+		index: /* @__PURE__ */ new Map(),
+		resolved: {
+			command: "serve",
+			root: process.cwd()
+		}
+	};
+	return {
+		/**
+		* Throws on an invalid catalogue during a build, and warns during a dev server run.
+		*
+		* @throws {@link Error} When a catalogue defines an unknown key or drops a placeholder.
+		*/
+		buildStart() {
+			const lines = wrong(state, options);
+			if (lines.length === 0) return;
+			if (state.resolved.command === "build") throw new Error(lines.join("\n"));
+			for (const line of lines) this.warn(line);
+		},
+		/**
+		* Records the root, runs the search, and writes the types.
+		*
+		* @param config - The resolved configuration.
+		*/
+		configResolved(config) {
+			state.resolved = config;
+			refound(state, options);
+			retyped(state, options);
+		},
+		/**
+		* Adds every `locales` directory to the watcher, including those outside the project root.
+		*
+		* @param server - The dev server.
+		*/
+		configureServer(server) {
+			server.watcher.add([...new Set(state.catalogues.map((one) => dirname(dirname(one.file))))]);
+		},
+		/**
+		* Handles a catalogue change on a dev server by pushing the new strings to the page.
+		*
+		* @param changed - The file, what happened to it, and the modules the change reached.
+		* @returns An empty array for a catalogue, or undefined for any other file.
+		*/
+		hotUpdate(changed) {
+			const path = normalizePath(changed.file);
+			if (!catalogued(path)) return void 0;
+			if (changed.type !== "update") {
+				refollowed(state, options, path, this);
+				return [];
+			}
+			const catalogue = state.catalogues.find((one) => one.file === path);
+			if (catalogue === void 0) return void 0;
+			resent(state, options, catalogue, this);
+			return [];
+		},
+		/**
+		* Serves the catalogues module, or the module one pair is fetched as.
+		*
+		* @param id - The module being loaded.
+		* @returns The source, or undefined when the module is not this plugin's.
+		*/
+		load(id) {
+			if (id === RESOLVED) return cataloguesModule(state.index, options.fallback ?? FALLBACK, options.eager ?? false);
+			const pair = pairOfId(id);
+			return pair === void 0 ? void 0 : pairModule(filesOf(state.index, pair.language, pair.namespace));
+		},
+		name: "stealth:i18n",
+		/**
+		* Claims the catalogues specifier and every pair specifier.
+		*
+		* @param id - The specifier being resolved.
+		* @returns The resolved identifier, or undefined for any other import.
+		*/
+		resolveId(id) {
+			return id === "virtual:i18n" || pairOfId(id) !== void 0 ? `\0${id}` : void 0;
+		},
+		/**
+		* Runs the search and the types again during a watching build.
+		*
+		* @remarks
+		*   A dev server reports the same change to `hotUpdate`, which pushes the strings to the page,
+		*   so this hook ignores a change while serving. A watching build has no page and rebuilds.
+		* @param id - The file that changed.
+		*/
+		watchChange(id) {
+			if (state.resolved.command !== "build" || !catalogued(normalizePath(id))) return;
+			refound(state, options);
+			retyped(state, options);
+		}
+	};
+}
+//#endregion
+export { EVENT, FOUNDATION, ID, LOCALES, cataloguesModule, declared, found, i18n, indexed, pairId, pairOfId, problems };

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@stealthscale/vite-plugin-i18n",
+  "version": "0.0.0",
+  "description": "Finds every catalogue an application can reach, types their keys, and answers the module it loads them from.",
+  "keywords": [
+    "i18n",
+    "vite-plugin"
+  ],
+  "homepage": "https://github.com/stealth-scale/config/tree/main/packages/vite-plugin-i18n#readme",
+  "bugs": "https://github.com/stealth-scale/config/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stealth-scale/config.git",
+    "directory": "packages/vite-plugin-i18n"
+  },
+  "files": [
+    "client.d.ts",
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "imports": {
+    "#*": "./src/*"
+  },
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json",
+    "./client": "./client.d.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "yaml": "^2.9.1"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/core": "^0.18.5",
+    "@stealthscale/testing": "^0.3.0",
+    "@stealthscale/testing-config": "^0.3.0",
+    "@stealthscale/vite-config": "^0.6.0",
+    "@stealthscale/vite-config-typescript": "^0.3.0",
+    "@stealthscale/vite-plugin-base": "^0.2.0",
+    "@types/node": "^26.5.1",
+    "@vitest/coverage-v8": "4.1.11",
+    "publint": "^0.3.24",
+    "typescript": "^7.0.2",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.3.1",
+    "vitest": "4.1.11"
+  },
+  "peerDependencies": {
+    "@stealthscale/vite-plugin-base": "^0.2.0",
+    "vite": "^8.0.0"
+  },
+  "engines": {
+    "node": ">=26.0.0"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "check": "vp check",
+    "test": "vp test"
+  }
+}