@edgekits/i18n-core 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,57 @@ 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.3.0 — 2026-10-28
+
+### Upgrading from 0.2.x
+
+- **`.i18n-hashes.json` changes shape.** It now holds one baseline per KV namespace id (`{ "<kvId>": { "<locale>:<ns>": "<hash>" } }`). An old flat file is the baseline of the top-level `TRANSLATIONS` id (what 0.2.x wrote), whichever environment migrates first, and is rewritten in the new shape. Commit it as before.
+- **The edge cache starts cold once.** Cache URLs carry the entry format (`https://<keyPrefix>/i18n:v2:<locale>:<ns>`, encoded); 0.2.x entries are never read again and expire on their own. Expect one KV read per namespace and data center right after the deploy.
+- **`migrate` takes about a minute longer and can exit 1.** It purges, waits `--purge-delay` seconds (default 65) for KV to settle, and purges the same URLs again. It exits 1 when KV was updated but the edge cache was not purged (no `CLOUDFLARE_ZONE_ID` or token, or a failed purge); `.i18n-hashes.json` is then not written and the next run retries. A CI step that passed without purge credentials now fails.
+- **Regenerate and commit the generated files** (`npx edgekits-i18n bundle --fallbacks`, or `seed`). `I18n.Schema` types numbers and booleans as such and a list of objects as one merged object type (a key every element has is required, any other optional, a key of differing types a union); a list that mixes strings and objects stops the run. A `null` value and a namespace named `locale` are rejected. Hashes of namespaces with mixed-case keys change once (code-point key order), so the first `migrate` purges those namespaces too.
+- **`keyPrefix` must be a plain lower-case host** (`example.com`, `my-site`): no scheme, path, port syntax, space or upper case. `defineI18nConfig` throws otherwise.
+- **The CLI is stricter.** An unknown argument (`-e staging`) exits 1 naming it; `--purge-delay` is at most 600; `CLOUDFLARE_ZONE_ID` must be 32 hex characters. With `--env <name>`, `.dev.vars.<name>` replaces `.dev.vars` when it exists, as in wrangler. `migrate` compares only the baseline of the KV namespace it writes with the committed file, so `migrate --env staging && migrate` runs in one job.
+- **Node `>=22.23.4`.**
+
+### Changed
+
+- The fetcher caches the raw KV value of each namespace, never the merged namespace, marks each entry `X-EdgeKits-I18n: v2` (a response at the URL without it is a miss), and merges the current compiled fallback on every read; a key KV does not have is cached as a `null` marker with `s-maxage=60`; cache URLs are `https://<keyPrefix>/<encodeURIComponent(i18n:v2:<locale>:<ns>)>`.
+- KV bulk reads take at most 100 keys at a time, in parallel; a failing read falls back for its own namespaces only.
+- `migrate` purges twice, `--purge-delay` seconds apart (default 65), writes `.i18n-hashes.json` only after both, and exits 1 when the purge was skipped or failed.
+- `.i18n-hashes.json` holds one baseline per KV namespace id; the old flat shape is the top-level id's baseline, read and rewritten. `migrate` refuses to run only while that KV namespace's baseline differs from the committed file (`HEAD`).
+- `seed` writes the `TRANSLATIONS` binding's `preview_id` when it has one (what `wrangler dev` reads); `migrate` writes its `id`.
+- `I18n.Schema` types numbers and booleans as such, and a list of objects as one object type merged from its elements.
+- Content hashes sort keys by code point (the same on every machine) instead of `localeCompare`; locales and namespaces are read in code point order.
+- CLI arguments are checked: anything but the command, `--fallbacks`, `--purge-all`, `--help` and the value flags exits 1; `--purge-delay` is at most 600; `CLOUDFLARE_ZONE_ID` must be 32 hex characters.
+- With `--env <name>`, `migrate` reads `.dev.vars.<name>` instead of `.dev.vars` when it exists.
+- `localizedPath` keeps a file path without a trailing slash and keeps a `?query`/`#hash`; `toIetfTag` cases each subtag by length; `plural` interpolates both forms.
+- `engines.node` `>=22.23.4`.
+
+### Added
+
+- CLI `--purge-delay <seconds>` and `--env <name>` (the binding and `CLOUDFLARE_ZONE_ID` from `env.<name>`; wrangler gets `--env`); without `--env`, a warning when an environment binds `TRANSLATIONS` to another id.
+- `migrate` deletes the KV keys of translation files removed since the last run (`wrangler kv bulk delete`) and purges their URLs.
+- Warnings for a namespace only non-default locales have, keys the default locale lacks, and JSON files in subfolders of a locale folder.
+- `isFilePath`, from the root and `./format`.
+- `migrate --purge-all`: purge every namespace's URLs whatever the baseline says (after a `git revert` of translations).
+- A warning when two wrangler environments put different `TRANSLATIONS` namespaces on one `CLOUDFLARE_ZONE_ID` (they share cache URLs under one `keyPrefix`).
+
+### Fixed
+
+- `.dev.vars` is read with dotenv syntax (`util.parseEnv`: quotes, `export `, inline `#` comments).
+- A translation file with a BOM is read; an empty or invalid one stops the run naming `<localesDir>/<locale>/<file>`.
+- A namespace named `locale` is rejected (its fallback collided with `FALLBACK_LOCALE`); a `null` value is rejected with its key path.
+- `defineI18nConfig` rejects a `keyPrefix` that is not a URL host as written.
+- A translated value under a `constructor` or `prototype` key was dropped by the fallback merge.
+- A namespace a page mutated changed the compiled fallback for every later request in the isolate; each call now returns its own copy (`structuredClone`).
+- `cache.put` got a clone of the entry's Response, and the original was never read.
+- `localizedPath` treats `\` as a segment separator and drops tabs and newlines, as the URL parser does: a decoded `/\evil.com/` gives `/evil.com/`, never a protocol-relative path.
+- `migrate --env staging` on a 0.2.x flat baseline read it as staging's and dropped it, so production never deleted its removed keys.
+
+## 0.2.2 — 2026-10-27
+
+No changes; released in lockstep.
+
 ## 0.2.1 — 2026-10-27
 
 No changes; released in lockstep with the plugin rename (see `@edgekits/astro-i18n` 0.2.1).

package/README.md

@@ -1,15 +1,21 @@
 # @edgekits/i18n-core
 
 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,
+Workers KV, one JSON value per locale and namespace; each namespace's KV value is cached at the
+edge under its own URL (merged with the compiled fallback on every read) and purged through the
+Cloudflare Purge API only when its content changed; a namespace KV does not have is cached as
+missing for 60 seconds; the default locale's JSON files define a typed schema. Each cache entry
+carries `X-EdgeKits-I18n: v2`; a response at that URL without it is a miss, read from KV again
+and replaced. After a KV error the compiled fallback is served and not cached, so the next
+request reads KV again. Every namespace a call returns is its own copy: mutating it never
+changes the next request's text. 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.
 
+Requires Node `>=22.23.4` (the CLI runs under it; the engine itself runs in workerd).
+
 ## `createI18n`
 
 One instance per project: your config, the CLI's generated modules, and the platform bindings.
@@ -44,17 +50,33 @@ export const i18n = createI18n(
   },
 )
 
-const { common } = await i18n.fetchTranslations('de', ['common'])
+export default {
+  async fetch(request: Request): Promise<Response> {
+    // Inside a request, never at module scope: on Workers, `env` and the edge cache belong
+    // to the request.
+    const { common } = await i18n.fetchTranslations('de', ['common'])
+    return Response.json(common)
+  },
+}
 ```
 
+The edge cache URL's host is `keyPrefix` (`https://<keyPrefix>/…`) and the cache is per zone: two
+Workers on one zone that read different KV namespaces (production and staging, say) need
+different `keyPrefix` values, or each serves the other's cached translations.
+
 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):
+The pure helpers are exported from the root and from `./format` (Node-safe): `fmt`, `plural`
+(both forms interpolate `{count}`), `pluralIcu`, `toIetfTag` (`zh-hant-tw` -> `zh-Hant-TW`),
+`isFilePath`, 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, except for a file path
+(`isFilePath`: the last segment ends in an extension that starts with a letter, `/rss.xml`, not
+`/blog/v2.0`); a `?query` and a `#hash` in the input are kept after the path. Segments are
+read as a URL parser reads an https path (`\` separates them like `/`, a tab or newline is
+dropped), so a decoded `/\evil.com/` gives `/evil.com/` and no result starts with `//`:
 
 ```ts
 import { localizedPath } from '@edgekits/i18n-core/format'
@@ -64,55 +86,119 @@ const options = { routing: 'prefix-except-default', defaultLocale: 'en', isLocal
 localizedPath('de', '/about/', options) // '/de/about/'
 localizedPath('en', '/de/about/', options) // '/about/'
 localizedPath('en', '/de/about/', { ...options, routing: 'prefix' }) // '/en/about/'
+localizedPath('de', '/rss.xml', options) // '/de/rss.xml'
+localizedPath('de', '/about/?x=1#top', options) // '/de/about/?x=1#top'
 ```
 
 ## 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:
+`wrangler.jsonc` from the directory it runs in, unless 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.            |
+| 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 binding and the `CLOUDFLARE_ZONE_ID` var. Its directory is the Worker root: `.dev.vars` and the project's wrangler are found there.                                                                                                                   |
+| `--env <name>`            | none (the top level)        | The `TRANSLATIONS` binding and `CLOUDFLARE_ZONE_ID` from `env.<name>` of the wrangler config (wrangler does not inherit them into an environment); wrangler itself gets `--env <name>`; `.dev.vars.<name>` is read instead of `.dev.vars` when it exists, as wrangler does. |
+| `--purge-delay <seconds>` | `65`                        | `migrate`: the wait between its two purges (below), `0` to `600`. `0` purges once.                                                                                                                                                                                          |
+| `--purge-all`             | off                         | `migrate`: purge every namespace's cache URLs, changed or not (after a `git revert` of translations, below).                                                                                                                                                                |
+| `--fallbacks`             | off                         | `bundle`: also write `<generatedDir>/fallbacks.generated.ts`.                                                                                                                                                                                                               |
 
-Both paths resolve against the current directory, and a flag may come before or after the
+The 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` |
+local KV state lands in the `.wrangler/state/` that `wrangler dev` there reads. Without `--env`,
+when an `env.<name>` binds `TRANSLATIONS` to another id, the CLI warns once, naming those
+environments. Any other argument (`-e staging`, a second command) exits `1`, naming it.
+
+Two environments on one zone that bind different KV namespaces share cache URLs when they share
+the `keyPrefix`: each `migrate` would purge, and each Worker cache, the other's entries. Give
+each environment its own `keyPrefix` (a config per environment, `--config`); `migrate` warns
+when the wrangler config puts two such environments on one `CLOUDFLARE_ZONE_ID`.
+
+| 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 remote KV, deletes the keys of removed files, purges the changed and removed namespaces' edge-cache entries twice, writes `.i18n-hashes.json` |
+
+`seed` writes the `TRANSLATIONS` binding's `preview_id` when it has one (the namespace
+`wrangler dev` reads), otherwise its `id`; `migrate` always writes the `id`. `seed` only adds
+and overwrites: after you delete a translation file, wipe `.wrangler/state` (or delete the key
+with `wrangler kv key delete --local`) so local KV stops serving it.
 
 The generated files are ordinary project files: commit them, and run the CLI again after you
-edit a JSON file.
+edit a JSON file. Locales and namespaces are read in code point order, so the files come out
+the same on every machine.
 
 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.
+The name `locale` is reserved: the fallbacks file already exports `FALLBACK_LOCALE`.
+
+The files are read as JSON (a leading BOM is ignored). A file that is empty or not JSON, or a
+`null` value anywhere (it would replace the default locale's text with `null`), stops the run
+with the file and key path; JSON files in subfolders of a locale folder are ignored with a
+warning. In `I18n.Schema`, leaves are `string`, `number` or `boolean` as in the default locale's
+JSON; a list of objects is one object type merged from its elements: a key every element has is
+required, any other optional (`?:`), and a key whose type differs between elements a union. A
+list that mixes kinds of elements (strings and objects) stops the run, naming the key path and
+the file, as a `null` does. The CLI warns about a namespace
+that only non-default locales have, and about keys a locale has that the default locale lacks
+(neither is typed).
+
+`keyPrefix` must be a URL host as written: lowercase, no scheme, path or space: the project's
+own domain (`www.my-site.com`) or a dotless name (`my-site`), never a host you do not own. It is the host of every edge-cache URL, so `defineI18nConfig` rejects anything else.
+
+`.i18n-hashes.json` holds, per KV namespace id, one content hash per namespace and locale as of
+the last successful `migrate` against that namespace:
+
+```json
+{ "<kvId>": { "en:common": "5c924960820d", "de:common": "…" } }
+```
 
-`.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.
+The next `migrate` purges exactly the entries whose hash changed. A file in the pre-0.3 flat
+shape (`{ "en:common": "…" }`) is what 0.2.x wrote for the top-level `TRANSLATIONS` id: it is
+that id's baseline whichever environment migrates first, and it stays that id's when another id
+is written next to it. Rules:
+
+- Only `migrate` writes it, and only after both purges succeeded (or nothing changed). `seed`
+  never touches it: local KV is not remote KV.
+- Commit it after every `migrate`. It is the record of what each remote namespace holds; with
+  `--env`, staging and production keep separate baselines in the one file.
+- `migrate` refuses to run while the baseline of the KV namespace it writes differs from the
+  one in the committed file (`git show HEAD:.i18n-hashes.json`), since a wrong baseline would
+  skip purges silently. Only that namespace's entry counts, so `migrate --env staging &&
+migrate` in one job works. When the git check cannot run (no `git` on the PATH, or not a git
+  work tree), `migrate` warns and proceeds without it.
+- A `git revert` of translations reverts the baseline with them, so the next `migrate` sees no
+  change and purges nothing while the edge still holds the reverted text. Run
+  `migrate --purge-all`: it purges every namespace's URLs whatever the baseline says.
+
+A translation file removed since the last `migrate` (a `de/pricing.json` in the baseline but no
+longer on disk): `migrate` lists its KV key, deletes it (`wrangler kv bulk delete --force`, the
+same id, config and `--env`), and purges its cache URL with the others.
+
+`migrate` purges, waits `--purge-delay` seconds (65 by default), and purges the same URLs again:
+KV can take up to 60 s to show a write in other locations, and a request there in that window
+would cache the old value again for a year.
+
+`migrate` reads the zone ID from `CLOUDFLARE_ZONE_ID` (a var in `wrangler.jsonc`, or in
+`env.<name>` with `--env`, or the environment) and the token from
+`CLOUDFLARE_CACHEPURGE_API_TOKEN` (the environment or `.dev.vars`, read with dotenv syntax:
+quotes, `export ` and `#` comments; with `--env <name>`, `.dev.vars.<name>` when it exists). The
+zone ID must be 32 hex characters: from the wrangler config it is checked before anything is
+written, from the environment at the purge.
+
+Exit status: `0` on success, `1` on any error. `migrate` also exits `1` after the KV push when
+the edge cache was not purged: no zone ID or token (or a malformed zone ID), a failed delete of
+the removed files' keys, or a failed purge (either round). The message says so,
+`.i18n-hashes.json` is left alone, and the next run retries the same deletions and purge.
 
 ### Monorepo: one translations folder, several Workers
 
@@ -125,7 +211,7 @@ 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`.
+  `CLOUDFLARE_ZONE_ID` (or the same per `env.<name>`, used with `--env <name>`).
 - Run one `migrate` per change, from the repository root, with any one app's wrangler config:
 
   ```sh

package/dist/assemble.d.ts

@@ -15,6 +15,11 @@
  * 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).
  *
+ * The result is the caller's own: the fallback is a module-level object shared by every
+ * request in the isolate, so it is deep-copied first (`structuredClone`; deepMerge copies
+ * only the levels the raw value overrides). A page that mutates what it was handed never
+ * changes the next request's text.
+ *
  * Deliberately pure — no `cloudflare:workers` imports, so it is testable under
  * plain Node (`npm test`).
  */

package/dist/assemble.js

@@ -16,6 +16,11 @@ import { deepMerge } from "./deep-merge.js";
  * 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).
  *
+ * The result is the caller's own: the fallback is a module-level object shared by every
+ * request in the isolate, so it is deep-copied first (`structuredClone`; deepMerge copies
+ * only the levels the raw value overrides). A page that mutates what it was handed never
+ * changes the next request's text.
+ *
  * Deliberately pure — no `cloudflare:workers` imports, so it is testable under
  * plain Node (`npm test`).
  */
@@ -23,5 +28,5 @@ export function assembleNamespace(rawValue, fallback) {
     const raw = rawValue ?? {};
     if (!fallback)
         return raw;
-    return deepMerge(fallback, raw);
+    return deepMerge(structuredClone(fallback), raw);
 }

package/dist/cli/collect.d.ts

@@ -0,0 +1,13 @@
+import type { CollectedData } from './generate.ts';
+/**
+ * Read `<localesDir>/<locale>/<namespace>.json` into the collected tree. A locale is a
+ * folder of `localesDir` with at least one JSON file directly in it; JSON files in its
+ * subfolders are not read and come back in `ignored`. Locales and namespaces are inserted
+ * sorted by code point, so the generated files and the KV bulk data come out the same on
+ * every machine. Throws, naming the file through `display`, on a file that is empty or not
+ * JSON (a leading BOM is stripped first).
+ */
+export declare function collectTranslations(localesDir: string, display: (file: string) => string): {
+    collected: CollectedData;
+    ignored: string[];
+};

package/dist/cli/collect.js

@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import path from 'node:path';
+// Code point order: the same on every machine, whatever the file system lists first.
+const byCodePoint = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/**
+ * Read `<localesDir>/<locale>/<namespace>.json` into the collected tree. A locale is a
+ * folder of `localesDir` with at least one JSON file directly in it; JSON files in its
+ * subfolders are not read and come back in `ignored`. Locales and namespaces are inserted
+ * sorted by code point, so the generated files and the KV bulk data come out the same on
+ * every machine. Throws, naming the file through `display`, on a file that is empty or not
+ * JSON (a leading BOM is stripped first).
+ */
+export function collectTranslations(localesDir, display) {
+    const collected = {};
+    const ignored = [];
+    const localeDirs = fs
+        .readdirSync(localesDir, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name)
+        .sort(byCodePoint);
+    for (const locale of localeDirs) {
+        const localeDir = path.join(localesDir, locale);
+        // Namespace names (not file names: `a-b.json` sorts before `a.json`, `a` before `a-b`).
+        const entries = fs
+            .readdirSync(localeDir, { withFileTypes: true, recursive: true })
+            .sort((a, b) => byCodePoint(path.basename(a.name, '.json'), path.basename(b.name, '.json')));
+        for (const entry of entries) {
+            if (!entry.isFile() || !entry.name.endsWith('.json'))
+                continue;
+            const file = path.join(entry.parentPath, entry.name);
+            if (entry.parentPath !== localeDir) {
+                ignored.push(display(file));
+                continue;
+            }
+            const namespace = path.basename(entry.name, '.json');
+            if (!collected[locale])
+                collected[locale] = {};
+            collected[locale][namespace] = readTranslationFile(file, display);
+        }
+    }
+    return { collected, ignored };
+}
+function readTranslationFile(file, display) {
+    const raw = fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, '');
+    if (raw.trim() === '') {
+        throw new Error(`${display(file)} is empty: write {} for a namespace with no keys yet.`);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`${display(file)} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}

package/dist/cli/dev-vars.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A `.dev.vars` file's variables, in the dotenv syntax wrangler reads it with: quoted
+ * values, `#` comments (inline too, outside quotes), `export ` prefixes, CRLF. Node's own
+ * `util.parseEnv` does the parsing. The BOM and the `export ` prefixes are removed first:
+ * Node's parser keeps a BOM in the first key, and the prefix is handled here rather than
+ * left to whichever Node release runs the CLI.
+ */
+export declare function parseDevVars(content: string): Record<string, string>;

package/dist/cli/dev-vars.js

@@ -0,0 +1,13 @@
+import { parseEnv } from 'node:util';
+/**
+ * A `.dev.vars` file's variables, in the dotenv syntax wrangler reads it with: quoted
+ * values, `#` comments (inline too, outside quotes), `export ` prefixes, CRLF. Node's own
+ * `util.parseEnv` does the parsing. The BOM and the `export ` prefixes are removed first:
+ * Node's parser keeps a BOM in the first key, and the prefix is handled here rather than
+ * left to whichever Node release runs the CLI.
+ */
+export function parseDevVars(content) {
+    const source = content.replace(/^\uFEFF/, '').replace(/^[ \t]*export[ \t]+/gm, '');
+    const parsed = parseEnv(source);
+    return Object.fromEntries(Object.entries(parsed).filter((entry) => typeof entry[1] === 'string'));
+}

package/dist/cli/generate.d.ts

@@ -12,11 +12,16 @@ export type KvBulkEntry = {
 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.
+ * `languages`, a namespace file name does not match NAMESPACE_NAME or is reserved
+ * (`locale`), 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;
+/**
+ * Throws, naming the key path and the file, on the first `null` in any locale: merged over
+ * the compiled fallback, a null replaces the default locale's text.
+ */
+export declare function assertNoNullValues(collected: CollectedData): 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
@@ -34,7 +39,7 @@ export declare function schemaSourceLocale(collected: CollectedData, defaultLoca
 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.
+ * Throws, naming the key, when an array in it mixes kinds of elements or a value is null.
  */
 export declare function buildTypesContent(collected: CollectedData, defaultLocale: string): string;
 /**
@@ -50,3 +55,10 @@ export declare function buildRuntimeConstantsContent(collected: CollectedData, d
  * Null when the default locale has no translations (nothing to fall back to).
  */
 export declare function buildFallbacksContent(collected: CollectedData, defaultLocale: string): string | null;
+/**
+ * Warnings about what I18n.Schema and the fallbacks will not cover, compared with the
+ * default locale: a namespace no default-locale file has, and keys a locale's file has
+ * that the default locale's lacks (a count per file, the first three paths). Empty when
+ * the default locale has no translations (the CLI warns about that on its own).
+ */
+export declare function translationWarnings(collected: CollectedData, defaultLocale: string): string[];