@edgekits/astro-i18n 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,48 @@ 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`.**
+- **Peer floors:** `astro` `^7.4.0`, `@astrojs/cloudflare` `^14.4.0`, `wrangler` `^4.152.0` (`npm i -D wrangler@^4.152.0` if npm reports a peer conflict).
+- **The build fails** on `trailingSlash: 'never'`, on a `base` other than `/`, on a prerendered `404.astro` (either mode), and, with routing `'prefix-except-default'`, on a prerendered `[lang]` route (`export const prerender = true`). Each message says why.
+- **If you copied the skill's recipes:** the no-JS form recipe redirects to `ctx.originPathname` (since 0.2.2); the fallback-post recipe now answers a missing entry with `return Astro.rewrite('/404')`; `src/pages/404.astro` (and `500.astro`) stays at the root, not under `[lang]`, and reads the locale from `Astro.locals`.
+- **Responses change:** root-mode default-locale pages send `Vary: Cookie` (Cloudflare's cache ignores it: bypass or key on the lang cookie); a response that sets the lang cookie is `Cache-Control: private`; redirects of requests other than GET/HEAD are 307/308; a locale segment in another case (`/DE/…`) redirects to `/de/…`; `/404` and `/500` pass through untouched.
+
+### Changed
+
+- Built and tested on astro 7.4.2, `@astrojs/cloudflare` 14.4.2 and wrangler 4.154; peer floors raised to `astro` `^7.4.0`, `@astrojs/cloudflare` `^14.4.0`, `wrangler` `^4.152.0`; `engines.node` `>=22.23.4`.
+- The edge cache holds each namespace's raw KV value under versioned URLs (`i18n:v2:`) and merges the compiled fallback on every read, so a default-locale edit reaches every locale on the next deploy; a namespace KV lacks is cached as missing for 60 s (`@edgekits/i18n-core`).
+- Any path whose last segment has an extension that starts with a letter bypasses locale routing (`/site.webmanifest`, `/doc.pdf`); `/blog/v2.0` stays a page.
+- The ignored prefixes match on a segment boundary (`/apis/` is a page) and include `/_server-islands` and `/.well-known`.
+- The soft 404 on bypassed paths replaces only a 404 HTML response; other HTML (a server island) passes.
+- Redirects of requests other than GET/HEAD keep the method: 308 for a normalisation, 307 for a negotiated one.
+- Root-mode default-locale pages carry `Vary: Cookie`; a response that writes the lang cookie is `Cache-Control: private` (merged; `no-store` kept).
+- `localizedPath` keeps a file path without a trailing slash and keeps a `?query`/`#hash`; `toIetfTag` cases each subtag by length (`zh-Hant-TW`); `plural` interpolates both forms.
+- `LanguageSwitcher` keeps the query string when it navigates and writes `Secure` only on https; its file paths follow the core's rule. Markup unchanged.
+
+### Added
+
+- The integration refuses `trailingSlash: 'never'`, a `base` other than `/`, a prerendered `404.astro` (served without the middleware; `Astro.rewrite('/404')` into it is a 500), and in `'prefix-except-default'` a prerendered `[lang]` route, each with the reason.
+- A locale segment in another case (`/DE/about/`, `/pt-BR/`) gets one permanent redirect to the lower-case URL.
+- `isFilePath` in `./format`.
+
+### Fixed
+
+- The root-mode redirect of a `[lang]` file route's `/<defaultLocale>/…` form could produce a protocol-relative `Location` (`/en//evil.com/x.png` -> `//evil.com/x.png`); every target is now built from path segments.
+- `/404` and `/500` pass through untouched in both modes (they were redirected, or rewritten again when Astro re-ran the middleware for the error page). Astro re-runs it with the original request, so the re-entry is recognised by the error route's pattern with the locals already set: the error page renders once, with the visitor's locale.
+- `localizedPath` treats `\` as a segment separator (`@edgekits/i18n-core`), and the README's canonical/hreflang recipe appends to `Astro.url.origin` instead of resolving against `Astro.site`: a request for `/%5Cevil.com/` no longer yields an off-site canonical.
+- Server islands in `'prefix-except-default'` were redirected to a trailing-slash URL and their HTML replaced by the soft 404.
+- `/.well-known/…` URLs were treated as pages.
+
 ## 0.2.2 — 2026-10-27
 
 ### Fixed

package/README.md

@@ -15,11 +15,11 @@ The design is explained in the edgekits.dev series:
 
 ## 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
+- Astro `^7.4` with `output: 'server'` and the `@astrojs/cloudflare` adapter `^14.4`.
+- wrangler `^4.152`, 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`.
+- Node `>=22.23.4` (what Astro 7.4 requires).
 - 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. Zone › Zone › Read is optional; with it, `migrate` checks
@@ -75,26 +75,28 @@ export default defineI18nConfig({
 })
 ```
 
-| Field                      | Required | Default                   | Meaning                                                                                                                                                                                                     |
-| -------------------------- | -------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `languages`                | yes      |                           | `{ [locale]: { name, countryCode? } }`; `countryCode` is optional: the code your flag component receives                                                                                                    |
-| `defaultLocale`            | yes      |                           | one of `languages`; its JSON files define the schema                                                                                                                                                        |
-| `cookie`                   | yes      |                           | `{ name, maxAge }` (seconds) of the language cookie                                                                                                                                                         |
-| `keyPrefix`                | yes      |                           | a hostname of your zone, or a unique name without a dot: KV keys are `<keyPrefix>:<namespace>:<locale>` and every cache URL is `https://<keyPrefix>/…` (see [Deployment targets](#deployment-targets))      |
-| `missingTranslationBanner` | yes      |                           | enables `MissingTranslationBanner`                                                                                                                                                                          |
-| `routing`                  | no       | `'prefix-except-default'` | `'prefix-except-default'`: the default locale at the root (`/about/`), the others prefixed (`/de/about/`); `'prefix'`: every URL starts with its locale (`/en/about/`). See [Routing modes](#routing-modes) |
-| `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)                                                                                                                                                    |
+| Field                      | Required | Default                   | Meaning                                                                                                                                                                                                                                                      |
+| -------------------------- | -------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `languages`                | yes      |                           | `{ [locale]: { name, countryCode? } }`; `countryCode` is optional: the code your flag component receives                                                                                                                                                     |
+| `defaultLocale`            | yes      |                           | one of `languages`; its JSON files define the schema                                                                                                                                                                                                         |
+| `cookie`                   | yes      |                           | `{ name, maxAge }` (seconds) of the language cookie                                                                                                                                                                                                          |
+| `keyPrefix`                | yes      |                           | a hostname of your zone, or a unique name without a dot, written as a URL host (lowercase, no scheme or path): KV keys are `<keyPrefix>:<namespace>:<locale>` and every cache URL is `https://<keyPrefix>/…` (see [Deployment targets](#deployment-targets)) |
+| `missingTranslationBanner` | yes      |                           | enables `MissingTranslationBanner`                                                                                                                                                                                                                           |
+| `routing`                  | no       | `'prefix-except-default'` | `'prefix-except-default'`: the default locale at the root (`/about/`), the others prefixed (`/de/about/`); `'prefix'`: every URL starts with its locale (`/en/about/`). See [Routing modes](#routing-modes)                                                  |
+| `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)                                                                                                                                                                                                     |
 
 Locale codes (the keys of `languages`) are lowercase everywhere: the config, the `locales/`
 folders and the URLs (`pt-br`, not `pt-BR`). `toIetfTag()` from `./format` gives the IETF form
 (`pt-BR`) where one is needed, such as `<html lang>` and hreflang.
 
-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.
+The config is validated when it loads, and each of these throws with a message naming the
+field: an empty `languages`; a locale key that is not lowercase; a `keyPrefix` that is not a
+URL host as written; a `defaultLocale` or `markdownLocale` outside `languages`; a `routing`
+other than the two modes; a `countryToLocale` key that is not an uppercase country code, or a
+value outside `languages`.
 
 ### 4. Add the integration
 
@@ -167,8 +169,12 @@ locales/
 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.
 
-Lists are allowed and typed: `["a", "b"]` is `string[]`, a list of objects is `Array<{…}>` from
-its first element, and a locale that has the list replaces it whole.
+Values are typed as written: strings, numbers and booleans. Lists are allowed and typed:
+`["a", "b"]` is `string[]`; a list of objects is `Array<{…}>`, one object type merged from
+its elements (a key every element has is required, any other optional, a key whose type differs
+between elements a union); a locale that has the list replaces it whole. Two things stop the
+CLI, naming the key path and the file: a `null` (leave the key out to fall back to the default
+locale's text) and a list that mixes kinds of elements (strings and objects).
 
 ### 6. Generate and seed
 
@@ -179,30 +185,49 @@ npx edgekits-i18n seed
 The `edgekits-i18n` command comes from `@edgekits/i18n-core`, which this package depends on, so
 it is in your project's `node_modules/.bin` with no extra install.
 
-| 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` |
+| 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`; the binding's `preview_id` when set)                                            |
+| `edgekits-i18n migrate`            | the same as `bundle --fallbacks`                                                                                    | pushes to production KV, deletes the keys of removed files, purges the changed namespaces' edge-cache entries twice, 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:
+`.i18n-hashes.json` holds, per KV namespace id, one content hash per namespace and locale as
+of the last successful `migrate`; the next `migrate` purges exactly the entries whose hash
+changed, and deletes the KV keys of files removed since. Rules:
 
-- Only `migrate` writes it, and only after the purge succeeded (or nothing changed). `seed`
+- Only `migrate` writes it, and only after both purges 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` refuses to run while the baseline of the KV namespace it writes differs from the
+  one in the committed file (`HEAD`), since a wrong baseline would skip purges silently. Only
+  that namespace's entry counts: `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 file from 0.2.x (one flat baseline) is the baseline of the top-level `TRANSLATIONS` id,
+  whichever environment migrates first; it is rewritten per KV id.
+- After a `git revert` of translations, the baseline is reverted with them and reports no
+  change: run `migrate --purge-all`, which purges every namespace's URLs whatever the
+  baseline says.
 
 `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.
+`.dev.vars`). It purges, waits 65 s for KV to settle (`--purge-delay`), and purges again.
+Without the zone ID or token, when deleting the removed keys or a purge fails, it still pushes
+to KV but exits 1 and leaves `.i18n-hashes.json` alone, so the next run retries. The zone ID
+must be 32 hex characters. `--env <name>` reads the binding and the zone ID from `env.<name>`,
+and `.dev.vars.<name>` instead of `.dev.vars` when it exists (as wrangler does). Two
+environments on one zone with different KV namespaces need a `keyPrefix` each (a config per
+environment): with one, their cache URLs are the same, and `migrate` warns. An unknown
+argument (`-e staging`) exits 1. All flags:
+[the core's CLI reference](https://github.com/EdgeKits/i18n/tree/main/packages/core#cli).
+
+After you delete a translation file, `migrate` removes its key from production KV; `seed`
+does not touch local KV's copy. Wipe `.wrangler/state` (or delete the key with
+`wrangler kv key delete --local`) so `astro dev` stops serving it.
 
 ### 7. Use translations in a page
 
@@ -251,14 +276,14 @@ add the line.
 
 ### 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`                                                                 |
+| 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`, `localizedPath`, `isFilePath`, `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
@@ -266,12 +291,14 @@ under Node and `src/content.config.ts` (evaluated by `astro sync`) can use them.
 
 ### Geo-IP locale fallback: `countryToLocale`
 
-When a request's URL has no locale, the middleware picks one in this order: the language
-cookie, then the `Accept-Language` header (each tag in `q` order, the full tag, then its
-language part, so `es-MX` reaches `es`; the first tag that names one of your `languages` wins),
-then, only when no tag matched, the visitor's country (`request.cf.country`) through your
-`countryToLocale` table, and finally `defaultLocale`. The middleware reads the header itself;
-Astro's `preferredLocale` is not used.
+In `'prefix'`, when a request's URL has no locale, the middleware picks one in this order: the
+language cookie, then the `Accept-Language` header (each tag in `q` order, the full tag, then
+its language part, so `es-MX` reaches `es`; the first tag that names one of your `languages`
+wins), then, only when no tag matched, the visitor's country (`request.cf.country`) through
+your `countryToLocale` table, and finally `defaultLocale`. The middleware reads the header itself;
+Astro's `preferredLocale` is not used. In `'prefix-except-default'` a URL without a locale is a
+default-locale page: no cascade runs, and only a language cookie naming another locale
+redirects (see [Routing modes](#routing-modes)).
 
 ```ts
 // edgekits-i18n.config.ts
@@ -302,12 +329,23 @@ export default defineI18nConfig({
 })
 ```
 
+In `'prefix'`:
+
 | 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     |
 
+In `'prefix-except-default'` (default locale `en`), the default locale's form has no prefix, and
+a `.md` path without a locale renders from the default locale's `[lang]` endpoint:
+
+| Request          | With `markdownLocale: 'en'` | With `markdownLocale: 'de'` | Without `markdownLocale`    |
+| ---------------- | --------------------------- | --------------------------- | --------------------------- |
+| `/de/blog/x.md/` | redirect to `/blog/x.md`    | redirect to `/de/blog/x.md` | passed through as is        |
+| `/blog/x.md`     | served (as `/en/blog/x.md`) | redirect to `/de/blog/x.md` | served (as `/en/blog/x.md`) |
+| `/en/blog/x.md`  | redirect to `/blog/x.md`    | redirect to `/de/blog/x.md` | passed through as is        |
+
 Use it when your markdown endpoints exist in one locale only. Without it, the package assumes
 nothing about them.
 
@@ -335,9 +373,15 @@ In `'prefix-except-default'` the default locale has no prefix here either: with
 In both modes, rewrites and redirects keep the query string (`/?utm=x` redirects to
 `/en/?utm=x` in `'prefix'`, and renders `/` with `?utm=x` in `'prefix-except-default'`).
 
+A middleware after the i18n one sees `context.url.pathname` as the visitor sent it, still
+percent-encoded (`/%61dmin/` for `/admin/`, under the `/<defaultLocale>/…` rewrite in
+`'prefix-except-default'`): match on decoded paths (`decodeURIComponent`), or on
+`context.routePattern` and `context.params`.
+
 In `'prefix-except-default'`, build canonical and hreflang URLs from `Astro.originPathname`
 (the URL the visitor requested; `Astro.url` is the rewritten `/<defaultLocale>/…`) through
-`localizedPath` from `/runtime`. Astro's own `astro:i18n` URL helpers prefix the default locale
+`localizedPath` from `/runtime`, appended to `Astro.url.origin` (string concatenation, not
+`new URL(path, Astro.site)`: the path is the visitor's, and only the origin is yours). Astro's own `astro:i18n` URL helpers prefix the default locale
 here, so `localizedPath` is the one to use:
 
 ```astro
@@ -352,9 +396,9 @@ const options = {
 const path = Astro.originPathname
 ---
 
-<link rel="canonical" href={new URL(localizedPath(Astro.locals.uiLocale, path, options), Astro.site)} />
-{SUPPORTED_LOCALES.map((locale) => <link rel="alternate" hreflang={toIetfTag(locale)} href={new URL(localizedPath(locale, path, options), Astro.site)} />)}
-<link rel="alternate" hreflang="x-default" href={new URL(localizedPath(DEFAULT_LOCALE, path, options), Astro.site)} />
+<link rel="canonical" href={Astro.url.origin + localizedPath(Astro.locals.uiLocale, path, options)} />
+{SUPPORTED_LOCALES.map((locale) => <link rel="alternate" hreflang={toIetfTag(locale)} href={Astro.url.origin + localizedPath(locale, path, options)} />)}
+<link rel="alternate" hreflang="x-default" href={Astro.url.origin + localizedPath(DEFAULT_LOCALE, path, options)} />
 ```
 
 Two limits:
@@ -363,8 +407,46 @@ Two limits:
   page at `/de/` (a content slug `de`) cannot exist next to the German site.
 - A shared HTML cache in front of the site must key root paths on the lang cookie, or skip
   caching requests that carry one: the same URL renders for a cookie-less visitor and
-  redirects one whose cookie names another locale. Under `'prefix'`, `/en/` is in the same
-  situation: it answers a visitor whose cookie names another locale with a `Set-Cookie`.
+  redirects one whose cookie names another locale. Every default-locale page response carries
+  `Vary: Cookie`, but Cloudflare's cache ignores `Vary: Cookie`: a Cache Rule must bypass
+  requests with the lang cookie, or include it in the cache key. Under `'prefix'`, `/en/` is in
+  the same situation: it answers a visitor whose cookie names another locale with a `Set-Cookie`.
+
+#### What the middleware leaves alone, and the rules it keeps (both modes)
+
+- **Files and system paths pass through.** A path whose last segment ends in an extension that
+  starts with a letter is a file (`/rss.xml`, `/doc.pdf`, `/site.webmanifest`; `/blog/v2.0` is
+  a page), and so is everything under `/api`, `/assets`, `/_astro`, `/_image`, `/_actions`,
+  `/_server-islands`, `/.well-known`, `/favicon.ico` and the Vite dev server's `/@vite`, `/@id`,
+  `/@fs`, `/src` and `/node_modules`, each matched on a segment boundary (`/apis/` is a page). When Astro answers such a request with its 404 page, the middleware
+  sends a plain-text 404 instead; any other response passes unchanged.
+- **A page whose last segment contains a dot is addressed with its trailing slash**
+  (`/team/john.doe/`): without it, `/team/john.doe` is a file path, gets no redirect and no
+  locale. Link to the slash form; `localizedPath` gives it for a path that ends in `/`.
+- **Server islands** (`server:defer`) are fetched from `/_server-islands/…`, a URL without a
+  locale: in the island, `Astro.locals.uiLocale` is the default locale. Pass the page's locale
+  to the island as a prop.
+- **Error pages stay at the root**: `src/pages/404.astro` (and `500.astro`), not under
+  `[lang]`. `/404` and `/500` pass through untouched, and the page reads the locale from
+  `Astro.locals` (the visitor's, when Astro renders it for a missing page under `/de/` or for
+  a page that answers `new Response(null, { status: 404 })`). In a page, answer a missing
+  entry with `return Astro.rewrite('/404')`. Keep `404.astro` on-demand: a prerendered one is
+  refused at build time.
+- **Redirects keep the method.** For a request other than GET or HEAD (a form POST), a
+  permanent normalisation is a 308 and a negotiated redirect a 307, so the body is resent.
+- **The locale segment is lower case.** `/DE/about/` and `/pt-BR/` redirect permanently, in one
+  hop, to the canonical lower-case URL (`/de/about/`, `/pt-br/`; the default locale without its
+  prefix in `'prefix-except-default'`).
+- **A response that sets the lang cookie is `Cache-Control: private`** (the URL wins over a
+  stale cookie, and the corrected cookie is this visitor's); an existing `no-store` stays.
+
+The integration refuses four Astro settings at build time, each with the reason:
+`trailingSlash: 'never'` (Astro strips the slash the middleware adds: every page would
+redirect forever; `'ignore'` and `'always'` work), a `base` other than `/` (the middleware's
+paths assume the site root), a prerendered `404.astro` in either mode (Astro serves it without
+the middleware, and `Astro.rewrite('/404')` into it is a 500), and in `'prefix-except-default'`
+a prerendered `[lang]` route (`export const prerender = true`): root URLs render through a
+rewrite, and Astro refuses a rewrite into a prerendered route.
 
 ### Styling the components
 
@@ -487,9 +569,9 @@ cache.
 
 **Workers for Platforms, untrusted namespace.** `request.cf` is absent, so the country step of
 the locale cascade never runs. `caches.default` is disabled, so every render reads its
-namespaces from KV in one bulk read: the output is correct, only the cache layer and its KV
-savings are gone. Set `I18N_CACHE=off` so the behaviour is explicit, and expect one bulk KV read
-per render.
+namespaces from KV in bulk reads of up to 100 keys: the output is correct, only the cache
+layer and its KV savings are gone. Set `I18N_CACHE=off` so the behaviour is explicit, and
+expect one bulk KV read per render (per 100 namespaces).
 
 <!-- skill-guide:start -->
 
@@ -575,11 +657,12 @@ npx skills add EdgeKits/i18n --skill astro-i18n
 
 ### Prerequisites
 
-- An Astro `^7.3` project with `output: 'server'` and the `@astrojs/cloudflare` adapter `^14.3`.
+- An Astro `^7.4` project with `output: 'server'` and the `@astrojs/cloudflare` adapter `^14.4`.
   For a new site: `npm create astro@latest`, then `npx astro add cloudflare`, then set
   `output: 'server'` in `astro.config`.
-- wrangler `^4.125` installed in the project (`npm i -D wrangler`) and a `wrangler.jsonc`. The
+- wrangler `^4.152` installed in the project (`npm i -D wrangler`) and a `wrangler.jsonc`. The
   package's CLI runs the project's own wrangler, never a global one.
+- Node `>=22.23.4`.
 - A git repository (`git init`): the generated files and the purge baseline
   (`.i18n-hashes.json`) are committed, and `migrate` checks the baseline against git (outside
   a repository it skips that check, with a warning).
@@ -687,12 +770,12 @@ A locale without a `countryCode` shows its name alone. A `countryCode` whose SVG
 
 Before it reports back, the skill runs its adoption checklist: the config matches your answers
 and every locale code is lowercase; `seed` writes the generated files and leaves
-`.i18n-hashes.json` alone; `astro check` passes; under `astro dev`, `/` redirects to a locale,
-each locale renders its own copy (or the default locale's, if it has no JSON yet), an unknown
+`.i18n-hashes.json` alone; `astro check` passes; under `astro dev`, `/` redirects to a locale
+(`'prefix'`) or renders the default locale (`'prefix-except-default'`), each locale renders its own copy (or the default locale's, if it has no JSON yet), an unknown
 first segment such as `/zz/` is prefixed rather than crashing, `<html lang>` reads `pt-BR` on a
 `pt-br` page, hreflang tags cover every locale plus `x-default`, and the switcher changes the
 URL and sets the language cookie. It also checks that no page is left at `src/pages/*.astro`
-and that every `countryCode` has its SVG.
+(the error pages `404.astro` and `500.astro` excepted) and that every `countryCode` has its SVG.
 
 ### Everyday work
 
@@ -714,7 +797,7 @@ seed`. A key that exists only in another locale is not typed.
 
 `.i18n-hashes.json` records what production KV holds. Only a successful `migrate` writes it,
 it is committed right after, and nothing else edits it. `migrate` refuses to run while that
-file has uncommitted changes.
+file's baseline for the KV namespace it writes differs from the committed one.
 
 ### Forms and SEO
 
@@ -758,13 +841,15 @@ canonical at the original instead of using `noindex`.
   run since. Add it to the default locale and run `seed` (or `bundle`); if the editor still
   shows the error, restart its TypeScript server.
 - **`Cannot find module 'cloudflare:workers'` in `tsc`.** Run `npx wrangler types`.
-- **`migrate` refuses to run.** `.i18n-hashes.json` has uncommitted changes. If the last
-  `migrate` wrote it, commit it. If anything else changed it, discard the change with
+- **`migrate` refuses to run.** The baseline of the KV namespace it writes, in
+  `.i18n-hashes.json`, differs from the committed one. If the last `migrate` wrote it, commit it. If anything else changed it, discard the change with
   `git checkout .i18n-hashes.json` and run `migrate` again. Never edit or delete it to get
   past the check.
-- **`migrate` updated KV but the site shows old copy.** The purge was skipped: the zone is not
-  proxied, or the zone ID or token is missing. Fix it and run `migrate` again; it retries the
-  same purge.
+- **`migrate` exits 1 after "KV is updated; the edge cache is not".** The purge was skipped or
+  failed (the zone ID or token is missing or malformed, or the Purge API refused), or deleting
+  the KV keys of removed files failed. Fix it and run `migrate` again; it retries the same
+  deletions and purge. If it exited 0 and the site still shows old copy, the zone
+  is not proxied.
 - **npm 12: `esbuild` or `workerd` did not install.** npm 12 blocks dependency install
   scripts by default and lists the skipped packages at the end of `npm install`. Both need
   theirs: run `npm install-scripts approve esbuild workerd`, then
@@ -798,13 +883,18 @@ under their own terms. EdgeKits runs no service behind this plugin.
 
 ## 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
+A request reaches the middleware, which settles the URL's locale (in `'prefix'` it redirects a
+URL without one; in `'prefix-except-default'` it renders such a URL as the default locale's
+page through an internal rewrite to `/<defaultLocale>/…`) 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
+Cache API under `https://<keyPrefix>/…`; the misses are read from KV in batches of up to 100
+keys, and their KV values are written back to the cache in the background, marked
+`X-EdgeKits-I18n: v2` (a response at that URL without the mark is a miss). Every namespace,
+cached or fresh, is merged over the compiled default-locale fallbacks when it is read, so a new
+default-locale key shows in every locale on the next deploy. A cached value lives for a year
+(`s-maxage=31536000, immutable`): `migrate` purges the ones whose content changed, and leaves
+the rest warm. A namespace KV does not have is cached as missing for 60 seconds. If KV cannot be reached, the compiled fallbacks render the
 default locale's text instead of an error.
 
 ## License

package/dist/integration/index.d.ts

@@ -25,6 +25,36 @@ export declare function resolveConfig(config: I18nConfig): I18nConfig & {
  * instead of merging.
  */
 export declare function localesDeclaration(locales: readonly string[]): string;
+/**
+ * The Astro settings the middleware cannot work under, refused at config time:
+ * - `trailingSlash: 'never'`: Astro removes a trailing slash before the middleware runs
+ *   (astro/dist/core/routing/handler.js:105-107, Astro 7.4.2), and the middleware adds it
+ *   back: every page would redirect forever. `'ignore'` (the default) and `'always'` work.
+ * - a `base` other than `/`: the middleware's paths and redirects assume the site's root.
+ */
+export declare function assertAstroRouting(astroConfig: Pick<AstroConfig, 'trailingSlash' | 'base'>): void;
+/**
+ * In 'prefix-except-default' the default locale's pages render through a rewrite to
+ * `/<default>/…`, and Astro refuses a rewrite from an on-demand request into a
+ * prerendered route (ForbiddenRewrite, a 500: astro/dist/core/rewrites/handler.js:29-33,
+ * Astro 7.4.2). Every `[lang]` route must be on-demand.
+ */
+export declare function assertNoPrerenderedLangRoute(routes: ReadonlyArray<{
+    pattern: string;
+    isPrerendered: boolean;
+}>): void;
+/**
+ * A prerendered 404 page, in either mode: Astro serves it as a static file without the
+ * middleware (no locale in `locals`), and a page's `Astro.rewrite('/404')` into it from an
+ * on-demand request is a ForbiddenRewrite, a 500 (astro/dist/core/rewrites/handler.js:29-33,
+ * Astro 7.4.2). Only the project's own route counts: Astro's built-in 404 is on-demand.
+ */
+export declare function assertNoPrerendered404(routes: ReadonlyArray<{
+    pattern: string;
+    isPrerendered: boolean;
+    origin?: string;
+    entrypoint?: string;
+}>): void;
 /**
  * The Astro `i18n` block set when the project has none: locales and default from the
  * config; routed as locale-prefixed in both modes (the middleware redirects `/` itself in
@@ -32,10 +62,10 @@ export declare function localesDeclaration(locales: readonly string[]): string;
  * re-validate what `updateConfig` merges, so its schema defaults never fill a partial block.
  *
  * `prefixDefaultLocale: true` in 'prefix-except-default' too: Astro's own i18n check runs
- * after the middleware, on the rewritten URL (astro/dist/core/routing/handler.js:128-130),
- * and with `prefixDefaultLocale: false` the strategy `pathname-prefix-other-locales`
- * answers notFound to any path carrying the default locale (astro/dist/i18n/router.js:
- * 104-121) — the rewritten `/<default>/about/` is exactly that. With `true` the check
+ * after the middleware, on the rewritten URL (astro/dist/core/routing/handler.js:167-169,
+ * Astro 7.4.2), and with `prefixDefaultLocale: false` the strategy
+ * `pathname-prefix-other-locales` answers notFound to any path carrying the default locale
+ * (astro/dist/i18n/router.js:107-124) — the rewritten `/<default>/about/` is exactly that. With `true` the check
  * passes and `Astro.currentLocale` works on root pages.
  */
 export declare function astroI18n(config: I18nConfig): NonNullable<AstroConfig['i18n']>;

package/dist/integration/index.js

@@ -19,6 +19,7 @@ export function edgekitsI18n(config, options = {}) {
         hooks: {
             'astro:config:setup': ({ config: astroConfig, updateConfig, addMiddleware }) => {
                 const generatedDir = new URL(`${trimSlashes(i18nConfig.generatedDir ?? DEFAULT_GENERATED_DIR)}/`, astroConfig.root);
+                assertAstroRouting(astroConfig);
                 // Astro sets `Astro.currentLocale` (read by `resolveLocale`) only with an `i18n`
                 // block: set it when the project has none, check it when it has one.
                 if (astroConfig.i18n)
@@ -36,6 +37,11 @@ export function edgekitsI18n(config, options = {}) {
                     addMiddleware({ entrypoint: '@edgekits/astro-i18n/middleware', order: 'pre' });
                 }
             },
+            'astro:routes:resolved': ({ routes }) => {
+                assertNoPrerendered404(routes);
+                if (i18nConfig.routing === 'prefix-except-default')
+                    assertNoPrerenderedLangRoute(routes);
+            },
             'astro:config:done': ({ injectTypes }) => {
                 injectTypes({ filename: 'locales.d.ts', content: localesDeclaration(Object.keys(i18nConfig.languages)) });
                 // The shipped runtime imports the virtual modules; a consumer's program needs their
@@ -79,6 +85,53 @@ export function localesDeclaration(locales) {
         '',
     ].join('\n');
 }
+/**
+ * The Astro settings the middleware cannot work under, refused at config time:
+ * - `trailingSlash: 'never'`: Astro removes a trailing slash before the middleware runs
+ *   (astro/dist/core/routing/handler.js:105-107, Astro 7.4.2), and the middleware adds it
+ *   back: every page would redirect forever. `'ignore'` (the default) and `'always'` work.
+ * - a `base` other than `/`: the middleware's paths and redirects assume the site's root.
+ */
+export function assertAstroRouting(astroConfig) {
+    if (astroConfig.trailingSlash === 'never') {
+        throw new Error("[@edgekits/astro-i18n] `trailingSlash: 'never'` is not supported: Astro removes the trailing slash " +
+            'before the middleware runs, and the middleware adds it back to every page, so each request would ' +
+            "redirect forever. Use 'ignore' (the default) or 'always'.");
+    }
+    if (astroConfig.base !== undefined && astroConfig.base !== '/') {
+        throw new Error(`[@edgekits/astro-i18n] \`base: ${JSON.stringify(astroConfig.base)}\` is not supported: the middleware's ` +
+            'locale paths and redirects are built from the site root. Serve the site at the root of its host ' +
+            '(remove `base`, or set it to "/").');
+    }
+}
+/**
+ * In 'prefix-except-default' the default locale's pages render through a rewrite to
+ * `/<default>/…`, and Astro refuses a rewrite from an on-demand request into a
+ * prerendered route (ForbiddenRewrite, a 500: astro/dist/core/rewrites/handler.js:29-33,
+ * Astro 7.4.2). Every `[lang]` route must be on-demand.
+ */
+export function assertNoPrerenderedLangRoute(routes) {
+    const prerendered = routes.find((route) => route.isPrerendered && (route.pattern === '/[lang]' || route.pattern.startsWith('/[lang]/')));
+    if (prerendered) {
+        throw new Error(`[@edgekits/astro-i18n] ${prerendered.pattern} is prerendered: with routing 'prefix-except-default' the ` +
+            "default locale's pages render through a rewrite to /<default>/…, and Astro refuses a rewrite into a " +
+            "prerendered route (ForbiddenRewrite). Remove `export const prerender = true` from that page, or use routing 'prefix'.");
+    }
+}
+/**
+ * A prerendered 404 page, in either mode: Astro serves it as a static file without the
+ * middleware (no locale in `locals`), and a page's `Astro.rewrite('/404')` into it from an
+ * on-demand request is a ForbiddenRewrite, a 500 (astro/dist/core/rewrites/handler.js:29-33,
+ * Astro 7.4.2). Only the project's own route counts: Astro's built-in 404 is on-demand.
+ */
+export function assertNoPrerendered404(routes) {
+    const page = routes.find((route) => route.pattern === '/404' && route.isPrerendered && route.origin === 'project');
+    if (page) {
+        throw new Error(`[@edgekits/astro-i18n] ${page.entrypoint ?? 'src/pages/404.astro'} is prerendered: Astro serves a prerendered ` +
+            "404 page without the middleware, so it never gets the visitor's locale, and a page's `Astro.rewrite('/404')` " +
+            'into it is refused (ForbiddenRewrite, a 500). Remove `export const prerender = true` from the 404 page.');
+    }
+}
 /**
  * The Astro `i18n` block set when the project has none: locales and default from the
  * config; routed as locale-prefixed in both modes (the middleware redirects `/` itself in
@@ -86,10 +139,10 @@ export function localesDeclaration(locales) {
  * re-validate what `updateConfig` merges, so its schema defaults never fill a partial block.
  *
  * `prefixDefaultLocale: true` in 'prefix-except-default' too: Astro's own i18n check runs
- * after the middleware, on the rewritten URL (astro/dist/core/routing/handler.js:128-130),
- * and with `prefixDefaultLocale: false` the strategy `pathname-prefix-other-locales`
- * answers notFound to any path carrying the default locale (astro/dist/i18n/router.js:
- * 104-121) — the rewritten `/<default>/about/` is exactly that. With `true` the check
+ * after the middleware, on the rewritten URL (astro/dist/core/routing/handler.js:167-169,
+ * Astro 7.4.2), and with `prefixDefaultLocale: false` the strategy
+ * `pathname-prefix-other-locales` answers notFound to any path carrying the default locale
+ * (astro/dist/i18n/router.js:107-124) — the rewritten `/<default>/about/` is exactly that. With `true` the check
  * passes and `Astro.currentLocale` works on root pages.
  */
 export function astroI18n(config) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgekits/astro-i18n",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Edge-native i18n for Astro on Cloudflare Workers: translations in Workers KV, a per-namespace edge cache invalidated by the Purge API, and typed keys.",
   "keywords": [
     "astro",
@@ -24,7 +24,7 @@
     "url": "https://github.com/EdgeKits/i18n/issues"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=22.23.4"
   },
   "exports": {
     ".": {
@@ -57,14 +57,16 @@
     "format:check": "prettier --check ."
   },
   "dependencies": {
-    "@edgekits/i18n-core": "0.2.2"
+    "@edgekits/i18n-core": "0.3.0"
   },
   "peerDependencies": {
-    "@astrojs/cloudflare": "^14.3.0",
-    "astro": "^7.3.0",
-    "wrangler": "^4.125.0"
+    "@astrojs/cloudflare": "^14.4.0",
+    "astro": "^7.4.0",
+    "wrangler": "^4.152.0"
   },
   "devDependencies": {
-    "astro": "^7.3.8"
+    "@astrojs/cloudflare": "^14.4.2",
+    "astro": "^7.4.2",
+    "wrangler": "^4.152.0"
   }
 }

package/src/components/LanguageSwitcher.astro

@@ -111,6 +111,25 @@ const hasChoice = SUPPORTED_LOCALES.length > 1
   // cannot import the project's config.
   import type { Locale } from '../constants'
 
+  // The core's `localizedPath`, inlined (a client script imports types only): the page's
+  // path in `targetLang`, a file path (`/rss.xml`) without a trailing slash. The URL carries
+  // the current locale's prefix exactly when it has one (every locale in 'prefix', all but
+  // the default in 'prefix-except-default'), so `currentLang` is the only segment to strip.
+  // It receives pathnames only. `test/language-switcher-script.test.ts` compares it with the core.
+  function localizedPathOf(
+    pathname: string,
+    targetLang: string,
+    currentLang: string | undefined,
+    routing: string | undefined,
+    defaultLocale: string | undefined,
+  ): string {
+    const segments = pathname.split('/').filter(Boolean)
+    if (segments[0] === currentLang) segments.shift()
+    const isFile = /\.[a-z][a-z0-9]{0,10}$/i.test(pathname.slice(pathname.lastIndexOf('/') + 1))
+    const rest = segments.length > 0 ? `${segments.join('/')}${isFile ? '' : '/'}` : ''
+    return routing !== 'prefix' && targetLang === defaultLocale ? `/${rest}` : `/${targetLang}/${rest}`
+  }
+
   class LanguageSwitcher extends HTMLElement {
     private trigger: HTMLButtonElement | null = null
     private dropdown: HTMLElement | null = null
@@ -162,18 +181,6 @@ const hasChoice = SUPPORTED_LOCALES.length > 1
       this.dropdown.hidden ? this.open() : this.close()
     }
 
-    // The core's `localizedPath`, inlined (a client script imports types only): the page's
-    // path in `targetLang`. The URL carries the current locale's prefix exactly when it has
-    // one (every locale in 'prefix', all but the default in 'prefix-except-default'), so
-    // `data-current-lang` is the only segment to strip.
-    private localizedPath(pathname: string, targetLang: string): string {
-      const { currentLang, routing, defaultLocale } = this.dataset
-      const segments = pathname.split('/').filter(Boolean)
-      if (segments[0] === currentLang) segments.shift()
-      const rest = segments.length > 0 ? `${segments.join('/')}/` : ''
-      return routing !== 'prefix' && targetLang === defaultLocale ? `/${rest}` : `/${targetLang}/${rest}`
-    }
-
     private onSelect = (event: Event) => {
       const target = event.target as HTMLElement
       const button = target.closest<HTMLButtonElement>('[data-ls-item]')
@@ -189,9 +196,12 @@ const hasChoice = SUPPORTED_LOCALES.length > 1
       // must stay free of Set-Cookie so the HTML edge cache can serve it), so
       // the switcher is the place where the preference is born. Not httpOnly on
       // either side (cookie-storage.ts): the server validates it, never trusts it.
-      document.cookie = `${cookieName}=${lang}; path=/; max-age=${cookieMaxAge}; SameSite=Lax; Secure`
+      document.cookie = `${cookieName}=${lang}; path=/; max-age=${cookieMaxAge}; SameSite=Lax${location.protocol === 'https:' ? '; Secure' : ''}`
 
-      window.location.href = this.localizedPath(window.location.pathname, lang)
+      // The query string goes along (`?utm=…`); the hash names a part of this page, not the other.
+      const { currentLang, routing, defaultLocale } = this.dataset
+      window.location.href =
+        localizedPathOf(window.location.pathname, lang, currentLang, routing, defaultLocale) + window.location.search
     }
 
     private onDocumentClick = (event: MouseEvent) => {

package/src/integration/index.ts

@@ -38,6 +38,8 @@ export function edgekitsI18n(config: I18nConfig, options: EdgekitsI18nOptions =
           astroConfig.root,
         )
 
+        assertAstroRouting(astroConfig)
+
         // Astro sets `Astro.currentLocale` (read by `resolveLocale`) only with an `i18n`
         // block: set it when the project has none, check it when it has one.
         if (astroConfig.i18n) assertAstroI18n(astroConfig.i18n, i18nConfig)
@@ -56,6 +58,10 @@ export function edgekitsI18n(config: I18nConfig, options: EdgekitsI18nOptions =
           addMiddleware({ entrypoint: '@edgekits/astro-i18n/middleware', order: 'pre' })
         }
       },
+      'astro:routes:resolved': ({ routes }) => {
+        assertNoPrerendered404(routes)
+        if (i18nConfig.routing === 'prefix-except-default') assertNoPrerenderedLangRoute(routes)
+      },
       'astro:config:done': ({ injectTypes }) => {
         injectTypes({ filename: 'locales.d.ts', content: localesDeclaration(Object.keys(i18nConfig.languages)) })
         // The shipped runtime imports the virtual modules; a consumer's program needs their
@@ -104,6 +110,68 @@ export function localesDeclaration(locales: readonly string[]): string {
   ].join('\n')
 }
 
+/**
+ * The Astro settings the middleware cannot work under, refused at config time:
+ * - `trailingSlash: 'never'`: Astro removes a trailing slash before the middleware runs
+ *   (astro/dist/core/routing/handler.js:105-107, Astro 7.4.2), and the middleware adds it
+ *   back: every page would redirect forever. `'ignore'` (the default) and `'always'` work.
+ * - a `base` other than `/`: the middleware's paths and redirects assume the site's root.
+ */
+export function assertAstroRouting(astroConfig: Pick<AstroConfig, 'trailingSlash' | 'base'>): void {
+  if (astroConfig.trailingSlash === 'never') {
+    throw new Error(
+      "[@edgekits/astro-i18n] `trailingSlash: 'never'` is not supported: Astro removes the trailing slash " +
+        'before the middleware runs, and the middleware adds it back to every page, so each request would ' +
+        "redirect forever. Use 'ignore' (the default) or 'always'.",
+    )
+  }
+  if (astroConfig.base !== undefined && astroConfig.base !== '/') {
+    throw new Error(
+      `[@edgekits/astro-i18n] \`base: ${JSON.stringify(astroConfig.base)}\` is not supported: the middleware's ` +
+        'locale paths and redirects are built from the site root. Serve the site at the root of its host ' +
+        '(remove `base`, or set it to "/").',
+    )
+  }
+}
+
+/**
+ * In 'prefix-except-default' the default locale's pages render through a rewrite to
+ * `/<default>/…`, and Astro refuses a rewrite from an on-demand request into a
+ * prerendered route (ForbiddenRewrite, a 500: astro/dist/core/rewrites/handler.js:29-33,
+ * Astro 7.4.2). Every `[lang]` route must be on-demand.
+ */
+export function assertNoPrerenderedLangRoute(routes: ReadonlyArray<{ pattern: string; isPrerendered: boolean }>): void {
+  const prerendered = routes.find(
+    (route) => route.isPrerendered && (route.pattern === '/[lang]' || route.pattern.startsWith('/[lang]/')),
+  )
+  if (prerendered) {
+    throw new Error(
+      `[@edgekits/astro-i18n] ${prerendered.pattern} is prerendered: with routing 'prefix-except-default' the ` +
+        "default locale's pages render through a rewrite to /<default>/…, and Astro refuses a rewrite into a " +
+        "prerendered route (ForbiddenRewrite). Remove `export const prerender = true` from that page, or use routing 'prefix'.",
+    )
+  }
+}
+
+/**
+ * A prerendered 404 page, in either mode: Astro serves it as a static file without the
+ * middleware (no locale in `locals`), and a page's `Astro.rewrite('/404')` into it from an
+ * on-demand request is a ForbiddenRewrite, a 500 (astro/dist/core/rewrites/handler.js:29-33,
+ * Astro 7.4.2). Only the project's own route counts: Astro's built-in 404 is on-demand.
+ */
+export function assertNoPrerendered404(
+  routes: ReadonlyArray<{ pattern: string; isPrerendered: boolean; origin?: string; entrypoint?: string }>,
+): void {
+  const page = routes.find((route) => route.pattern === '/404' && route.isPrerendered && route.origin === 'project')
+  if (page) {
+    throw new Error(
+      `[@edgekits/astro-i18n] ${page.entrypoint ?? 'src/pages/404.astro'} is prerendered: Astro serves a prerendered ` +
+        "404 page without the middleware, so it never gets the visitor's locale, and a page's `Astro.rewrite('/404')` " +
+        'into it is refused (ForbiddenRewrite, a 500). Remove `export const prerender = true` from the 404 page.',
+    )
+  }
+}
+
 /**
  * The Astro `i18n` block set when the project has none: locales and default from the
  * config; routed as locale-prefixed in both modes (the middleware redirects `/` itself in
@@ -111,10 +179,10 @@ export function localesDeclaration(locales: readonly string[]): string {
  * re-validate what `updateConfig` merges, so its schema defaults never fill a partial block.
  *
  * `prefixDefaultLocale: true` in 'prefix-except-default' too: Astro's own i18n check runs
- * after the middleware, on the rewritten URL (astro/dist/core/routing/handler.js:128-130),
- * and with `prefixDefaultLocale: false` the strategy `pathname-prefix-other-locales`
- * answers notFound to any path carrying the default locale (astro/dist/i18n/router.js:
- * 104-121) — the rewritten `/<default>/about/` is exactly that. With `true` the check
+ * after the middleware, on the rewritten URL (astro/dist/core/routing/handler.js:167-169,
+ * Astro 7.4.2), and with `prefixDefaultLocale: false` the strategy
+ * `pathname-prefix-other-locales` answers notFound to any path carrying the default locale
+ * (astro/dist/i18n/router.js:107-124) — the rewritten `/<default>/about/` is exactly that. With `true` the check
  * passes and `Astro.currentLocale` works on root pages.
  */
 export function astroI18n(config: I18nConfig): NonNullable<AstroConfig['i18n']> {

package/src/middleware/i18n.ts

@@ -1,5 +1,6 @@
 import type { AstroCookies, MiddlewareHandler } from 'astro'
 import {
+  isFilePath,
   localizedPath,
   MARKDOWN_PATH,
   markdownRedirectTarget,
@@ -12,12 +13,12 @@ import { DEFAULT_LOCALE, type Locale } from '../constants'
 import { readCookieLang, setCookieLang, type CookieLang } from '../cookie-storage'
 import { resolveLocaleForTranslations } from '../resolve-locale'
 
-// Regex to identify public static assets (images, fonts, scripts, etc.)
-// These files should bypass i18n routing and locale detection.
-const PUBLIC_FILE_REGEX = /\.(ico|png|jpg|jpeg|svg|webp|gif|css|js|map|txt|xml|json|woff2?|avif|md)$/i
-
-// List of URL prefixes that should be ignored by the i18n middleware.
-// Includes API endpoints, internal Astro paths, and standard static routes.
+// List of URL prefixes that should be ignored by the i18n middleware, each matched on a
+// segment boundary (`/api` and `/api/…`, never `/apis/`).
+// Includes API endpoints, internal Astro paths, and standard static routes. Server islands
+// are fetched from `<base>/_server-islands/<component>` (astro/dist/runtime/server/render/
+// server-islands.js:153), a URL without a locale: they render with the default locale in
+// `locals` unless the page passes the locale as a prop.
 // The Vite dev-server prefixes (/@vite, /@id, /@fs, /src, /node_modules) make
 // dev survive `run_worker_first: ["/*"]` being left on: without them every
 // dev-module request fell through to the locale logic, got redirected to
@@ -29,7 +30,9 @@ const IGNORED_PREFIXES = [
   '/_astro',
   '/_image',
   '/_actions',
-  '/favicon',
+  '/_server-islands',
+  '/.well-known',
+  '/favicon.ico',
   '/@vite',
   '/@id',
   '/@fs',
@@ -37,6 +40,19 @@ const IGNORED_PREFIXES = [
   '/node_modules',
 ]
 
+// The error pages, at the root in both modes. Passed through untouched when requested
+// directly or through a page's `Astro.rewrite('/404')`, which re-runs the middleware on
+// `/404` (core/rewrites/handler.js:67-71). Astro's own `isRoute404` accepts `/404/` as well
+// (core/routing/internal/route-errors.js).
+const ERROR_PAGE = /^\/(404|500)\/?$/
+
+// When a route answers an empty 404 or 500, Astro renders the error page and runs the
+// middleware again for it with the ORIGINAL request (astro/dist/core/errors/
+// default-handler.js:68-80): the visitor's pathname, the error page's route pattern. The
+// locals the first pass set are still there, which tells it from a first pass on an
+// unmatched path (also routed to `/404`, with no locals yet).
+const ERROR_ROUTES = ['/404', '/500']
+
 // Extracts the context type from Astro's MiddlewareHandler for cleaner function signatures.
 type I18nMiddlewareContext = Parameters<MiddlewareHandler>[0]
 
@@ -74,15 +90,28 @@ export type I18nMiddlewareDeps = {
 // next visit to `/`, and the URL-wins cookie sync below would then overwrite that choice.
 //
 // Both kinds, in both routing modes, keep the query string (`?utm=…`, `?sent=1`).
-const REDIRECT_STATUS = import.meta.env?.DEV ? 302 : 301
+//
+// A request other than GET or HEAD (a form POST) keeps its method and body across the hop:
+// 308 for a permanent normalisation (307 under `astro dev`), 307 for a negotiated one.
+// A 301 or 302 would let the browser resend it as a GET without the body.
+const IS_DEV = !!import.meta.env?.DEV
+const REDIRECT_STATUS = IS_DEV ? 302 : 301
+
+const keepsMethod = (request: Request) => request.method !== 'GET' && request.method !== 'HEAD'
+
+// The status of a deterministic normalisation for this request.
+function permanentStatus(request: Request): 301 | 302 | 307 | 308 {
+  if (!keepsMethod(request)) return REDIRECT_STATUS
+  return IS_DEV ? 307 : 308
+}
 
 // A redirect whose target depends on the visitor: temporary, never stored by a shared
 // cache, and keyed on the request headers that chose it (the country is not a request
 // header, hence `no-store` rather than relying on Vary alone). `vary` names only the
 // headers that were consulted: the root of 'prefix-except-default' reads the cookie alone.
-function negotiatedRedirect(target: string, vary = 'Cookie, Accept-Language'): Response {
+function negotiatedRedirect(request: Request, target: string, vary = 'Cookie, Accept-Language'): Response {
   return new Response(null, {
-    status: 302,
+    status: keepsMethod(request) ? 307 : 302,
     headers: {
       Location: target,
       'Cache-Control': 'private, no-store',
@@ -91,7 +120,39 @@ function negotiatedRedirect(target: string, vary = 'Cookie, Accept-Language'): R
   })
 }
 
-const isIgnoredPrefix = (pathname: string) => IGNORED_PREFIXES.some((p) => pathname.startsWith(p))
+// Edits a response's headers in place, or on a copy when they are immutable (a response
+// from `fetch()`).
+function withHeaders(response: Response, edit: (headers: Headers) => void): Response {
+  try {
+    edit(response.headers)
+    return response
+  } catch {
+    const copy = new Response(response.body, response)
+    edit(copy.headers)
+    return copy
+  }
+}
+
+// `Vary: Cookie` added to whatever the response varies on already.
+function varyOnCookie(headers: Headers): void {
+  const vary = headers.get('Vary')
+  if (!vary) return headers.set('Vary', 'Cookie')
+  const fields = vary.split(',').map((field) => field.trim().toLowerCase())
+  if (!fields.includes('*') && !fields.includes('cookie')) headers.set('Vary', `${vary}, Cookie`)
+}
+
+// A response that sets the lang cookie is for one visitor: `private` replaces `public` and
+// `s-maxage` (a shared cache's directives); every other directive, `no-store` included, stays.
+function makePrivate(headers: Headers): void {
+  const kept = (headers.get('Cache-Control') ?? '')
+    .split(',')
+    .map((directive) => directive.trim())
+    .filter((directive) => directive !== '' && !/^(public|private|s-maxage=.*)$/i.test(directive))
+  headers.set('Cache-Control', ['private', ...kept].join(', '))
+}
+
+const isIgnoredPrefix = (pathname: string) =>
+  IGNORED_PREFIXES.some((p) => pathname === p || pathname.startsWith(`${p}/`))
 
 // The project's localized routes live under `src/pages/[lang]/`. `context.routePattern` is
 // the route Astro matched for the original URL, before any rewrite: a locale-less
@@ -104,12 +165,13 @@ const isLangRoute = (routePattern: string | undefined) =>
 // or its built-in one): astro/dist/core/routing/internal/astro-designed-error-pages.js.
 const NOT_FOUND_ROUTE = '/404'
 
-// Determines if the current request path matches static assets or ignored prefixes.
-// Returns true to skip i18n processing for this request.
+// Determines if the current request path is a file (any extension that starts with a
+// letter: the core's isFilePath) or an ignored prefix. Returns true to skip i18n
+// processing for this request.
 function shouldBypassI18n(pathname: string): boolean {
-  if (PUBLIC_FILE_REGEX.test(pathname)) return true
+  if (isFilePath(pathname)) return true
   if (isIgnoredPrefix(pathname)) return true
-  // Markdown endpoints: /en/blog/slug.md/ (with or without trailing slash)
+  // Markdown endpoints in the `.md/` form (`/en/blog/slug.md/`); `.md` is a file path
   if (MARKDOWN_PATH.test(pathname)) return true
   return false
 }
@@ -152,14 +214,15 @@ export function createI18nMiddleware(deps: I18nMiddlewareDeps): MiddlewareHandle
 
   // The `.md` redirect target, or null. 'prefix': the core's markdown-path.ts as is.
   // 'prefix-except-default': the same target without the default locale's prefix (through
-  // localizedPath, minus the trailing slash a `.md` path never has); a path already at
-  // `/<default>/…` is redirected too, since that is no longer canonical.
+  // localizedPath, which keeps a file path without a trailing slash; the `.md/` form loses
+  // its slash first); a path already at `/<default>/…` is redirected too, since that is no
+  // longer canonical.
   function markdownTarget(pathname: string): string | null {
     const target = markdownRedirectTarget(pathname, { isLocale, markdownLocale: deps.markdownLocale })
     if (deps.routing === 'prefix') return target
     if (!deps.markdownLocale || !MARKDOWN_PATH.test(pathname)) return null
 
-    const localized = localizedPath(deps.markdownLocale, target ?? pathname, pathOptions).slice(0, -1)
+    const localized = localizedPath(deps.markdownLocale, (target ?? pathname).replace(/\/+$/, ''), pathOptions)
     return localized === pathname ? null : localized
   }
 
@@ -187,7 +250,8 @@ export function createI18nMiddleware(deps: I18nMiddlewareDeps): MiddlewareHandle
     //     on the same host, a locale this site does not have) is corrected to the
     //     URL locale too, so a stale value never outlives the next request.
     const cookie = deps.readCookieLang(context.cookies)
-    if (cookie.present && cookie.locale !== urlLocale) {
+    const writesCookie = cookie.present && cookie.locale !== urlLocale
+    if (writesCookie) {
       deps.setCookieLang(context.cookies, urlLocale)
     }
     // Set uiLocale to Astro locals
@@ -198,11 +262,13 @@ export function createI18nMiddleware(deps: I18nMiddlewareDeps): MiddlewareHandle
 
     // Normalize trailing slash and structure
     const normalized = buildLocalizedPath(urlLocale, segments.slice(1))
-    if (pathname !== normalized) {
-      return context.redirect(normalized + url.search, REDIRECT_STATUS)
-    }
+    const response =
+      pathname !== normalized
+        ? context.redirect(normalized + url.search, permanentStatus(context.request))
+        : await next()
 
-    return await next()
+    // The Set-Cookie makes the response this visitor's: no shared cache may keep it.
+    return writesCookie ? withHeaders(response, makePrivate) : response
   }
 
   // 'prefix-except-default': the default locale at the root, the others under their prefix.
@@ -217,7 +283,10 @@ export function createI18nMiddleware(deps: I18nMiddlewareDeps): MiddlewareHandle
 
     // The default locale's prefix is not canonical: one permanent hop to the path without it.
     if (urlLocale === deps.defaultLocale) {
-      return context.redirect(localizedPath(deps.defaultLocale, pathname, pathOptions) + search, REDIRECT_STATUS)
+      return context.redirect(
+        localizedPath(deps.defaultLocale, pathname, pathOptions) + search,
+        permanentStatus(context.request),
+      )
     }
 
     if (urlLocale) {
@@ -231,26 +300,37 @@ export function createI18nMiddleware(deps: I18nMiddlewareDeps): MiddlewareHandle
     context.locals.translationLocale = deps.resolveLocaleForTranslations(deps.defaultLocale)
 
     const cookie = deps.readCookieLang(context.cookies)
+    let writesCookie = false
     if (cookie.present && cookie.locale !== deps.defaultLocale) {
       if (cookie.locale) {
-        return negotiatedRedirect(localizedPath(cookie.locale, pathname, pathOptions) + search, 'Cookie')
+        return negotiatedRedirect(
+          context.request,
+          localizedPath(cookie.locale, pathname, pathOptions) + search,
+          'Cookie',
+        )
       }
       // Present but invalid: corrected to the URL's locale, as serveLocalized does.
       deps.setCookieLang(context.cookies, deps.defaultLocale)
+      writesCookie = true
     }
 
     const normalized = localizedPath(deps.defaultLocale, pathname, pathOptions)
+    let response: Response
     if (pathname !== normalized) {
-      return context.redirect(normalized + search, REDIRECT_STATUS)
+      response = context.redirect(normalized + search, permanentStatus(context.request))
+    } else {
+      // The project's pages live under `src/pages/[lang]/`: render `/<default>/…` while the
+      // URL stays. `next(path)` rewrites without running the middleware again
+      // (astro/dist/core/middleware/astro-middleware.js:33-40, Astro 7.4.2) and keeps
+      // `locals`; `context.rewrite()` would re-run it (core/rewrites/handler.js:67-71).
+      // The rewritten URL is built from the string alone (core/routing/rewrite.js:22), and
+      // `context.url`, Astro.url and Actions' `?_action=` read it: the query goes in too.
+      // The page depends on the lang cookie (a valid other locale redirects away), so it
+      // varies on it.
+      response = withHeaders(await next(`/${deps.defaultLocale}${pathname}${search}`), varyOnCookie)
     }
 
-    // The project's pages live under `src/pages/[lang]/`: render `/<default>/…` while the
-    // URL stays. `next(path)` rewrites without running the middleware again
-    // (astro/dist/core/middleware/astro-middleware.js:33-40) and keeps `locals`;
-    // `context.rewrite()` would re-run it (astro/dist/core/rewrites/handler.js:67-71).
-    // The rewritten URL is built from the string alone (core/routing/rewrite.js:22), and
-    // `context.url`, Astro.url and Actions' `?_action=` read it: the query goes in too.
-    return await next(`/${deps.defaultLocale}${pathname}${search}`)
+    return writesCookie ? withHeaders(response, makePrivate) : response
   }
 
   // Main i18n middleware handler. Intercepts incoming requests, manages routing,
@@ -263,6 +343,27 @@ export function createI18nMiddleware(deps: I18nMiddlewareDeps): MiddlewareHandle
     const segments = pathname.split('/').filter(Boolean) // "/es/about/" -> ["es", "about"]
     const firstSegment = segments[0] ?? null
 
+    // The error pages: no redirect, no rewrite. On a re-entry for an error page the locals
+    // an earlier pass set (the visitor's locale) stay; a direct request gets the default.
+    const reentry = ERROR_ROUTES.includes(context.routePattern) && context.locals.uiLocale !== undefined
+    if (reentry || ERROR_PAGE.test(pathname)) {
+      if (context.locals.uiLocale === undefined) {
+        context.locals.uiLocale = deps.defaultLocale
+        context.locals.translationLocale = deps.resolveLocaleForTranslations(deps.defaultLocale)
+      }
+      return await next()
+    }
+
+    // A locale segment in another case (`/DE/…`, `/pt-BR/…`): one permanent hop to the
+    // canonical lower-case path (without the default's prefix in 'prefix-except-default').
+    if (firstSegment && !isLocale(firstSegment) && isLocale(firstSegment.toLowerCase())) {
+      const lowered = `/${[firstSegment.toLowerCase(), ...segments.slice(1)].join('/')}${pathname.endsWith('/') ? '/' : ''}`
+      return context.redirect(
+        localizedPath(firstSegment.toLowerCase(), lowered, pathOptions) + url.search,
+        permanentStatus(context.request),
+      )
+    }
+
     // 2. SAFETY NET (For static file 404 pages)
     // Attempt to infer the locale from the URL, or fallback to the default.
     let safeLocale = deps.defaultLocale
@@ -283,7 +384,7 @@ export function createI18nMiddleware(deps: I18nMiddlewareDeps): MiddlewareHandle
       // (the core's markdown-path.ts). Without `markdownLocale` they pass through untouched.
       const target = markdownTarget(pathname)
       if (target) {
-        return context.redirect(target + url.search, REDIRECT_STATUS)
+        return context.redirect(target + url.search, permanentStatus(context.request))
       }
 
       // 'prefix-except-default': the default locale's `[lang]` routes answer at the root,
@@ -295,8 +396,13 @@ export function createI18nMiddleware(deps: I18nMiddlewareDeps): MiddlewareHandle
       let rewrite: string | undefined
       if (deps.routing !== 'prefix') {
         const markdown = MARKDOWN_PATH.test(pathname)
+        // Built from the path's segments (localizedPath), never by slicing the pathname:
+        // `/en//evil.com/x.png` must not become the protocol-relative `//evil.com/x.png`.
         if (firstSegment === deps.defaultLocale && !markdown && isLangRoute(context.routePattern)) {
-          return context.redirect(pathname.slice(deps.defaultLocale.length + 1) + url.search, REDIRECT_STATUS)
+          return context.redirect(
+            localizedPath(deps.defaultLocale, pathname, pathOptions) + url.search,
+            permanentStatus(context.request),
+          )
         }
         const langRouteOrNone = isLangRoute(context.routePattern) || context.routePattern === NOT_FOUND_ROUTE
         if (
@@ -310,13 +416,13 @@ export function createI18nMiddleware(deps: I18nMiddlewareDeps): MiddlewareHandle
 
       const contentType = response.headers.get('content-type') || ''
       const isHtml = contentType.includes('text/html')
-      const isRedirect = response.status >= 300 && response.status < 400
 
-      // If Astro attempts to return HTML for a static/API request (and it's not a redirect),
-      // it means the file wasn't found and Astro rendered a fallback page (404.astro or catch-all).
-      // We strictly intercept this and return a lightweight text-based 404 instead.
+      // If Astro answers a static/API request with a 404 HTML page, the file wasn't found
+      // and Astro rendered its fallback (404.astro). We intercept this and return a
+      // lightweight text-based 404 instead: an HTML response with any other status (a
+      // server island, an endpoint that renders HTML) is the route's own answer and passes.
       // Why? To mitigate Directory Bruteforcing / Fuzzing attacks and save resources.
-      if (isHtml && !isRedirect) {
+      if (isHtml && response.status === 404) {
         // Aggressively save Worker CPU cycles for missing static files
         return new Response('Not found', {
           status: 404,
@@ -337,7 +443,7 @@ export function createI18nMiddleware(deps: I18nMiddlewareDeps): MiddlewareHandle
     if (!firstSegment) {
       const target = buildLocalizedPath(fallbackLocale, [])
       if (pathname !== target) {
-        return negotiatedRedirect(target + url.search)
+        return negotiatedRedirect(context.request, target + url.search)
       }
       return await next()
     }
@@ -353,7 +459,7 @@ export function createI18nMiddleware(deps: I18nMiddlewareDeps): MiddlewareHandle
     const target = buildLocalizedPath(fallbackLocale, segments)
 
     if (pathname !== target) {
-      return negotiatedRedirect(target + url.search)
+      return negotiatedRedirect(context.request, target + url.search)
     }
 
     return await next()

package/src/translations-keys.ts

@@ -6,6 +6,6 @@ import { i18n } from './instance'
  * Purge API.
  *
  * Formats: <keyPrefix>:<namespace>:<locale> and
- * https://<keyPrefix>/<encodeURIComponent(i18n:<locale>:<namespace>)>
+ * https://<keyPrefix>/<encodeURIComponent(i18n:v2:<locale>:<namespace>)>
  */
 export const { buildTranslationKvKey, buildTranslationCacheUrl, buildTranslationCacheRequest } = i18n