@edgekits/astro-i18n 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# 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.1.0 — unreleased
+
+### Added
+
+- The engine extracted from edgekits.dev into its own package, with its git history.
+- An Astro integration that serves the config and the generated files as virtual modules, sets `ssr.noExternal`, registers the middleware, and sets Astro's `i18n` block when the project has none.
+- The `Locale` type narrowed to your locales through the augmentable `I18nLocales` interface.
+- The `edgekits-i18n` CLI: `bundle`, `seed` and `migrate`, with per-namespace cache purges and the `.i18n-hashes.json` baseline.
+- Node-safe entries `./config` and `./format` for code that runs outside workerd.
+- Headless `LanguageSwitcher` and `MissingTranslationBanner`: a `classes` prop map and stable `data-*` hooks, no CSS shipped.
+- `countryToLocale`, the geo-IP step of the locale fallback, as an optional config field.
+- `markdownLocale`: the locale `.md` endpoints are redirected to, as an optional config field; without it they pass through untouched.
+- Type declarations for the virtual modules, injected into the consumer's program, so `tsc` and `astro check` accept the runtime source.
+- The `astro-i18n` agent skill (a Claude Code plugin, source in `plugins/astro-i18n/`): adopts the package, localizes forms and multilingual SEO; its version tracks the package's.
+- Security audit fixes (2026-10-12): locale-negotiated redirects are temporary (302) and uncacheable (`Cache-Control: private, no-store`, `Vary: Cookie, Accept-Language`); the CLI validates locale folders and namespace names and escapes generated string literals; the purge client's HTTP 429 retry is bounded and honours `Retry-After`; hardening of `deepMerge` and KV-failure logging; the CLI runs the project's own wrangler (now a declared peer dependency, `^4.125.0`) through Node and `git` directly, with no shell on any platform.

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,395 @@
-# Temporary Holding Version
+# @edgekits/astro-i18n
 
-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.
+Edge-native i18n for Astro on Cloudflare Workers. Translations live as data in Workers KV, one
+JSON value per locale and namespace, so the server renders every page in its language and
+nothing ships to the client; changing a string is a KV write, not a redeploy. Each namespace is
+cached at the edge under its own URL, and `edgekits-i18n migrate` purges only the namespaces
+whose content changed through the Cloudflare Purge API. The default locale's JSON files define a
+typed schema: the CLI generates the `I18n.Schema` declaration, so `t.common.hero.title` is
+checked by TypeScript and a missing key is a compile error.
+
+The design is explained in the edgekits.dev series:
+[Stop Shipping Translations to the Client, Part 1](https://edgekits.dev/en/blog/edge-native-i18n-astro-cloudflare-part-1/),
+[Part 2](https://edgekits.dev/en/blog/edge-native-i18n-astro-cloudflare-part-2/) and
+[Stop Redeploying to Update Translations (Part 3)](https://edgekits.dev/en/blog/granular-edge-cache-purge-astro-cloudflare-part-3/).
+
+## Requirements
+
+- Astro `^7.3` with `output: 'server'` and the `@astrojs/cloudflare` adapter `^14.3`.
+- wrangler `^4.125`, installed in the project (a peer dependency: the CLI runs the project's own
+  wrangler for its KV writes).
+- A `wrangler.jsonc` (the CLI reads that file; `wrangler.toml` and `wrangler.json` are not read).
+- Node `>=22`.
+- A Workers KV namespace bound as `TRANSLATIONS`.
+- For `migrate` only: the site on a proxied Cloudflare zone, its zone ID, and an API token with
+  the Zone › Cache Purge permission.
+
+## Quick start
+
+### 1. Install
+
+```sh
+npm i @edgekits/astro-i18n
+```
+
+### 2. Bind a KV namespace
+
+```sh
+npx wrangler kv namespace create TRANSLATIONS
+```
+
+Add the namespace to `wrangler.jsonc` under the binding name `TRANSLATIONS`:
+
+```jsonc
+{
+  "compatibility_date": "2026-09-01",
+  "kv_namespaces": [{ "binding": "TRANSLATIONS", "id": "<the id wrangler printed>" }],
+}
+```
+
+### 3. Write `edgekits-i18n.config.ts`
+
+At the project root. Both the integration and the CLI read it.
+
+```ts
+// edgekits-i18n.config.ts
+import { defineI18nConfig } from '@edgekits/astro-i18n/config'
+
+export default defineI18nConfig({
+  // The keys are the locales; the only list of languages there is.
+  languages: {
+    en: { countryCode: 'us', name: 'English' },
+    de: { countryCode: 'de', name: 'Deutsch' },
+  },
+  defaultLocale: 'en',
+  // The language cookie: set by the LanguageSwitcher, kept in sync by the middleware.
+  cookie: { name: 'lang', maxAge: 60 * 60 * 24 * 365 },
+  // Prefix of every KV key and the host of every edge-cache URL: use your site's domain.
+  keyPrefix: 'example.com',
+  // Whether MissingTranslationBanner may render.
+  missingTranslationBanner: true,
+  // Every URL starts with its locale (/en/, /de/about/). The only routing there is.
+  routing: 'prefix',
+})
+```
+
+| Field                      | Required | Default      | Meaning                                                                  |
+| -------------------------- | -------- | ------------ | ------------------------------------------------------------------------ |
+| `languages`                | yes      |              | `{ [locale]: { countryCode, name } }`; `countryCode` is for your flag UI |
+| `defaultLocale`            | yes      |              | one of `languages`; its JSON files define the schema                     |
+| `cookie`                   | yes      |              | `{ name, maxAge }` (seconds) of the language cookie                      |
+| `keyPrefix`                | yes      |              | KV keys are `<keyPrefix>:<namespace>:<locale>`                           |
+| `missingTranslationBanner` | yes      |              | enables `MissingTranslationBanner`                                       |
+| `routing`                  | yes      |              | `'prefix'`                                                               |
+| `localesDir`               | no       | `'locales'`  | where the CLI reads `<locale>/<namespace>.json`                          |
+| `generatedDir`             | no       | `'src/i18n'` | where the CLI writes `runtime-constants.ts` and `fallbacks.generated.ts` |
+| `countryToLocale`          | no       | none         | geo-IP step of the locale fallback (see Reference)                       |
+| `markdownLocale`           | no       | none         | the locale `.md` endpoints are served in (see Reference)                 |
+
+The config is validated when it loads: an empty `languages`, a `defaultLocale` or
+`markdownLocale` outside it, or a bad `countryToLocale` entry throws with a message naming the
+field.
+
+### 4. Add the integration
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config'
+import cloudflare from '@astrojs/cloudflare'
+import { edgekitsI18n } from '@edgekits/astro-i18n'
+
+import i18nConfig from './edgekits-i18n.config'
+
+export default defineConfig({
+  output: 'server',
+  adapter: cloudflare(),
+  integrations: [edgekitsI18n(i18nConfig)],
+})
+```
+
+The integration sets up:
+
+- a Vite plugin serving the config and your generated files to the runtime as virtual modules;
+- `vite.ssr.noExternal` for the package, whose runtime ships as source;
+- Astro's `i18n` block, when `astro.config` has none: `locales` from `languages`, your
+  `defaultLocale`, `routing: { prefixDefaultLocale: true, redirectToDefaultLocale: false }`.
+  Astro needs it to compute `preferredLocale` from `Accept-Language`. If you keep your own
+  block, its `locales` must include every configured locale and its `defaultLocale` must match,
+  or the build stops with a message saying which;
+- the `Locale` type: the union of your locales, for the package's exports;
+- type declarations for its virtual modules, so `tsc` and `astro check` accept the package's
+  runtime source in your program;
+- the locale-routing middleware, with `edgekitsI18n(i18nConfig)` or
+  `edgekitsI18n(i18nConfig, { middleware: 'auto' })`. With `{ middleware: 'manual' }` nothing is
+  registered and you place it in your own `sequence()`:
+
+  ```ts
+  // src/middleware.ts
+  import { sequence } from 'astro:middleware'
+  import { onRequest as i18n } from '@edgekits/astro-i18n/middleware'
+
+  export const onRequest = sequence(i18n, yourOwnMiddleware)
+  ```
+
+The middleware redirects a URL without a locale (`/`, `/about/`) to a localized one and sets
+`Astro.locals.uiLocale` (the URL's locale) and `Astro.locals.translationLocale` (the locale to
+fetch translations for) on every request.
+
+### 5. Write translations
+
+One JSON file per locale and namespace, under `localesDir`:
+
+```
+locales/
+  en/
+    common.json
+  de/
+    common.json
+```
+
+```json
+// locales/en/common.json
+{ "hero": { "title": "Hello, world" } }
+```
+
+```json
+// locales/de/common.json
+{ "hero": { "title": "Hallo, Welt" } }
+```
+
+The default locale's files define the schema: their namespaces and keys are the types. Another
+locale may leave keys out; the default locale's text fills the gaps.
+
+### 6. Generate and seed
+
+```sh
+npx edgekits-i18n seed
+```
+
+| 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.
+
+`.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.
+
+### 7. Use translations in a page
+
+```astro
+---
+// src/pages/[lang]/index.astro
+import { fetchTranslations } from '@edgekits/astro-i18n/runtime'
+
+const { common } = await fetchTranslations(Astro.locals.translationLocale, ['common'])
+---
+
+<h1>{common.hero.title}</h1>
+```
+
+`fetchTranslations(locale, namespaces)` returns one object per namespace, typed from the
+schema: `common.hero.title` is a `string`, a key that does not exist is a type error. Run
+`npx astro dev` and open `/de/`: the heading reads "Hallo, Welt", served from local KV. Before
+you edit and re-seed, see `I18N_CACHE` below.
+
+`npx astro check` passes on this setup as is. `tsc` also checks the package's runtime source
+when a `.ts` file of yours imports it, and that source reads `cloudflare:workers` and a
+`KVNamespace` binding: generate the Workers types once with `npx wrangler types` (it needs the
+`compatibility_date` above) and `tsc` passes too.
+
+`@edgekits/astro-i18n/runtime` also exports `fmt` (`{placeholder}` interpolation), `plural` and
+`pluralIcu`, the locale constants (`DEFAULT_LOCALE`, `SUPPORTED_LOCALES`, `LANGUAGES`) and the
+`Locale` type.
+
+### 8. Runtime switches
+
+Both are optional `vars` in `wrangler.jsonc` (or `.dev.vars` locally), read as `on`/`off`
+(`true`/`false` and `1`/`0` work too):
+
+| Var          | Default | Effect                                                          |
+| ------------ | ------- | --------------------------------------------------------------- |
+| `I18N_CACHE` | `on`    | `off` reads KV on every request and skips the edge cache        |
+| `DEBUG_I18N` | `off`   | `on` logs cache hits, misses and KV reads to the Worker console |
+
+While you edit translations locally, put `I18N_CACHE=off` in `.dev.vars`. `astro dev` runs your
+Worker with a local Cache API, which keeps the first value it served for each namespace: after
+a second `seed` the page still shows the old text. With the cache off, a `seed` shows on the
+next request. `.dev.vars` is read when the dev server starts: restart it after you
+add the line.
+
+## Reference
+
+### Which entry to import
+
+| Entry                               | Where it runs              | What it holds                                                                                                  |
+| ----------------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `@edgekits/astro-i18n`              | `astro.config` (Node)      | `edgekitsI18n()` (the integration) and `defineI18nConfig`                                                      |
+| `@edgekits/astro-i18n/config`       | anywhere, Node-safe        | `defineI18nConfig`, `localesOf(config)` (`DEFAULT_LOCALE`, `SUPPORTED_LOCALES`, `LANGUAGES`), the types        |
+| `@edgekits/astro-i18n/format`       | anywhere, Node-safe        | `fmt`, `plural`, `pluralIcu`, `toIetfTag`, `replaceLocaleInPath`, `getLangFromUrl`                             |
+| `@edgekits/astro-i18n/runtime`      | workerd only (pages, APIs) | `fetchTranslations`, the locale constants from the integration's config, locale resolution, the format helpers |
+| `@edgekits/astro-i18n/middleware`   | workerd only               | the i18n middleware (`onRequest`); registered for you unless `middleware: 'manual'`                            |
+| `@edgekits/astro-i18n/components/*` | `.astro` pages             | `LanguageSwitcher`, `MissingTranslationBanner`                                                                 |
+
+Node-safe entries import nothing from `cloudflare:workers` and no virtual module, so unit tests
+under Node and `src/content.config.ts` (evaluated by `astro sync`) can use them. `./runtime` and
+`./middleware` need the integration's Vite setup and the Workers runtime.
+
+### Geo-IP locale fallback: `countryToLocale`
+
+When a request's URL has no locale, the middleware picks one in this order: the language
+cookie, then Astro's `preferredLocale` (full tag, then its language part), then, only when Astro
+reports no preferred locale, the visitor's country (`request.cf.country`) through your
+`countryToLocale` table, and finally `defaultLocale`. Astro computes `preferredLocale` by
+matching `Accept-Language` against its `i18n.locales`, which the integration sets from your
+`languages` unless your `astro.config` has its own `i18n` block.
+
+```ts
+// edgekits-i18n.config.ts
+export default defineI18nConfig({
+  languages: { en: { … }, de: { … }, es: { … }, ja: { … } },
+  defaultLocale: 'en',
+  // ISO 3166-1 alpha-2 (uppercase) → one of `languages`; checked at config time.
+  countryToLocale: { US: 'en', GB: 'en', DE: 'de', AT: 'de', CH: 'de', ES: 'es', MX: 'es', JP: 'ja' },
+  // …
+})
+```
+
+Without `countryToLocale` the geo step is skipped: the package ships no country table of its
+own, so a visitor with no cookie and no preferred locale gets `defaultLocale`.
+
+### Markdown endpoints: `markdownLocale`
+
+The middleware leaves paths ending in `.md` (or `.md/`) out of locale routing. With
+`markdownLocale` set, it also gives them one canonical form: `/<markdownLocale>/<rest>` with no
+trailing slash, reached in a single redirect. A leading locale segment is replaced; any other
+leading segment is kept.
+
+```ts
+// edgekits-i18n.config.ts
+export default defineI18nConfig({
+  // …
+  markdownLocale: 'en', // one of `languages`; checked at config time
+})
+```
+
+| Request          | With `markdownLocale: 'en'` | Without `markdownLocale` |
+| ---------------- | --------------------------- | ------------------------ |
+| `/de/blog/x.md/` | redirect to `/en/blog/x.md` | passed through as is     |
+| `/blog/x.md`     | redirect to `/en/blog/x.md` | passed through as is     |
+| `/en/blog/x.md`  | served                      | passed through as is     |
+
+Use it when your markdown endpoints exist in one locale only. Without it, the package assumes
+nothing about them.
+
+### Styling the components
+
+`LanguageSwitcher` and `MissingTranslationBanner` are headless: they carry structure, behaviour
+and `data-*` hooks, and every class comes from you. The package ships no CSS and needs no
+Tailwind. Pass classes per element through the `classes` prop; a slot you leave out renders no
+`class` attribute at all.
+
+`LanguageSwitcher` slots:
+
+| Slot          | Element                                                                  |
+| ------------- | ------------------------------------------------------------------------ |
+| `root`        | the wrapper `div` inside `<language-switcher>`                           |
+| `trigger`     | the toggle `button`                                                      |
+| `triggerIcon` | the trigger icon (your `triggerIcon` component or the inline default)    |
+| `dropdown`    | the menu `div`                                                           |
+| `item`        | each language `button`                                                   |
+| `itemActive`  | appended to `item` on the current language                               |
+| `itemLabel`   | the `span` holding the flag and the language name                        |
+| `activeIcon`  | the current-language marker (your `activeIcon` component or the default) |
+
+`MissingTranslationBanner` has one slot, `root` (the banner `div`).
+
+Hooks rendered whether or not you pass `classes`, for CSS or your own scripts:
+
+| Hook                                                           | Where                              | Meaning                          |
+| -------------------------------------------------------------- | ---------------------------------- | -------------------------------- |
+| `data-open="true\|false"`                                      | `<language-switcher>`              | the menu is open                 |
+| `data-current-lang`, `data-cookie-name`, `data-cookie-max-age` | `<language-switcher>`              | config the client script reads   |
+| `data-ls-trigger`                                              | the toggle button                  | also carries `aria-expanded`     |
+| `data-ls-dropdown`                                             | the menu                           | `hidden` attribute while closed  |
+| `data-ls-item`, `data-lang`                                    | each language button               | `data-lang` is the item's locale |
+| `data-active="true"`                                           | the current language's button only | that button is also `disabled`   |
+| `data-missing="content\|ui"`                                   | the banner                         | which of your `texts` is showing |
+
+The menu opens and closes through the `hidden` HTML attribute, `data-open` on the element and
+`aria-expanded` on the trigger; the script adds or removes no class. The browser's default
+`[hidden] { display: none }` hides the menu. A display class on the `dropdown` slot (`flex`,
+`grid`, `block`) can override that default, so either leave display alone there or restate it,
+as the CSS example below does.
+
+With Tailwind:
+
+```astro
+<LanguageSwitcher
+  classes={{
+    root: 'relative',
+    trigger: 'rounded-full p-2 hover:bg-muted',
+    triggerIcon: 'size-5',
+    dropdown: 'absolute right-8 z-50 -mt-8 w-44 overflow-hidden rounded-lg border bg-card shadow-lg',
+    item: 'flex w-44 items-center justify-between px-4 py-2 text-sm hover:bg-muted',
+    itemActive: 'bg-background cursor-default',
+    itemLabel: 'flex items-center gap-3',
+    activeIcon: 'size-6',
+  }}
+/>
+<MissingTranslationBanner texts={bannerTexts} classes={{ root: 'mx-6 mt-6 border px-4 py-2 text-center' }} />
+```
+
+With plain CSS on the hooks, no `classes` needed:
+
+```css
+language-switcher > div {
+  position: relative;
+}
+[data-ls-dropdown] {
+  position: absolute;
+  right: 0;
+  display: flex;
+  flex-direction: column;
+}
+[data-ls-dropdown][hidden] {
+  display: none; /* the UA default, restated because the rule above sets display */
+}
+[data-ls-item][data-active] {
+  font-weight: 600;
+}
+[data-missing='content'] {
+  border-left: 3px solid orange;
+}
+```
+
+## How it works
+
+A request reaches the middleware, which settles the URL's locale (redirecting when there is
+none) and sets `uiLocale` and `translationLocale` on `Astro.locals`. A page asks
+`fetchTranslations` for the namespaces it renders. Each namespace is looked up in the Workers
+Cache API under `https://<keyPrefix>/…`; the misses are read from KV in one batch, merged over
+the compiled default-locale fallbacks, returned, and written back to the cache in the
+background. Cached entries live for a year (`s-maxage=31536000, immutable`): `migrate` purges the ones whose content
+changed, and leaves the rest warm. If KV cannot be reached, the compiled fallbacks render the
+default locale's text instead of an error.
+
+## License
+
+MIT © Gary Stupak. See [LICENSE](LICENSE).

package/dist/cli/generate.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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` or a namespace file name does not match NAMESPACE_NAME. 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. */
+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>` 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,133 @@
+import { 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 the `FALLBACK_<NAMESPACE>`
+// identifier, so its file name is restricted to what is valid in all three.
+export const NAMESPACE_NAME = /^[a-z0-9][a-z0-9_]*$/;
+/**
+ * Throws, naming the offender, when a locale folder is not one of the config's
+ * `languages` or a namespace file name does not match NAMESPACE_NAME. 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(', ')}.`);
+        }
+        for (const ns of Object.keys(namespaces)) {
+            if (!NAMESPACE_NAME.test(ns)) {
+                throw new Error(`Namespace "${ns}" (${locale}/${ns}.json) must match ${NAMESPACE_NAME}: lowercase letters, digits and underscores.`);
+            }
+        }
+    }
+}
+/**
+ * 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 generateSchemaTs(schema, indent = 4) {
+    const pad = ' '.repeat(indent);
+    const padInner = ' '.repeat(indent + 2);
+    if (schema && typeof schema === 'object' && !Array.isArray(schema)) {
+        const entries = Object.entries(schema);
+        if (entries.length === 0)
+            return '{}';
+        const lines = entries.map(([key, value]) => {
+            const valueTs = value && typeof value === 'object' && !Array.isArray(value)
+                ? generateSchemaTs(value, indent + 2)
+                : 'string';
+            return `${padInner}${JSON.stringify(key)}: ${valueTs}`;
+        });
+        return `{\n${lines.join(';\n')};\n${pad}}`;
+    }
+    return 'string';
+}
+/** `src/i18n.generated.d.ts`: the global `I18n.Schema`, from the schema source locale. */
+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);
+        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>` 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)) {
+        const constName = `FALLBACK_${ns.toUpperCase()}`;
+        lines.push(`export const ${constName} = ${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[];