@edgekits/i18n-core 0.0.0-stage → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this package are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the package uses
+[Semantic Versioning](https://semver.org/).
+
+## 0.2.1 — 2026-10-27
+
+No changes; released in lockstep with the plugin rename (see `@edgekits/astro-i18n` 0.2.1).
+
+## 0.2.0 — 2026-10-27
+
+First release, extracted from `@edgekits/astro-i18n` 0.1.8: the engine with no framework in it.
+
+### Added
+
+- `createI18n(config, generated, bindings)`: one instance per project. The platform bindings
+  (KV, cache, `waitUntil`, the two flags) are arguments, read when a function runs, so getters
+  over request-scoped values work. The instance carries the locale constants, the generated
+  `NAMESPACE_KEYS`, the fetcher, the fallback cascade, the lang-cookie helpers over any
+  `CookieJar` and the KV key and cache URL builders.
+- No zod: locales are checked by `isLocale`/`parseLocale` against the config's `languages`.
+- `routing` is optional and validated here, but read by the adapter (`'prefix'`,
+  `'prefix-except-default'`).
+- The fallback cascade takes a `userPreference` source between the cookie and
+  Accept-Language.
+- `localizedPath(locale, path, options)`: the path of a page in a locale for either routing
+  mode.
+- `fallbackIdentifier` and dotted namespace names: `app.billing.json` is the namespace
+  `app.billing`, compiled as `FALLBACK_APP__BILLING`.
+- CLI `edgekits-i18n`: `--config` and `--wrangler` name the config and the Worker's wrangler
+  config (monorepos); the config's directory is the project root, the wrangler config's the
+  Worker root.
+
+### Fixed
+
+- After a failed KV read the fetcher serves the compiled fallback and no longer writes it to
+  the edge cache (it was cached immutable for a year under the requested locale's URL).
+
+### Changed
+
+- Config validation errors are prefixed `[@edgekits/i18n-core]` (they said
+  `[@edgekits/astro-i18n]`).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gary Stupak
+
+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

@@ -1,3 +1,144 @@
-# Temporary Holding Version
+# @edgekits/i18n-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The EdgeKits edge-native i18n engine, free of any framework. Translations live as data in
+Workers KV, one JSON value per locale and namespace; each namespace is cached at the edge under
+its own URL and purged through the Cloudflare Purge API only when its content changed; the
+default locale's JSON files define a typed schema. After a KV error the compiled fallback is
+served and not cached, so the next request reads KV again. This package holds the config validation,
+the fetcher, locale resolution, the lang cookie, the format helpers and the `edgekits-i18n`
+CLI. A framework adapter builds on it: for Astro, use
+[`@edgekits/astro-i18n`](https://github.com/EdgeKits/i18n/tree/main/packages/astro#readme),
+which depends on this package and needs nothing else from you.
+
+## `createI18n`
+
+One instance per project: your config, the CLI's generated modules, and the platform bindings.
+Every binding is read when a function runs, never when the instance is created, so getters over
+request-scoped values work.
+
+```ts
+import { env, waitUntil } from 'cloudflare:workers'
+import { createI18n, parseBooleanFlag } from '@edgekits/i18n-core'
+
+import config from '../edgekits-i18n.config'
+import * as fallbacks from './i18n/fallbacks.generated'
+import * as runtimeConstants from './i18n/runtime-constants'
+
+export const i18n = createI18n(
+  config,
+  { fallbacks, runtimeConstants },
+  {
+    get kv() {
+      return env.TRANSLATIONS
+    },
+    get cache() {
+      return caches.default ?? null
+    },
+    waitUntil,
+    get cacheEnabled() {
+      return parseBooleanFlag(env.I18N_CACHE, true)
+    },
+    get debug() {
+      return parseBooleanFlag(env.DEBUG_I18N, false)
+    },
+  },
+)
+
+const { common } = await i18n.fetchTranslations('de', ['common'])
+```
+
+The instance also carries the locale constants (`DEFAULT_LOCALE`, `SUPPORTED_LOCALES`, `NAMESPACE_KEYS`,
+`LANGUAGES`), `isLocale`/`parseLocale`, the fallback cascade (`resolveFallbackLocale`), the
+lang-cookie helpers over any `CookieJar`, and the KV key and cache URL builders the CLI shares.
+`routing` in the config is validated here but read by the adapter.
+
+The pure helpers are exported from the root and from `./format` (Node-safe): `fmt`, `plural`,
+`pluralIcu`, `toIetfTag`, and `localizedPath`, the path of a page in a locale for either
+routing mode (a leading locale segment is stripped first; the result ends in a slash):
+
+```ts
+import { localizedPath } from '@edgekits/i18n-core/format'
+
+const options = { routing: 'prefix-except-default', defaultLocale: 'en', isLocale: (s: string) => ['en', 'de'].includes(s) } as const
+
+localizedPath('de', '/about/', options) // '/de/about/'
+localizedPath('en', '/de/about/', options) // '/about/'
+localizedPath('en', '/de/about/', { ...options, routing: 'prefix' }) // '/en/about/'
+```
+
+## CLI
+
+The `edgekits-i18n` command is this package's. It reads `edgekits-i18n.config.ts` and
+`wrangler.jsonc` from the directory it runs in, unless two flags name them:
+
+```sh
+npx edgekits-i18n seed
+```
+
+| Flag                | Default                     | What comes from it                                                                                                                                              |
+| ------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--config <path>`   | `./edgekits-i18n.config.ts` | The config. Its directory is the project root: `localesDir`, `generatedDir`, `i18n-data.json`, `src/i18n.generated.d.ts` and `.i18n-hashes.json` resolve there. |
+| `--wrangler <path>` | `./wrangler.jsonc`          | The `TRANSLATIONS` KV id and the `CLOUDFLARE_ZONE_ID` var. Its directory is the Worker root: `.dev.vars` and the project's wrangler are found there.            |
+
+Both paths resolve against the current directory, and a flag may come before or after the
+command. The CLI always runs wrangler with `--config` set to that file, from its directory, so
+local KV state lands in the `.wrangler/state/` that `wrangler dev` there reads.
+
+| Command                            | Writes                                                                                                              | Then                                                                                                   |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `edgekits-i18n bundle`             | `i18n-data.json` (the KV payload), `src/i18n.generated.d.ts` (the schema), `<generatedDir>/runtime-constants.ts`    | nothing else                                                                                           |
+| `edgekits-i18n bundle --fallbacks` | the above and `<generatedDir>/fallbacks.generated.ts` (the default locale compiled in, served if KV is unreachable) | nothing else                                                                                           |
+| `edgekits-i18n seed`               | the same as `bundle --fallbacks`                                                                                    | pushes every value to local KV (`wrangler kv bulk put --local`)                                        |
+| `edgekits-i18n migrate`            | the same as `bundle --fallbacks`                                                                                    | pushes to production KV, purges the changed namespaces' edge-cache entries, writes `.i18n-hashes.json` |
+
+The generated files are ordinary project files: commit them, and run the CLI again after you
+edit a JSON file.
+
+A namespace is the file name under `<localesDir>/<locale>/`: segments of lowercase letters,
+digits and underscores, joined by single dots, so `locales/en/app.billing.json` is the
+namespace `app.billing`. Its compiled fallback is `FALLBACK_APP__BILLING` (dots become `__`),
+so `app.billing` and `app__billing` cannot both exist; the KV key and cache URL keep the dot.
+
+`.i18n-hashes.json` holds one content hash per namespace and locale as of the last successful
+`migrate`; the next `migrate` purges exactly the entries whose hash changed. Rules:
+
+- Only `migrate` writes it, and only after the purge succeeded (or nothing changed). `seed`
+  never touches it: local KV is not production.
+- Commit it after every `migrate`. It is the record of what production holds.
+- `migrate` refuses to run while the file has uncommitted changes, since a wrong baseline would
+  skip purges silently. When that git check cannot run (no `git` on the PATH, or not a git work
+  tree), `migrate` warns and proceeds without the purge-baseline check.
+
+`migrate` reads the zone ID from `CLOUDFLARE_ZONE_ID` (a var in `wrangler.jsonc` or the
+environment) and the token from `CLOUDFLARE_CACHEPURGE_API_TOKEN` (the environment or
+`.dev.vars`). Without either, it still pushes to KV but skips the purge and leaves
+`.i18n-hashes.json` alone, so the next run retries.
+
+### Monorepo: one translations folder, several Workers
+
+```text
+packages/i18n/        edgekits-i18n.config.ts, locales/, the generated files, .i18n-hashes.json
+apps/app/             wrangler.jsonc (+ .dev.vars)
+apps/admin/           wrangler.jsonc (+ .dev.vars)
+```
+
+- `packages/i18n/` holds the config, `locales/` and the generated files; each app imports them
+  from there.
+- Every app's `wrangler.jsonc` binds the same `TRANSLATIONS` namespace and sets the same
+  `CLOUDFLARE_ZONE_ID`.
+- Run one `migrate` per change, from the repository root, with any one app's wrangler config:
+
+  ```sh
+  npx edgekits-i18n migrate --config packages/i18n/edgekits-i18n.config.ts --wrangler apps/app/wrangler.jsonc
+  ```
+
+  It pushes once to the shared namespace and purges once: the cache URLs live on the zone, so
+  the purge reaches every host on it.
+
+- `.i18n-hashes.json` lives next to the config; commit it there.
+- `seed` takes the same flags. Local KV state belongs to the app whose wrangler config you pass,
+  so seed once per app you run `wrangler dev` in.
+
+## License
+
+MIT © Gary Stupak. See [LICENSE](LICENSE).

package/dist/accept-language.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The Accept-Language step of the middleware's fallback cascade, read from the header
+ * itself. Astro's own match is no substitute: it keeps only the tags that equal a
+ * configured locale before choosing, so a regional tag (`es-MX`) never reaches a
+ * language-part match. Pure: no Astro, no virtual module, no `cloudflare:`.
+ */
+export type AcceptLanguageEntry = {
+    tag: string;
+    q: number;
+};
+/**
+ * The header's language ranges, highest `q` first (header order among equals). A missing
+ * or unparsable `q` is 1; `q=0` entries and the `*` wildcard are dropped.
+ */
+export declare function parseAcceptLanguage(header: string | null): AcceptLanguageEntry[];
+/**
+ * The first supported locale the header names: for each tag in `q` order, the full tag
+ * (lowercased), then its language subtag (before the first `-` or `_`). Null when none.
+ */
+export declare function matchAcceptLanguage<L extends string>(header: string | null, parseLocale: (value: unknown) => L | null): L | null;

package/dist/accept-language.js

@@ -0,0 +1,51 @@
+/**
+ * The Accept-Language step of the middleware's fallback cascade, read from the header
+ * itself. Astro's own match is no substitute: it keeps only the tags that equal a
+ * configured locale before choosing, so a regional tag (`es-MX`) never reaches a
+ * language-part match. Pure: no Astro, no virtual module, no `cloudflare:`.
+ */
+/**
+ * The header's language ranges, highest `q` first (header order among equals). A missing
+ * or unparsable `q` is 1; `q=0` entries and the `*` wildcard are dropped.
+ */
+export function parseAcceptLanguage(header) {
+    if (!header)
+        return [];
+    const entries = [];
+    for (const part of header.split(',')) {
+        const [rawTag = '', ...params] = part.split(';');
+        const tag = rawTag.trim();
+        if (!tag || tag === '*')
+            continue;
+        let q = 1;
+        for (const param of params) {
+            const [name, value] = param.split('=').map((s) => s.trim());
+            if (name?.toLowerCase() !== 'q' || value === undefined)
+                continue;
+            const parsed = Number.parseFloat(value);
+            if (!Number.isNaN(parsed))
+                q = parsed;
+        }
+        if (q <= 0)
+            continue;
+        entries.push({ tag, q });
+    }
+    // Array.prototype.sort is stable: equal q keeps header order.
+    return entries.sort((a, b) => b.q - a.q);
+}
+/**
+ * The first supported locale the header names: for each tag in `q` order, the full tag
+ * (lowercased), then its language subtag (before the first `-` or `_`). Null when none.
+ */
+export function matchAcceptLanguage(header, parseLocale) {
+    for (const { tag } of parseAcceptLanguage(header)) {
+        const lower = tag.toLowerCase();
+        const full = parseLocale(lower);
+        if (full)
+            return full;
+        const language = parseLocale(lower.split(/[-_]/)[0]);
+        if (language)
+            return language;
+    }
+    return null;
+}

package/dist/assemble.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Assemble a single translation namespace from a raw value and its compiled
+ * fallback dictionary.
+ *
+ * This is the ONLY place namespace assembly happens: `fetchTranslations` routes
+ * its cache-HIT branch, its cache-miss/KV branch and `fetchAllFromKV` through it,
+ * so a cached namespace and a freshly read one can never diverge in shape.
+ *
+ * Semantics (unchanged from the original miss path):
+ *   - the fallback provides the full known key set,
+ *   - the raw value (cached entry or KV read) overrides it wherever it has a value,
+ *   - `null` / `undefined` are tolerated for either argument.
+ *
+ * Consequence for stale cache entries: a namespace cached before a schema addition
+ * degrades to default-locale text for the keys it predates instead of handing pages
+ * `undefined` (see ADR-0014 and the 2026-07-18 `/en/blog/` incident).
+ *
+ * Deliberately pure — no `cloudflare:workers` imports, so it is testable under
+ * plain Node (`npm test`).
+ */
+export declare function assembleNamespace(rawValue: unknown, fallback: unknown): object;

package/dist/assemble.js

@@ -0,0 +1,27 @@
+import { deepMerge } from "./deep-merge.js";
+/**
+ * Assemble a single translation namespace from a raw value and its compiled
+ * fallback dictionary.
+ *
+ * This is the ONLY place namespace assembly happens: `fetchTranslations` routes
+ * its cache-HIT branch, its cache-miss/KV branch and `fetchAllFromKV` through it,
+ * so a cached namespace and a freshly read one can never diverge in shape.
+ *
+ * Semantics (unchanged from the original miss path):
+ *   - the fallback provides the full known key set,
+ *   - the raw value (cached entry or KV read) overrides it wherever it has a value,
+ *   - `null` / `undefined` are tolerated for either argument.
+ *
+ * Consequence for stale cache entries: a namespace cached before a schema addition
+ * degrades to default-locale text for the keys it predates instead of handing pages
+ * `undefined` (see ADR-0014 and the 2026-07-18 `/en/blog/` incident).
+ *
+ * Deliberately pure — no `cloudflare:workers` imports, so it is testable under
+ * plain Node (`npm test`).
+ */
+export function assembleNamespace(rawValue, fallback) {
+    const raw = rawValue ?? {};
+    if (!fallback)
+        return raw;
+    return deepMerge(fallback, raw);
+}

package/dist/cli/generate.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The CLI's code generation, as pure functions of the collected locale tree: no
+ * filesystem, so the emitted text is testable. Formats are those of the site's
+ * `scripts/bundle-translations.ts`, header aside.
+ */
+export type TranslationTree = Record<string, unknown>;
+export type CollectedData = Record<string, Record<string, TranslationTree>>;
+export type KvBulkEntry = {
+    key: string;
+    value: string;
+};
+export declare const NAMESPACE_NAME: RegExp;
+/**
+ * Throws, naming the offender, when a locale folder is not one of the config's
+ * `languages`, a namespace file name does not match NAMESPACE_NAME, or two namespaces
+ * compile to the same fallback identifier (`app.billing` and `app__billing`). Run on the
+ * collected tree before anything is generated or pushed.
+ */
+export declare function assertValidNames(collected: CollectedData, languages: Readonly<Record<string, unknown>>): void;
+/**
+ * A single-quoted TS string literal, escaped by JSON.stringify. For every name the
+ * validation accepts it is byte-identical to the plain `'name'` the CLI always wrote, so
+ * existing generated files do not change; anything else comes out escaped, not injected.
+ */
+export declare function quoteString(value: string): string;
+/** Locales that have at least one namespace, sorted. */
+export declare function localesWithTranslations(collected: CollectedData): string[];
+/**
+ * The locale the schema and the namespace list are derived from: the default locale
+ * when it has translations, otherwise the first locale that does.
+ */
+export declare function schemaSourceLocale(collected: CollectedData, defaultLocale: string): string | undefined;
+/** `wrangler kv bulk put` input: one entry per locale and namespace. */
+export declare function buildBulkData(collected: CollectedData, keyPrefix: string): KvBulkEntry[];
+/**
+ * `src/i18n.generated.d.ts`: the global `I18n.Schema`, from the schema source locale.
+ * Throws, naming the key, when an array in it mixes kinds of elements.
+ */
+export declare function buildTypesContent(collected: CollectedData, defaultLocale: string): string;
+/**
+ * `runtime-constants.ts`:
+ *   - NAMESPACE_KEYS            -> from the schema source locale (default locale preferred)
+ *   - LOCALES_WITH_TRANSLATIONS -> from all collected locales
+ *   - FULLY_TRANSLATED_LOCALES  -> locales that have ALL namespace keys
+ */
+export declare function buildRuntimeConstantsContent(collected: CollectedData, defaultLocale: string): string;
+/**
+ * `fallbacks.generated.ts`: one `FALLBACK_<NAMESPACE>` (`fallbackIdentifier`) per
+ * default-locale namespace.
+ * Null when the default locale has no translations (nothing to fall back to).
+ */
+export declare function buildFallbacksContent(collected: CollectedData, defaultLocale: string): string | null;

package/dist/cli/generate.js

@@ -0,0 +1,171 @@
+import { fallbackIdentifier, formatTranslationKvKey } from "../key-format.js";
+const HEADER = `// Auto-generated by @edgekits/astro-i18n (edgekits-i18n CLI)
+// Do not edit manually.
+`;
+// A namespace becomes part of a KV key, a cache URL and (dots as `__`) the
+// `FALLBACK_<NAMESPACE>` identifier, so its file name is restricted to what is valid in
+// all three: segments of [a-z0-9_], joined by single dots (`app.billing`).
+export const NAMESPACE_NAME = /^[a-z0-9][a-z0-9_]*(\.[a-z0-9][a-z0-9_]*)*$/;
+/**
+ * Throws, naming the offender, when a locale folder is not one of the config's
+ * `languages`, a namespace file name does not match NAMESPACE_NAME, or two namespaces
+ * compile to the same fallback identifier (`app.billing` and `app__billing`). Run on the
+ * collected tree before anything is generated or pushed.
+ */
+export function assertValidNames(collected, languages) {
+    const configured = Object.keys(languages);
+    for (const [locale, namespaces] of Object.entries(collected)) {
+        if (!configured.includes(locale)) {
+            throw new Error(`Locale folder "${locale}" is not one of \`languages\` in edgekits-i18n.config.ts: ${configured.join(', ')}.`);
+        }
+        const identifiers = new Map();
+        for (const ns of Object.keys(namespaces)) {
+            if (!NAMESPACE_NAME.test(ns)) {
+                throw new Error(`Namespace "${ns}" (${locale}/${ns}.json) must match ${NAMESPACE_NAME}: ` +
+                    'segments of lowercase letters, digits and underscores, joined by single dots.');
+            }
+            const identifier = fallbackIdentifier(ns);
+            const other = identifiers.get(identifier);
+            if (other !== undefined) {
+                throw new Error(`Namespaces "${other}" (${locale}/${other}.json) and "${ns}" (${locale}/${ns}.json) ` +
+                    `both compile to ${identifier}. Rename one of them.`);
+            }
+            identifiers.set(identifier, ns);
+        }
+    }
+}
+/**
+ * A single-quoted TS string literal, escaped by JSON.stringify. For every name the
+ * validation accepts it is byte-identical to the plain `'name'` the CLI always wrote, so
+ * existing generated files do not change; anything else comes out escaped, not injected.
+ */
+export function quoteString(value) {
+    const escaped = JSON.stringify(value).slice(1, -1).replace(/\\"/g, '"').replace(/'/g, "\\'");
+    return `'${escaped}'`;
+}
+/** Locales that have at least one namespace, sorted. */
+export function localesWithTranslations(collected) {
+    return Object.keys(collected).sort();
+}
+/**
+ * The locale the schema and the namespace list are derived from: the default locale
+ * when it has translations, otherwise the first locale that does.
+ */
+export function schemaSourceLocale(collected, defaultLocale) {
+    if (collected[defaultLocale])
+        return defaultLocale;
+    return localesWithTranslations(collected)[0];
+}
+/** `wrangler kv bulk put` input: one entry per locale and namespace. */
+export function buildBulkData(collected, keyPrefix) {
+    const bulkData = [];
+    for (const [locale, namespaces] of Object.entries(collected)) {
+        for (const [ns, json] of Object.entries(namespaces)) {
+            bulkData.push({ key: formatTranslationKvKey(keyPrefix, locale, ns), value: JSON.stringify(json) });
+        }
+    }
+    return bulkData;
+}
+function isTree(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+// The JSON kind of an array element; an array is typed only when all its elements share one.
+function jsonKind(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+/**
+ * The TS type of one JSON value. Objects become object types; arrays become `string[]`
+ * (strings, other scalars, or empty) or `Array<…>` typed from their first element
+ * (objects, nested arrays); every other leaf stays `string`. `keyPath` and `file` name the
+ * value in the error a mixed array raises.
+ */
+function generateSchemaTs(value, indent, keyPath, file) {
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return 'string[]';
+        const kinds = [...new Set(value.map(jsonKind))];
+        if (kinds.length > 1) {
+            throw new Error(`Key "${keyPath}" (${file}) is an array that mixes ${kinds.join(', ')} elements: ` +
+                'I18n.Schema cannot type it. Use one kind of element per array.');
+        }
+        const first = value[0];
+        if (!isTree(first) && !Array.isArray(first))
+            return 'string[]';
+        return `Array<${generateSchemaTs(first, indent, `${keyPath}[0]`, file)}>`;
+    }
+    if (!isTree(value))
+        return 'string';
+    const entries = Object.entries(value);
+    if (entries.length === 0)
+        return '{}';
+    const pad = ' '.repeat(indent);
+    const padInner = ' '.repeat(indent + 2);
+    const lines = entries.map(([key, child]) => `${padInner}${JSON.stringify(key)}: ${generateSchemaTs(child, indent + 2, `${keyPath}.${key}`, file)}`);
+    return `{\n${lines.join(';\n')};\n${pad}}`;
+}
+/**
+ * `src/i18n.generated.d.ts`: the global `I18n.Schema`, from the schema source locale.
+ * Throws, naming the key, when an array in it mixes kinds of elements.
+ */
+export function buildTypesContent(collected, defaultLocale) {
+    const source = schemaSourceLocale(collected, defaultLocale);
+    const schemaObject = (source && collected[source]) || {};
+    const namespaceLines = Object.entries(schemaObject).map(([ns, value]) => {
+        const valueTs = generateSchemaTs(value, 10, ns, `${source}/${ns}.json`);
+        return `      ${JSON.stringify(ns)}: ${valueTs}`;
+    });
+    const interfaceBody = namespaceLines.length > 0
+        ? `    export interface Schema {\n${namespaceLines.join(';\n')};\n    }`
+        : `    export interface Schema {}`;
+    return `${HEADER}
+declare global {
+  namespace I18n {
+${interfaceBody}
+  }
+}
+
+export {}
+`;
+}
+/**
+ * `runtime-constants.ts`:
+ *   - NAMESPACE_KEYS            -> from the schema source locale (default locale preferred)
+ *   - LOCALES_WITH_TRANSLATIONS -> from all collected locales
+ *   - FULLY_TRANSLATED_LOCALES  -> locales that have ALL namespace keys
+ */
+export function buildRuntimeConstantsContent(collected, defaultLocale) {
+    const source = schemaSourceLocale(collected, defaultLocale);
+    const namespaceKeys = Object.keys((source && collected[source]) || {}).sort();
+    const locales = localesWithTranslations(collected);
+    const fullyTranslatedLocales = locales.filter((locale) => {
+        const localeNamespaces = Object.keys(collected[locale] || {});
+        return namespaceKeys.every((ns) => localeNamespaces.includes(ns));
+    });
+    return `${HEADER}
+export const NAMESPACE_KEYS = [${namespaceKeys.map(quoteString).join(', ')}] as [string, ...string[]];
+
+export const LOCALES_WITH_TRANSLATIONS = [${locales.map(quoteString).join(', ')}] as const;
+
+export const FULLY_TRANSLATED_LOCALES = [${fullyTranslatedLocales.map(quoteString).join(', ')}] as const;
+`;
+}
+/**
+ * `fallbacks.generated.ts`: one `FALLBACK_<NAMESPACE>` (`fallbackIdentifier`) per
+ * default-locale namespace.
+ * Null when the default locale has no translations (nothing to fall back to).
+ */
+export function buildFallbacksContent(collected, defaultLocale) {
+    const fallbackNamespaces = collected[defaultLocale];
+    if (!fallbackNamespaces)
+        return null;
+    const lines = [HEADER];
+    lines.push(`export const FALLBACK_LOCALE = ${JSON.stringify(defaultLocale)} as const;\n`);
+    for (const [ns, json] of Object.entries(fallbackNamespaces)) {
+        lines.push(`export const ${fallbackIdentifier(ns)} = ${JSON.stringify(json, null, 2)} as const;\n`);
+    }
+    return lines.join('\n');
+}

package/dist/cli/hashes.d.ts

@@ -0,0 +1,19 @@
+import type { CollectedData } from './generate.ts';
+/**
+ * Per-namespace content hashes and the change diff that drives the cache purge.
+ * Pure apart from hashing. Same algorithm as the site's `scripts/bundle-translations.ts`,
+ * so an existing `.i18n-hashes.json` stays a valid baseline.
+ */
+export type HashMap = Record<string, string>;
+export declare function stableStringify(value: unknown): string;
+export declare function computeHash(value: unknown): string;
+/**
+ * Hash every collected namespace and list the "<locale>:<namespace>" pairs whose hash
+ * differs from the previous run (all of them when there is no previous run).
+ */
+export declare function diffHashes(collected: CollectedData, previousHashes: HashMap): {
+    currentHashes: HashMap;
+    changedKeys: string[];
+};
+/** Purge API URLs for the changed "<locale>:<namespace>" pairs. */
+export declare function purgeUrlsFor(changedKeys: readonly string[], keyPrefix: string): string[];

package/dist/cli/hashes.js

@@ -0,0 +1,42 @@
+import crypto from 'node:crypto';
+import { formatTranslationCacheUrl } from "../key-format.js";
+export function stableStringify(value) {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return '[' + value.map(stableStringify).join(',') + ']';
+    }
+    const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
+    return '{' + entries.map(([k, v]) => JSON.stringify(k) + ':' + stableStringify(v)).join(',') + '}';
+}
+export function computeHash(value) {
+    const json = stableStringify(value);
+    return crypto.createHash('sha256').update(json).digest('hex').slice(0, 12);
+}
+/**
+ * Hash every collected namespace and list the "<locale>:<namespace>" pairs whose hash
+ * differs from the previous run (all of them when there is no previous run).
+ */
+export function diffHashes(collected, previousHashes) {
+    const currentHashes = {};
+    const changedKeys = [];
+    for (const [locale, namespaces] of Object.entries(collected)) {
+        for (const [ns, json] of Object.entries(namespaces)) {
+            const hashKey = `${locale}:${ns}`;
+            const hash = computeHash(json);
+            currentHashes[hashKey] = hash;
+            if (previousHashes[hashKey] !== hash) {
+                changedKeys.push(hashKey);
+            }
+        }
+    }
+    return { currentHashes, changedKeys };
+}
+/** Purge API URLs for the changed "<locale>:<namespace>" pairs. */
+export function purgeUrlsFor(changedKeys, keyPrefix) {
+    return changedKeys.map((hashKey) => {
+        const [locale, ns] = hashKey.split(':');
+        return formatTranslationCacheUrl(keyPrefix, locale, ns);
+    });
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};