@stealthscale/vite-plugin-i18n 0.0.0 → 0.3.1

package/dist/index.mjs

@@ -1,20 +1,21 @@
-import { existsSync, globSync, readFileSync } from "node:fs";
+import { existsSync, globSync, mkdirSync, readFileSync, writeFileSync } 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";
+import { manifestAt, packageAt, scratchDir, text, writeIfChanged } from "@stealthscale/vite-plugin-base";
 //#region src/find.ts
 /**
-* Locates every `locales/<language>/<namespace>.json` an application and its dependencies ship.
+* Finds every catalogue file under `locales/<language>/` that an application and its dependencies
+* ship.
 *
 * @remarks
-*   A namespace is the first path segment under the language. `menu.json` and
+*   A namespace is the first path segment under the language, so `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.
+*   its keys under `sections.billing`. A namespace is fetched as one module however many files it
+*   is split across.
 */
 /**
-* The directory a package keeps its catalogues in.
+* Gives the directory a package keeps its catalogues in.
 */
 const LOCALES = "locales";
 /**
@@ -22,10 +23,14 @@ const LOCALES = "locales";
 */
 const EXTENSION = /\.(?:json|ya?ml)$/u;
 /**
-* Returns the namespace a file belongs to.
+* The scope of the house's packages, which the walk follows from an application in any scope,
+* because the plugin host renders words from the catalogue its package publishes.
+*/
+const HOUSE = "@stealthscale";
+/**
+* Returns the namespace a file belongs to, which is its first path segment with any extension
+* stripped.
 *
-* @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) {
@@ -33,10 +38,8 @@ function namespaceOf(relative) {
 	return at === -1 ? relative.replace(EXTENSION, "") : relative.slice(0, at);
 }
 /**
-* Returns the prefix a file's keys are nested under.
+* Returns the dotted prefix a file's keys nest under, taken from its path below the namespace.
 *
-* @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.
 */
@@ -45,7 +48,8 @@ function prefixOf(relative) {
 	return at === -1 ? "" : relative.slice(at + 1).replace(EXTENSION, "").replaceAll("/", ".");
 }
 /**
-* Lists every catalogue file under one directory's `locales`, at any depth.
+* Lists every catalogue file under one directory's `locales`, at any depth, and nothing where the
+* directory has no `locales`.
 *
 * @param directory - The package or application directory to search.
 * @param owner - The package name to record on each result.
@@ -69,7 +73,7 @@ function cataloguesIn(directory, owner, own) {
 	});
 }
 /**
-* Returns the scope a package name carries.
+* Returns the scope part of a package name.
 *
 * @param name - The package name, or undefined when the manifest declares none.
 * @returns The scope such as `@stealthscale`, or undefined for an unscoped name.
@@ -82,16 +86,16 @@ function scopeOf(name) {
 *
 * @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.
+*   siblings as peers. The root's `devDependencies` count as well, because an application declares
+*   the packages its examples import and a package declares the siblings its specimens import.
 * @param manifest - The parsed package.json.
-* @param own - True for the application's own manifest.
+* @param starting - True for the manifest the search starts from.
 */
-function namesIn(manifest, own) {
+function namesIn(manifest, starting) {
 	return [
 		"dependencies",
 		"peerDependencies",
-		...own ? ["devDependencies"] : []
+		...starting ? ["devDependencies"] : []
 	].flatMap((field) => {
 		const declared = manifest[field];
 		return typeof declared === "object" && declared !== null ? Object.keys(declared) : [];
@@ -105,53 +109,57 @@ function namesIn(manifest, own) {
 *   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.
+* @param starting - True for the directory the search starts from, whose development dependencies
+*   are followed.
+* @returns Each package with its manifest, the starting directory last, and nothing for a
+*   directory already visited or holding no manifest.
 */
-function walked(directory, walk, own) {
+function walked(directory, walk, starting) {
 	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)), {
+	return [...namesIn(manifest, starting).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.
+* Lists every catalogue a root 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.
+*   Where two packages declare the same language and namespace, the one later in the result wins
+*   the merge, and the root goes last for that reason. Each package is resolved through Node's
+*   resolution, so a workspace link and an installed copy are both found.
+* @param root - The application or package directory.
+* @param scopes - The scopes to follow. Defaults to the root's own scope and {@link HOUSE}.
 * @returns The catalogues in merge order.
 */
 function found(root, scopes) {
-	const own = manifestAt(root);
-	const named = own === void 0 ? void 0 : text(own, "name");
+	const manifest = manifestAt(root);
+	const named = manifest === void 0 ? void 0 : text(manifest, "name");
+	const application = manifest?.["private"] === true;
 	return walked(root, {
-		scopes: new Set(scopes ?? [scopeOf(named)].filter((scope) => scope !== void 0)),
+		scopes: new Set(scopes ?? [scopeOf(named), HOUSE].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));
+	}, true).flatMap((one) => cataloguesIn(one.at, text(one.manifest, "name") ?? basename(one.at), application && one.at === root));
 }
 //#endregion
 //#region src/emit.ts
 /**
-* Generates the module an application imports its catalogues from, and one module per pair.
+* Generates the virtual module an application imports its catalogues from, and one module per
+* language and namespace pair.
 */
 /**
-* The specifier an application imports to reach its catalogues.
+* 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.
+*   Neither a language tag nor a namespace contains a slash, so {@link 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`.
@@ -162,7 +170,7 @@ function pairId(language, namespace) {
 /**
 * Splits a pair module's specifier back into its language and namespace.
 *
-* @param id - A specifier, with or without the resolution prefix.
+* @param id - A specifier, with or without the resolved-module prefix.
 * @returns The pair, or undefined when the specifier addresses something else.
 */
 function pairOfId(id) {
@@ -173,7 +181,7 @@ function pairOfId(id) {
 	} : void 0;
 }
 /**
-* Indexes catalogues by language and namespace, preserving the order they were found in.
+* Indexes catalogues by language and namespace, keeping the order they were found in.
 *
 * @param catalogues - Every catalogue found.
 */
@@ -189,7 +197,7 @@ function indexed(catalogues) {
 	return byLanguage;
 }
 /**
-* Returns one language's catalogues indexed by namespace.
+* Returns one language's catalogues, indexed by namespace.
 *
 * @param index - The indexed catalogues.
 * @param language - The BCP 47 tag.
@@ -199,7 +207,7 @@ function ofLanguage(index, language) {
 	return index.get(language) ?? /* @__PURE__ */ new Map();
 }
 /**
-* Returns every file that belongs to one pair.
+* Returns the files that belong to one language and namespace pair.
 *
 * @param index - The indexed catalogues.
 * @param language - The BCP 47 tag.
@@ -210,7 +218,7 @@ 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.
+* Reports whether a parsed value is an object whose every leaf is a string.
 *
 * @param value - The parsed file contents.
 */
@@ -221,7 +229,7 @@ function isWords(value) {
 * 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.
+* @returns The contents, nested as written.
 * @throws {@link Error} When the file does not parse to an object of strings.
 */
 function wordsOf(catalogue) {
@@ -231,7 +239,7 @@ function wordsOf(catalogue) {
 	return parsed;
 }
 /**
-* Parses one catalogue file and nests its contents under the file's prefix.
+* Parses one catalogue file and nests its contents under the file's own prefix.
 *
 * @remarks
 *   A `title` key in `menu/sections/billing.json` comes back as `sections.billing.title`.
@@ -243,8 +251,8 @@ function nested(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.
+* @param under - Contents merged so far.
+* @param over - Contents to apply on top.
 */
 function merged(under, over) {
 	const result = { ...under };
@@ -257,13 +265,13 @@ function merged(under, over) {
 /**
 * 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.
+* @param files - The files in merge order. The last one wins 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.
+* Generates the module a pair is fetched as, with every file of the pair merged into it.
 *
 * @param files - The files in merge order.
 */
@@ -271,19 +279,49 @@ 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.
+* Matches a language tag or a namespace that the loader table writes inside a string literal as it
+* is: letters, digits, `_`, `.` and `-`.
+*/
+const NAME$1 = /^[\w.-]+$/u;
+/**
+* Returns a language tag or a namespace that the loader table can write inside a string literal.
 *
+* @param name - The language tag or the namespace.
+* @throws {@link Error} When the name contains a character other than a letter, a digit, `_`, `.`
+*   or `-`.
+*/
+function checked$1(name) {
+	if (!NAME$1.test(name)) throw new Error(`The catalogue name "${name}" contains a character other than a letter, a digit, "_", "." or "-".`);
+	return name;
+}
+/**
+* Generates the loader table, one dynamic import per pair, for the languages the module does not
+* inline.
+*
+* @remarks
+*   Every entry ends in its own comma, so a table with no language and a language with no namespace
+*   both close as valid objects. An inlined language gets no loader entry. Leaving one in would
+*   still make the bundler emit a chunk per pair even though nothing calls it, which is how the
+*   docs build came to emit the `specimen` namespace twice. The table writes each language tag and
+*   namespace inside its string literal as it is, after `checked` refuses any other character.
 * @param index - The indexed catalogues.
+* @param inlining - Languages the module inlines.
 * @returns The table as JavaScript source.
+* @throws {@link Error} When a language tag or a namespace contains a character other than a
+*   letter, a digit, `_`, `.` or `-`.
 */
-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}`;
+function loaders(index, inlining) {
+	const languages = [...index.entries()].filter(([language]) => !inlining.has(language)).map(([language, byNamespace]) => {
+		const tag = checked$1(language);
+		return `  "${tag}": {\n${[...byNamespace.keys()].map((namespace) => {
+			const name = checked$1(namespace);
+			return `    "${name}": () => import("${pairId(tag, name)}"),`;
+		}).join("\n")}\n  },`;
+	});
+	return languages.length === 0 ? "{}" : `{\n${languages.join("\n")}\n}`;
 }
 /**
-* Merges each namespace of one language, for inlining into the module.
+* Merges each namespace of one language, ready to inline into the module.
 *
 * @param index - The indexed catalogues.
 * @param language - The BCP 47 tag.
@@ -292,7 +330,7 @@ function inlined(index, language) {
 	return Object.fromEntries([...ofLanguage(index, language).entries()].map(([namespace, files]) => [namespace, mergedWords(files)]));
 }
 /**
-* Lists every namespace any language declares, sorted.
+* Lists every namespace any language declares, sorted, each one once.
 *
 * @param index - The indexed catalogues.
 */
@@ -305,24 +343,25 @@ function namespacesIn(index) {
 * 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.
+*   The fallback language is inlined, so the first paint needs no request. Every other language is
+*   fetched through the loader. Under `eager` every language is inlined and the loader fetches
+*   nothing, trading a larger bundle for one saved request per language.
 * @param index - The indexed catalogues.
 * @param fallback - The language that defines every key.
-* @param eager - Inlines every language when true.
+* @param eager - Whether to inline every language rather than the fallback alone.
 * @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)]));
+	const inlining = eager ? languages : [fallback];
+	const bundled = Object.fromEntries(inlining.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)};`,
+		`const loaders = ${loaders(index, new Set(inlining))};`,
 		"",
 		"export async function load(language, namespace) {",
 		"  const loader = loaders[language]?.[namespace];",
@@ -340,22 +379,22 @@ function cataloguesModule(index, fallback, eager = false) {
 * 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.
+*   An undefined key, a dropped placeholder and a key one package declares twice all reach the page
+*   as a wrong string. The build reports them rather than shipping them.
 */
 /**
-* Matches an i18next placeholder, `{{name}}` or `{{name, format}}`.
+* Pattern for an i18next placeholder, `{{name}}` or `{{name, format}}`, capturing the name.
 */
 const PLACEHOLDER = /\{\{\s*([^,}\s]+)/gu;
 /**
-* Matches a plural suffix, which is one of the six categories CLDR defines.
+* Pattern for a plural suffix, 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.
+* @param words - Contents, nested as the file stores them.
+* @param prefix - Path down to these contents. Empty at the top level.
 */
 function flattened(words, prefix = "") {
 	const flat = /* @__PURE__ */ new Map();
@@ -367,9 +406,9 @@ function flattened(words, prefix = "") {
 	return flat;
 }
 /**
-* Lists the placeholder names one string carries.
+* Lists the placeholder names one string contains.
 *
-* @param word - One translated string.
+* @param word - A translated string.
 * @returns Each name once, sorted.
 */
 function placeholdersOf(word) {
@@ -378,6 +417,10 @@ function placeholdersOf(word) {
 /**
 * Strips a plural or context suffix, so `pages_one` can be checked against any `pages_*`.
 *
+* @remarks
+*   Everything after the last underscore is taken as the suffix, whether or not it is one. A key
+*   whose own name carries an underscore loses its tail here and matches more broadly than it
+*   should.
 * @param key - A dotted key, with or without a suffix.
 */
 function stem(key) {
@@ -385,11 +428,11 @@ function stem(key) {
 	return at === -1 ? key : key.slice(0, at);
 }
 /**
-* Lists the placeholders a translation has to carry.
+* Lists the placeholders a translation is required 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`.
+*   A plural form drops `count` from the requirement. Some languages spell the number out in 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.
 */
@@ -398,13 +441,13 @@ function wanted(key, against) {
 	return PLURAL.test(key) ? names.filter((name) => name !== "count") : names;
 }
 /**
-* Reports a placeholder a restated key drops.
+* Reports the placeholders an overriding string 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.
+* @param file - The file that overrides the key.
+* @param key - The key being overridden.
+* @param word - The string the overriding file gives the key.
+* @param against - The string already defined for the key.
+* @returns One problem, or an empty array when the string carries every placeholder.
 */
 function placeholdersChecked(file, key, word, against) {
 	const carried = placeholdersOf(word);
@@ -418,6 +461,10 @@ function placeholdersChecked(file, key, word, against) {
 /**
 * Validates one translation against the fallback's definition of its namespace.
 *
+* @remarks
+*   A key with no exact match falls back to the `_other` form of its stem, so a language carrying
+*   more plural categories than the fallback is checked against the fallback's plural string rather
+*   than reported as undefined.
 * @param file - The translation to check.
 * @param defined - The fallback's contents for that namespace, flattened.
 */
@@ -439,15 +486,15 @@ function checked(file, defined) {
 	return found;
 }
 /**
-* Builds the fallback's definition of one namespace, collecting faults as it merges.
+* Merges the fallback's files for one namespace and collects the faults the merge exposes.
 *
 * @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.
+*   A package defines whatever keys it ships and another package may override one. An application
+*   may override a key too, but a key it adds to a namespace a package owns is reported as a typo.
+*   One owner declaring a key in two files is a fault wherever it happens, because the merge picks
+*   one of them silently.
 * @param files - The fallback files of the namespace, in merge order.
-* @param found - The array faults are pushed onto.
+* @param found - Array the faults are pushed onto.
 * @returns The namespace's contents, flattened.
 */
 function definition(files, found) {
@@ -478,12 +525,14 @@ function definition(files, found) {
 	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.
+* Validates the fallback's files against each other, then every translation against the fallback.
 *
+* @remarks
+*   An index with no entry for the fallback language reports nothing, on the grounds that there is
+*   nothing to check against.
 * @param index - The indexed catalogues.
 * @param fallback - The language that defines every key.
-* @returns Every fault, the fallback's first, then in file order.
+* @returns Every fault, the fallback's first and the rest in file order.
 */
 function problems(index, fallback) {
 	const defining = index.get(fallback);
@@ -555,65 +604,131 @@ function declared(index, fallback) {
 //#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.
+* Vite plugin for translation catalogues: finds them, serves the modules 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.
+* Resolved id of the catalogues module, with the leading NUL that marks it as generated.
 */
 const RESOLVED = `\0${ID}`;
 /**
-* The custom event name a changed catalogue is sent to the page under.
+* Name the plugin registers under, which `cataloguesOf` finds it by.
+*/
+const NAME = "stealth:i18n";
+/**
+* Returns the catalogue plugin's `api` among a configuration's plugins, or undefined where the
+* configuration has no catalogue plugin.
+*
+* @param plugins - The plugins of a resolved configuration.
+*/
+function cataloguesOf(plugins) {
+	return plugins.find((plugin) => plugin.name === NAME)?.api;
+}
+/**
+* Name of the custom event 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.
+*   contract between them and not a shared constant.
 */
 const EVENT = "i18n:catalogue";
 /**
-* The default language that defines every key.
+* Default for {@link Options.fallback}: the language every key is defined in.
 */
 const FALLBACK = "en";
 /**
-* The default path the generated types are written to, against the project root.
+* Default for {@link Options.types}, resolved against the project root.
 */
 const TYPES = "src/i18n.gen.d.ts";
 /**
+* Directory name the plugin's scratch space takes under the system temporary directory.
+*/
+const SCRATCH = "stealth-i18n";
+/**
+* File under the scratch that the plugin rewrites whenever a catalogue file appears or disappears
+* outside the module-per-file server.
+*
+* @remarks
+*   The catalogues module lists the stamp as a file to watch, so the bundler rebuilds the module
+*   when the stamp changes. A bundler watches the files a module read, and a new file is not one of
+*   them, so the plugin turns its appearance into a change to the stamp.
+*/
+const STAMP = "topology";
+/**
+* The payload sent when the set of languages and namespaces changes under a server that bundles.
+*/
+const RELOAD = {
+	path: "*",
+	type: "full-reload"
+};
+/**
+* Renders every language and namespace pair an index contains as sorted lines, for comparing one
+* search against the last.
+*
+* @remarks
+*   The catalogues module's exports and loader table depend on the shape as well as on the words. A
+*   page that already imported the module cannot pick up a shape change from a pushed event, so the
+*   plugin hands the module back for a reload.
+*/
+function shapeOf(index) {
+	return [...index.entries()].flatMap(([language, byNamespace]) => [...byNamespace.keys()].map((namespace) => `${language}/${namespace}`)).toSorted().join("\n");
+}
+/**
 * Searches for the catalogues again and indexes them, keeping the namespaces the options accept.
 *
-* @param state - The state to write the result into.
+* @param state - The state whose catalogues, index and shape are replaced.
 * @param options - Where to search and which namespaces to keep.
+* @returns True when the set of languages and namespaces differs from the last search's.
 */
 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);
+	const shape = shapeOf(state.index);
+	const reshaped = shape !== state.shape;
+	state.shape = shape;
+	return reshaped;
 }
 /**
 * 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.
+* @returns True when the file's content changed, false when it matched or types are off.
 */
 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.
+* Rewrites the stamp with a new timestamp, so a bundler watching it rebuilds the catalogues
+* module.
+*
+* @remarks
+*   `process.hrtime.bigint` has nanosecond resolution, so two writes within the same millisecond
+*   still produce different content.
+* @param state - The state that contains the stamp's path.
+*/
+function stamped(state) {
+	mkdirSync(dirname(state.stamp), { recursive: true });
+	writeFileSync(state.stamp, `${process.hrtime.bigint()}\n`);
+}
+/**
+* Formats each fault in the catalogues as one line naming the file, the key where the fault has
+* one, and what is wrong.
 *
 * @param state - The catalogues found.
 * @param options - Which language defines the keys.
+* @returns One line per fault, empty when every catalogue is valid.
 */
 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.
+* Reads the language and namespace 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`.
+* @returns The pair, or undefined when the path has no language directory under `locales`.
 */
 function pairOf(path) {
 	const rest = path.slice(path.lastIndexOf(`/${LOCALES}/`) + 7 + 2);
@@ -625,7 +740,7 @@ function pairOf(path) {
 	};
 }
 /**
-* Returns true when a path is a catalogue file.
+* Returns true for a path with a catalogue extension under a `locales` directory.
 *
 * @param path - A normalised path.
 */
@@ -633,9 +748,22 @@ 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.
+* Returns the `locales` directory a catalogue is under, which contains every language of its
+* package.
 *
-* @param graph - The module graph.
+* @remarks
+*   A catalogue in a namespace directory, such as `locales/en/specimen/badge.json`, is two levels
+*   below its language. The directory is cut from the path at the catalogue's own language, so a
+*   watcher given it reports a language directory that appears beside that one.
+*/
+function localesOf(catalogue) {
+	const at = catalogue.file.lastIndexOf(`/${LOCALES}/${catalogue.language}/`);
+	return catalogue.file.slice(0, at + 7 + 1);
+}
+/**
+* Invalidates a module the graph contains, and does nothing for one nothing imported.
+*
+* @param graph - The module graph to look the module up in and invalidate through.
 * @param id - The module's resolved identifier.
 */
 function stale(graph, id) {
@@ -643,11 +771,22 @@ function stale(graph, id) {
 	if (node !== void 0) graph.invalidateModule?.(node);
 }
 /**
-* Pushes a changed pair to a running page and invalidates the modules holding the old strings.
+* Returns the payload a changed pair is sent to the page with: every file of the pair, merged.
+*/
+function changedOf(state, pair) {
+	return {
+		language: pair.language,
+		namespace: pair.namespace,
+		words: mergedWords(filesOf(state.index, pair.language, pair.namespace))
+	};
+}
+/**
+* Pushes a changed pair to a running page, invalidates the modules that contain the old strings,
+* and warns about any fault the change introduced.
 *
 * @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.
+*   The catalogues module is invalidated as well as the pair's own, 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.
@@ -656,40 +795,144 @@ function stale(graph, id) {
 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))
-	});
+	watching.environment.hot.send(EVENT, changedOf(state, pair));
 	for (const line of wrong(state, options)) globalThis.console.warn(line);
 }
 /**
-* Handles a catalogue file that was added or deleted.
+* Pushes the pair a changed file belongs to under a server that bundles, and warns about any fault
+* the change introduced.
 *
 * @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.
+*   That server applies a rebuilt catalogues module in place, through the first module above it
+*   that accepts a hot update, and the i18next instance the page built keeps its strings. The pair
+*   therefore goes to the page as the event the hot update hook sends. The server's watcher and
+*   the bundler's both report an edit, so a payload equal to the last one sent is dropped.
+* @param state - The catalogues found, and the last payload sent.
+* @param options - Which language defines the keys, for the validation that follows.
+* @param path - The normalised path of the file that changed.
+* @param channel - The channel to the page.
+*/
+function pushed(state, options, path, channel) {
+	const pair = pairOf(path);
+	if (pair === void 0) return;
+	const changed = changedOf(state, pair);
+	const sent = JSON.stringify(changed);
+	if (sent === state.sent) return;
+	state.sent = sent;
+	channel.send(EVENT, changed);
+	for (const line of wrong(state, options)) globalThis.console.warn(line);
+}
+/**
+* Runs the search and the types again after a change a bundler reported, and rewrites the stamp
+* where the catalogues module has to be built again.
+*
+* @remarks
+*   A module lists the files it read, so an edit to one of them rebuilds the module without the
+*   stamp. A file that appears or disappears is in no module's list, so the stamp is rewritten for
+*   it, as it is for a change to the set of languages and namespaces.
+* @param state - The catalogues found, searched again here.
+* @param options - Where to search.
+* @param change - The kind of change, where the bundler reports one.
+* @returns True when the set of languages and namespaces changed.
+*/
+function rebuilt(state, options, change) {
+	const reshaped = refound(state, options);
+	retyped(state, options);
+	if (reshaped || change?.event === "create" || change?.event === "delete") stamped(state);
+	return reshaped;
+}
+/**
+* Follows a catalogue change during a watching build or under a server that bundles, and brings a
+* running page up to date under the server.
+*
+* @remarks
+*   A server that serves a module per file reports the same change to `hotUpdate`, so a change
+*   under that server is ignored here. A server that bundles runs no hot update hook. There the
+*   changed pair goes to the page, and the page reloads when the set of languages and namespaces
+*   changed, because a running page cannot take a new set from an event. A watching build has no
+*   page.
 * @param state - The catalogues found.
+* @param options - Where to search and which language defines the keys.
+* @param reported - The change, the environment and the file.
+*/
+function followed(state, options, reported) {
+	const { change, environment, path } = reported;
+	if (state.resolved.command === "build") {
+		rebuilt(state, options, change);
+		return;
+	}
+	if (environment?.config.isBundled !== true) return;
+	const reshaped = rebuilt(state, options, change);
+	const channel = environment.hot;
+	if (channel === void 0) return;
+	if (reshaped) channel.send(RELOAD);
+	else pushed(state, options, path, channel);
+}
+/**
+* Handles a catalogue file that was added or deleted.
+*
+* @remarks
+*   The search and the types run again, because the set of languages and namespaces may have
+*   changed. Where it did, the catalogues module goes back to the server for a reload, because a
+*   running page imported the old set and no pushed event replaces it. Where only the words of a
+*   pair changed, the pair is pushed to the page and the page keeps its state.
+* @param state - The catalogues found, searched again here.
 * @param options - Where to search.
 * @param path - The file that appeared or disappeared.
 * @param watching - The environment the file changed in.
+* @returns The catalogues module where the server has to reload it, and an empty array otherwise.
 */
 function refollowed(state, options, path, watching) {
-	refound(state, options);
+	const reshaped = refound(state, options);
 	retyped(state, options);
+	if (reshaped) {
+		stamped(state);
+		const node = watching.environment.moduleGraph.getModuleById(RESOLVED);
+		return node === void 0 ? [] : [node];
+	}
 	const pair = pairOf(path);
 	if (pair === void 0) stale(watching.environment.moduleGraph, RESOLVED);
 	else resent(state, options, pair, watching);
+	return [];
 }
 /**
-* Builds the plugin that finds the catalogues, types their keys, and serves `virtual:i18n`.
+* Selects the files whose words the catalogues module inlines: every catalogue when eager, and the
+* fallback language's alone otherwise.
+*
+* @param state - The catalogues found.
+* @param options - Whether every language is inlined, and which one is otherwise.
+* @returns The catalogues to inline, which are also the files the module watches.
+*/
+function inlinedFiles(state, options) {
+	if (options.eager === true) return state.catalogues;
+	return [...ofLanguage(state.index, options.fallback ?? FALLBACK).values()].flat();
+}
+/**
+* Returns what the plugin offers another plugin through its `api`. The catalogues and the words are
+* read from the state when they are called, so they follow every search after a change.
+*
+* @param state - The catalogues found, searched again on each change.
+* @param options - The fallback language.
+*/
+function offered(state, options) {
+	return {
+		catalogues: () => state.catalogues,
+		fallback: options.fallback ?? FALLBACK,
+		words: (language, namespace) => mergedWords(filesOf(state.index, language, namespace))
+	};
+}
+/**
+* Creates 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.
+*   On a dev server the plugin sends a changed catalogue to the page as an event and not as a
+*   reload, so the page keeps its state. A build throws on an invalid catalogue. Every module
+*   lists the files it read as files to watch, so a bundler that rebuilds on a change rebuilds the
+*   module.
+* @param options - Where to search and what to write. {@link Options} Documents every member, and
+*   every one has a default.
+* @returns The plugin, with its state set to the working directory until `configResolved`
+*   replaces it.
 */
 function i18n(options = {}) {
 	const state = {
@@ -698,13 +941,19 @@ function i18n(options = {}) {
 		resolved: {
 			command: "serve",
 			root: process.cwd()
-		}
+		},
+		sent: "",
+		shape: "",
+		stamp: join(scratchDir(SCRATCH, process.cwd()), STAMP)
 	};
 	return {
+		api: offered(state, options),
 		/**
-		* Throws on an invalid catalogue during a build, and warns during a dev server run.
+		* Throws on an invalid catalogue during a build, and warns through the bundler on a dev server
+		* run.
 		*
-		* @throws {@link Error} When a catalogue defines an unknown key or drops a placeholder.
+		* @throws {@link Error} When the command is `build` and a catalogue defines an unknown key or
+		*   drops a placeholder. The message lists every fault, one per line.
 		*/
 		buildStart() {
 			const lines = wrong(state, options);
@@ -713,76 +962,93 @@ function i18n(options = {}) {
 			for (const line of lines) this.warn(line);
 		},
 		/**
-		* Records the root, runs the search, and writes the types.
+		* Records the resolved configuration and the stamp's path for that root, then runs the first
+		* search and writes the types.
 		*
 		* @param config - The resolved configuration.
 		*/
 		configResolved(config) {
 			state.resolved = config;
+			state.stamp = join(scratchDir(SCRATCH, config.root), STAMP);
 			refound(state, options);
 			retyped(state, options);
 		},
 		/**
-		* Adds every `locales` directory to the watcher, including those outside the project root.
+		* Registers every `locales` directory with the watcher, including those outside the project
+		* root, so a file, a namespace or a language that appears under one is reported.
 		*
-		* @param server - The dev server.
+		* @param server - The dev server whose watcher the directories are added to.
 		*/
 		configureServer(server) {
-			server.watcher.add([...new Set(state.catalogues.map((one) => dirname(dirname(one.file))))]);
+			server.watcher.add([...new Set(state.catalogues.map((one) => localesOf(one)))]);
 		},
 		/**
 		* 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.
+		* @remarks
+		*   The types are written again on an edit too, because a key or a placeholder added to the
+		*   fallback language changes what the page may ask for.
+		* @param changed - The file, what happened to it, and the modules the change affects.
+		* @returns The catalogues module where the page has to reload it, an empty array for a
+		*   catalogue pushed to the page, or undefined for a file this plugin does not handle, which
+		*   leaves the change to the bundler.
 		*/
 		hotUpdate(changed) {
 			const path = normalizePath(changed.file);
 			if (!catalogued(path)) return void 0;
-			if (changed.type !== "update") {
-				refollowed(state, options, path, this);
-				return [];
-			}
+			if (changed.type !== "update") return refollowed(state, options, path, this);
 			const catalogue = state.catalogues.find((one) => one.file === path);
 			if (catalogue === void 0) return void 0;
+			retyped(state, options);
 			resent(state, options, catalogue, this);
 			return [];
 		},
 		/**
-		* Serves the catalogues module, or the module one pair is fetched as.
+		* Serves the catalogues module, or the module one pair is fetched as, declaring the files each
+		* one read as files to watch.
 		*
-		* @param id - The module being loaded.
-		* @returns The source, or undefined when the module is not this plugin's.
+		* @param id - The resolved identifier of the module being loaded.
+		* @returns The generated 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);
+			if (id === RESOLVED) {
+				if (!existsSync(state.stamp)) stamped(state);
+				this.addWatchFile(state.stamp);
+				for (const one of inlinedFiles(state, options)) this.addWatchFile(one.file);
+				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));
+			if (pair === void 0) return void 0;
+			const files = filesOf(state.index, pair.language, pair.namespace);
+			for (const one of files) this.addWatchFile(one.file);
+			return pairModule(files);
 		},
-		name: "stealth:i18n",
+		name: NAME,
 		/**
-		* Claims the catalogues specifier and every pair specifier.
+		* Claims the catalogues specifier and every pair specifier, leaving every other import alone.
 		*
 		* @param id - The specifier being resolved.
-		* @returns The resolved identifier, or undefined for any other import.
+		* @returns The specifier behind a NUL, 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.
+		* Follows a catalogue change during a watching build or under a server that bundles.
 		*
-		* @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.
+		* @param id - The path of the file that changed.
+		* @param change - Whether the file was created, deleted or updated, where the bundler reports
+		*   it.
 		*/
-		watchChange(id) {
-			if (state.resolved.command !== "build" || !catalogued(normalizePath(id))) return;
-			refound(state, options);
-			retyped(state, options);
+		watchChange(id, change) {
+			const path = normalizePath(id);
+			if (catalogued(path)) followed(state, options, {
+				change,
+				environment: this.environment,
+				path
+			});
 		}
 	};
 }
 //#endregion
-export { EVENT, FOUNDATION, ID, LOCALES, cataloguesModule, declared, found, i18n, indexed, pairId, pairOfId, problems };
+export { EVENT, FOUNDATION, ID, LOCALES, cataloguesModule, cataloguesOf, declared, found, i18n, indexed, pairId, pairOfId, problems };