@edgekits/astro-i18n 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -4,6 +4,42 @@ 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.8 — 2026-10-18
+
+### Added
+
+- `migrate` checks `keyPrefix` against the purge zone before purging. It reads the zone's name (`GET /zones/{id}`, same token) and warns when `keyPrefix` is a hostname with a dot that is neither the zone name nor a subdomain of it (case-insensitive, on a label boundary: `edgekits.dev.evil.com` warns against `edgekits.dev`). The Purge API answers success even for a URL on another proxied zone, so the name is the only thing left to check. The check needs Zone › Zone › Read on the token; without it (or on any lookup failure) `migrate` prints one info line saying the check was skipped. Either way the purge and the `.i18n-hashes.json` write behave as before.
+
+### Fixed
+
+- `LanguageSwitcher`: under `compressHTML` each item rendered two spaces before its label, because a JSX comment among the button's children split the whitespace run. The comment now sits in the `map` callback. 0.1.7's note that the markup "stays the same apart from the item labels" missed this one extra space per item.
+
+### Docs
+
+- The `keyPrefix` rule corrected (README "Deployment targets", config table, requirements and the skill guide's prerequisites). A unique name without a dot is valid: single-file purge from your zone reaches any URL whose hostname is no proxied Cloudflare zone. The danger is a hostname that is another proxied Cloudflare zone: its URLs can be purged only from that zone, and the API cannot tell you. Zone › Zone › Read on the token is optional and enables the `migrate` check.
+
+## 0.1.7 — 2026-10-17
+
+### Fixed
+
+- Accept-Language: a regional tag now reaches its language. The middleware reads the header itself (new `src/accept-language.ts`): each tag in `q` order, the full tag, then its language part, first match wins. `es-MX` now lands on `/es/`, and `es-MX, en;q=0.8` on `es` rather than `en`. The previous language-part fallback never ran for regional tags: it read Astro's `preferredLocale`, which keeps only tags equal to a configured locale before choosing, so `es-MX` arrived as undefined and fell through to geo or the default.
+- The cascade order is unchanged: cookie, Accept-Language, then the country only when no tag matched, then `defaultLocale`. Astro's `preferredLocale` is no longer read; the integration still sets Astro's `i18n` block when the project has none, for `Astro.currentLocale`.
+
+### Components
+
+- `LanguageSwitcher` takes `texts={{ trigger }}` for the toggle's `aria-label`. The default, `Switch language`, is unchanged, so existing markup stays the same apart from the item labels below.
+- Each item's label `span` carries `lang` with its locale, so a screen reader says `Deutsch` or `日本語` in that language.
+
+### Config
+
+- `defineI18nConfig` rejects a `languages` key that is not all-lowercase (`pt-BR`), naming the key and the lowercase form. Lowercase was documented but not enforced; `toIetfTag` relies on it.
+
+### Docs
+
+- README "Deployment targets": Workers on your own zone, Cloudflare for SaaS (`keyPrefix` inside the purge zone, one tenant per build), Workers for Platforms trusted (`keyPrefix` unique per tenant) and untrusted (no geo step, no `caches.default`: set `I18N_CACHE=off`).
+- "Installing it": a marketplace added from the `/plugin` panel lives in user settings; how a repository declares it under `extraKnownMarketplaces`.
+- The skill's `seo.md` documents `texts.trigger`; the starter `common.json` has `switchLanguage`.
+
 ## 0.1.6 — 2026-10-16
 
 No runtime changes: the `astro-i18n` skill only, found on the first one-prompt run for the tutorial.

package/README.md

@@ -22,7 +22,8 @@ The design is explained in the edgekits.dev series:
 - 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.
+  the Zone › Cache Purge permission. Zone › Zone › Read is optional; with it, `migrate` checks
+  `keyPrefix` against the zone's name.
 
 ## Quick start
 
@@ -73,18 +74,18 @@ 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      |              | 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)                                                 |
+| 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`                  | 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)                                                                                                                                               |
 
 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
@@ -117,7 +118,7 @@ The integration sets up:
 - `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
+  Astro needs it to set `Astro.currentLocale`, which `resolveLocale` reads. 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;
@@ -261,11 +262,11 @@ 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 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.
+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.
 
 ```ts
 // edgekits-i18n.config.ts
@@ -325,6 +326,11 @@ Tailwind. Pass classes per element through the `classes` prop; a slot you leave
 | `itemLabel`   | the `span` holding the flag and the language name                        |
 | `activeIcon`  | the current-language marker (your `activeIcon` component or the default) |
 
+`LanguageSwitcher` has one string of its own, the trigger's `aria-label`, `Switch language` by
+default. Translate it through `texts={{ trigger: … }}`, from a namespace you fetch yourself (the
+package fetches nothing for its components). Each language name renders with `lang` set to its
+locale, so a screen reader says `Deutsch` or `日本語` in that language.
+
 `MissingTranslationBanner` has one slot, `root` (the banner `div`).
 
 Hooks rendered whether or not you pass `classes`, for CSS or your own scripts:
@@ -394,6 +400,37 @@ name. A locale without a `countryCode` gets the name alone, and so does every lo
 pass no `flag`. A recipe that copies only the SVGs your locales use from the `flag-icons` npm
 package is under [Flags in the switcher](#flags-in-the-switcher) in "Using the skill".
 
+### Deployment targets
+
+**Workers Free or Paid, on your own zone.** Everything on this page applies as written.
+
+**Cloudflare for SaaS.** The Worker is the SaaS zone's fallback origin on a `*/*` route. It is
+a regular Worker: `request.cf`, `caches.default` and `env` behave as usual, and the host-only
+language cookie and the relative redirects keep visitors on their custom hostname. Two
+constraints:
+
+- `keyPrefix` is the host of every cache URL that `migrate` purges from the zone
+  `CLOUDFLARE_ZONE_ID` names. Recommended: a hostname of that zone (the zone name or a
+  subdomain). A unique name without a dot works too: single-file purge from your zone reaches
+  any URL whose hostname is no proxied Cloudflare zone. Never another domain that is a proxied
+  Cloudflare zone: its URLs can be purged only from that zone, by its owner, and the Purge API
+  reports success anyway. When the token can read the zone (Zone › Zone › Read), `migrate`
+  warns about a dotted `keyPrefix` outside the zone.
+- One tenant per build. `keyPrefix`, the locales, `defaultLocale` and `countryToLocale` are
+  build-time constants, so one Worker serving many custom hostnames serves the same translation
+  set to all of them.
+
+**Workers for Platforms, trusted namespace.** `request.cf` and `caches.default` are available.
+The Cache API is shared across the namespace and the cache URL is `https://<keyPrefix>/…`, so
+`keyPrefix` must be unique per tenant, or two tenants read each other's translations from the
+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.
+
 <!-- skill-guide:start -->
 
 ## Using the skill
@@ -448,6 +485,28 @@ turns the plugin on there, under `enabledPlugins` (`"astro-i18n@edgekits": true`
 honours those entries for a teammate once they trust the folder, but it does not download the
 plugin for them: each teammate runs the same `claude plugin install … --scope project` once.
 
+A marketplace added from the `/plugin` panel, or with `/plugin marketplace add`, is stored in
+your user settings, even when you then install the plugin at project scope, so the committed
+`.claude/settings.json` holds only `enabledPlugins`. On a fresh clone a teammate therefore first
+adds the marketplace: `/plugin marketplace add EdgeKits/skills`, or the CLI line with
+`--scope project` above. Declaring it in `.claude/settings.json` under `extraKnownMarketplaces`,
+keyed by the marketplace's name as in the block below, spares them that step once they trust the
+folder. In both cases the plugin itself is still installed once per contributor with
+`claude plugin install astro-i18n@edgekits --scope project`, as the paragraph above says.
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "edgekits": {
+      "source": { "source": "github", "repo": "EdgeKits/skills" }
+    }
+  },
+  "enabledPlugins": {
+    "astro-i18n@edgekits": true
+  }
+}
+```
+
 Any other agent, with the [skills CLI](https://skills.sh):
 
 ```sh
@@ -467,6 +526,8 @@ npx skills add EdgeKits/astro-i18n --skill astro-i18n
 - A Cloudflare account. Local development needs none until you create the real KV namespace.
 - For `edgekits-i18n migrate` (pushing copy to production): the site on a proxied Cloudflare
   zone (orange cloud), that zone's ID, and an API token with the Zone › Cache Purge permission.
+  Zone › Zone › Read on the same token is optional: with it, `migrate` checks `keyPrefix`
+  against the zone's name.
 
 ### First run on a fresh site
 

package/dist/cli/index.js

@@ -8,6 +8,7 @@ import { diffHashes, purgeUrlsFor } from "./hashes.js";
 import { CONFIG_FILE, loadI18nConfig } from "./load-config.js";
 import { purgeTranslationsCache } from "./purge.js";
 import { getKvNamespaceId, getWranglerVar, KV_BINDING, resolveWranglerBin } from "./wrangler.js";
+import { checkKeyPrefixZone } from "./zone.js";
 const HELP = `Usage: edgekits-i18n <command> [--fallbacks]
 
 Reads ${CONFIG_FILE} and <localesDir>/<locale>/<namespace>.json from the current directory.
@@ -144,7 +145,8 @@ async function run(command, args) {
     console.log('Generated:\n' + outputs.map((p) => `- ${path.relative(ROOT, p).split(path.sep).join('/')}`).join('\n'));
     // -------------------------------------------------------------------------
     // 5. Push to KV + purge changed cache entries via Cloudflare API
-    //    seed    → local KV only, no purge (local KV; the edge cache is not involved), hashes untouched
+    //    seed    → local KV only, no purge, hashes untouched (a warm local cache under
+    //              `astro dev` is the consumer's to drop: `I18N_CACHE=off`, restart)
     //    migrate → remote KV + Cloudflare Purge API, hashes written on success
     // -------------------------------------------------------------------------
     if (!shouldDeploy) {
@@ -207,7 +209,8 @@ async function deploy({ config, kvId, wranglerBin, isLocal, changedKeys, current
         process.exit(1);
     }
     if (isLocal) {
-        // Local KV: no purge (the edge cache is not involved), and the hashes describe production only.
+        // Local KV: no purge (a warm local cache under `astro dev` is the consumer's to drop),
+        // and the hashes describe production only.
         console.log('[i18n] .i18n-hashes.json left untouched (local seed).');
         return;
     }
@@ -254,6 +257,9 @@ async function deploy({ config, kvId, wranglerBin, isLocal, changedKeys, current
                 'Skipping cache purge — hash file NOT updated. Re-run `edgekits-i18n migrate` after setting the secret.');
         }
         else {
+            // Advisory: the Purge API reports success even for URLs it cannot reach, so the
+            // name is all there is to check. Never decides shouldWriteHashes.
+            await checkKeyPrefixZone(config.keyPrefix, zoneId, apiToken);
             console.log(`[i18n] Purging ${purgeUrls.length} cache entries via Cloudflare API...`);
             const purgeSuccess = await purgeTranslationsCache(zoneId, apiToken, purgeUrls);
             if (purgeSuccess) {

package/dist/cli/key-prefix-check.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The warning `migrate` prints when `keyPrefix` is a dotted hostname outside `zoneName`,
+ * or null when it is dotless, the zone name itself, or a subdomain of it (label
+ * boundary, case-insensitive, both sides trimmed). Pure: no network, no `process`.
+ */
+export declare function keyPrefixZoneWarning(keyPrefix: string, zoneName: string): string | null;

package/dist/cli/key-prefix-check.js

@@ -0,0 +1,27 @@
+// ---------------------------------------------------------------------------
+// keyPrefix against the purge zone
+//
+// Every cache URL is https://<keyPrefix>/..., and `migrate` purges those URLs from the
+// zone CLOUDFLARE_ZONE_ID names. A URL a Worker cached is purged from the Worker's own
+// zone when its hostname is no Cloudflare zone or a non-proxied one. A hostname that is
+// an active proxied Cloudflare zone can be purged only from that zone, by its owner, and
+// the Purge API answers `success: true` either way. The response cannot show the miss,
+// so the only check left is the name. A proxied zone always has a dot: a dotless
+// keyPrefix never collides with one.
+// ---------------------------------------------------------------------------
+/**
+ * The warning `migrate` prints when `keyPrefix` is a dotted hostname outside `zoneName`,
+ * or null when it is dotless, the zone name itself, or a subdomain of it (label
+ * boundary, case-insensitive, both sides trimmed). Pure: no network, no `process`.
+ */
+export function keyPrefixZoneWarning(keyPrefix, zoneName) {
+    const host = keyPrefix.trim().toLowerCase();
+    const zone = zoneName.trim().toLowerCase();
+    if (!host.includes('.') || host === zone || host.endsWith(`.${zone}`))
+        return null;
+    return (`[i18n] ⚠️  keyPrefix "${keyPrefix.trim()}" is a hostname outside the zone the purge is issued against (${zoneName.trim()}).\n` +
+        '        The Purge API answers success either way, so this run cannot tell whether the edge cache was purged.\n' +
+        `        It is harmless only if "${keyPrefix.trim()}" is no proxied Cloudflare zone: a URL on a proxied zone\n` +
+        '        can be purged only from that zone, by its owner. Fix: a keyPrefix inside the zone (its name or a\n' +
+        '        subdomain), or a unique name without a dot.');
+}

package/dist/cli/zone.d.ts

@@ -0,0 +1,21 @@
+export type ZoneDeps = {
+    fetch?: (input: string, init: RequestInit) => Promise<Response>;
+};
+/**
+ * Read the zone's name: `GET /zones/{zoneId}`, `result.name`. Needs Zone › Zone › Read
+ * on the token. Never throws: any failure (non-2xx, network error, unexpected body)
+ * comes back as `{ error }`.
+ *
+ * `deps` replaces `fetch` in tests.
+ */
+export declare function readZoneName(zoneId: string, apiToken: string, deps?: ZoneDeps): Promise<{
+    name: string;
+} | {
+    error: string;
+}>;
+/**
+ * Print the keyPrefix warning when `keyPrefix` lies outside the zone, or one info line
+ * when the zone name cannot be read. Advisory only: it returns nothing, and the purge
+ * runs the same either way.
+ */
+export declare function checkKeyPrefixZone(keyPrefix: string, zoneId: string, apiToken: string, deps?: ZoneDeps): Promise<void>;

package/dist/cli/zone.js

@@ -0,0 +1,42 @@
+import { keyPrefixZoneWarning } from "./key-prefix-check.js";
+/**
+ * Read the zone's name: `GET /zones/{zoneId}`, `result.name`. Needs Zone › Zone › Read
+ * on the token. Never throws: any failure (non-2xx, network error, unexpected body)
+ * comes back as `{ error }`.
+ *
+ * `deps` replaces `fetch` in tests.
+ */
+export async function readZoneName(zoneId, apiToken, deps = {}) {
+    const { fetch: fetchFn = fetch } = deps;
+    try {
+        const response = await fetchFn(`https://api.cloudflare.com/client/v4/zones/${zoneId}`, {
+            method: 'GET',
+            headers: { Authorization: `Bearer ${apiToken}` },
+        });
+        if (!response.ok)
+            return { error: `HTTP ${response.status}` };
+        const body = (await response.json());
+        const name = body?.result?.name;
+        if (typeof name !== 'string' || name.trim() === '')
+            return { error: 'no result.name in the response' };
+        return { name };
+    }
+    catch (err) {
+        return { error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * Print the keyPrefix warning when `keyPrefix` lies outside the zone, or one info line
+ * when the zone name cannot be read. Advisory only: it returns nothing, and the purge
+ * runs the same either way.
+ */
+export async function checkKeyPrefixZone(keyPrefix, zoneId, apiToken, deps = {}) {
+    const zone = await readZoneName(zoneId, apiToken, deps);
+    if ('error' in zone) {
+        console.log(`[i18n] ℹ️  Could not read the zone name (${zone.error}), so the keyPrefix check was skipped (needs Zone › Zone › Read on the token).`);
+        return;
+    }
+    const warning = keyPrefixZoneWarning(keyPrefix, zone.name);
+    if (warning)
+        console.warn(warning);
+}

package/dist/integration/index.js

@@ -19,8 +19,8 @@ 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);
-                // Astro computes `preferredLocale` (the middleware's Accept-Language step) only
-                // with an `i18n` block: set it when the project has none, check it when it has one.
+                // 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);
                 updateConfig({

package/dist/types.js

@@ -17,6 +17,12 @@ export function defineI18nConfig(config) {
     if (locales.length === 0) {
         throw new Error('[@edgekits/astro-i18n] `languages` must define at least one locale.');
     }
+    // Lowercase everywhere (config, `locales/` folders, URLs); `toIetfTag` relies on it.
+    for (const locale of locales) {
+        if (locale !== locale.toLowerCase()) {
+            throw new Error(`[@edgekits/astro-i18n] \`languages\` key "${locale}" is not lowercase (use "${locale.toLowerCase()}").`);
+        }
+    }
     if (!locales.includes(config.defaultLocale)) {
         throw new Error(`[@edgekits/astro-i18n] \`defaultLocale\` "${config.defaultLocale}" is not one of \`languages\`: ${locales.join(', ')}.`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgekits/astro-i18n",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "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",

package/src/accept-language.ts

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

package/src/cli/index.ts

@@ -19,6 +19,7 @@ import { diffHashes, purgeUrlsFor, type HashMap } from './hashes.ts'
 import { CONFIG_FILE, loadI18nConfig } from './load-config.ts'
 import { purgeTranslationsCache } from './purge.ts'
 import { getKvNamespaceId, getWranglerVar, KV_BINDING, resolveWranglerBin } from './wrangler.ts'
+import { checkKeyPrefixZone } from './zone.ts'
 
 const HELP = `Usage: edgekits-i18n <command> [--fallbacks]
 
@@ -197,7 +198,8 @@ async function run(command: Command, args: string[]): Promise<void> {
 
   // -------------------------------------------------------------------------
   // 5. Push to KV + purge changed cache entries via Cloudflare API
-  //    seed    → local KV only, no purge (local KV; the edge cache is not involved), hashes untouched
+  //    seed    → local KV only, no purge, hashes untouched (a warm local cache under
+  //              `astro dev` is the consumer's to drop: `I18N_CACHE=off`, restart)
   //    migrate → remote KV + Cloudflare Purge API, hashes written on success
   // -------------------------------------------------------------------------
 
@@ -289,7 +291,8 @@ async function deploy({
   }
 
   if (isLocal) {
-    // Local KV: no purge (the edge cache is not involved), and the hashes describe production only.
+    // Local KV: no purge (a warm local cache under `astro dev` is the consumer's to drop),
+    // and the hashes describe production only.
     console.log('[i18n] .i18n-hashes.json left untouched (local seed).')
     return
   }
@@ -344,6 +347,10 @@ async function deploy({
           'Skipping cache purge — hash file NOT updated. Re-run `edgekits-i18n migrate` after setting the secret.',
       )
     } else {
+      // Advisory: the Purge API reports success even for URLs it cannot reach, so the
+      // name is all there is to check. Never decides shouldWriteHashes.
+      await checkKeyPrefixZone(config.keyPrefix, zoneId, apiToken)
+
       console.log(`[i18n] Purging ${purgeUrls.length} cache entries via Cloudflare API...`)
       const purgeSuccess = await purgeTranslationsCache(zoneId, apiToken, purgeUrls)
 

package/src/cli/key-prefix-check.ts

@@ -0,0 +1,31 @@
+// ---------------------------------------------------------------------------
+// keyPrefix against the purge zone
+//
+// Every cache URL is https://<keyPrefix>/..., and `migrate` purges those URLs from the
+// zone CLOUDFLARE_ZONE_ID names. A URL a Worker cached is purged from the Worker's own
+// zone when its hostname is no Cloudflare zone or a non-proxied one. A hostname that is
+// an active proxied Cloudflare zone can be purged only from that zone, by its owner, and
+// the Purge API answers `success: true` either way. The response cannot show the miss,
+// so the only check left is the name. A proxied zone always has a dot: a dotless
+// keyPrefix never collides with one.
+// ---------------------------------------------------------------------------
+
+/**
+ * The warning `migrate` prints when `keyPrefix` is a dotted hostname outside `zoneName`,
+ * or null when it is dotless, the zone name itself, or a subdomain of it (label
+ * boundary, case-insensitive, both sides trimmed). Pure: no network, no `process`.
+ */
+export function keyPrefixZoneWarning(keyPrefix: string, zoneName: string): string | null {
+  const host = keyPrefix.trim().toLowerCase()
+  const zone = zoneName.trim().toLowerCase()
+
+  if (!host.includes('.') || host === zone || host.endsWith(`.${zone}`)) return null
+
+  return (
+    `[i18n] ⚠️  keyPrefix "${keyPrefix.trim()}" is a hostname outside the zone the purge is issued against (${zoneName.trim()}).\n` +
+    '        The Purge API answers success either way, so this run cannot tell whether the edge cache was purged.\n' +
+    `        It is harmless only if "${keyPrefix.trim()}" is no proxied Cloudflare zone: a URL on a proxied zone\n` +
+    '        can be purged only from that zone, by its owner. Fix: a keyPrefix inside the zone (its name or a\n' +
+    '        subdomain), or a unique name without a dot.'
+  )
+}

package/src/cli/zone.ts

@@ -0,0 +1,64 @@
+import { keyPrefixZoneWarning } from './key-prefix-check.ts'
+
+// ---------------------------------------------------------------------------
+// Zone name lookup for the keyPrefix check (migrate only)
+// ---------------------------------------------------------------------------
+
+export type ZoneDeps = {
+  fetch?: (input: string, init: RequestInit) => Promise<Response>
+}
+
+/**
+ * Read the zone's name: `GET /zones/{zoneId}`, `result.name`. Needs Zone › Zone › Read
+ * on the token. Never throws: any failure (non-2xx, network error, unexpected body)
+ * comes back as `{ error }`.
+ *
+ * `deps` replaces `fetch` in tests.
+ */
+export async function readZoneName(
+  zoneId: string,
+  apiToken: string,
+  deps: ZoneDeps = {},
+): Promise<{ name: string } | { error: string }> {
+  const { fetch: fetchFn = fetch } = deps
+
+  try {
+    const response = await fetchFn(`https://api.cloudflare.com/client/v4/zones/${zoneId}`, {
+      method: 'GET',
+      headers: { Authorization: `Bearer ${apiToken}` },
+    })
+    if (!response.ok) return { error: `HTTP ${response.status}` }
+
+    const body = (await response.json()) as { result?: { name?: unknown } } | null
+    const name = body?.result?.name
+    if (typeof name !== 'string' || name.trim() === '') return { error: 'no result.name in the response' }
+
+    return { name }
+  } catch (err) {
+    return { error: err instanceof Error ? err.message : String(err) }
+  }
+}
+
+/**
+ * Print the keyPrefix warning when `keyPrefix` lies outside the zone, or one info line
+ * when the zone name cannot be read. Advisory only: it returns nothing, and the purge
+ * runs the same either way.
+ */
+export async function checkKeyPrefixZone(
+  keyPrefix: string,
+  zoneId: string,
+  apiToken: string,
+  deps: ZoneDeps = {},
+): Promise<void> {
+  const zone = await readZoneName(zoneId, apiToken, deps)
+
+  if ('error' in zone) {
+    console.log(
+      `[i18n] ℹ️  Could not read the zone name (${zone.error}), so the keyPrefix check was skipped (needs Zone › Zone › Read on the token).`,
+    )
+    return
+  }
+
+  const warning = keyPrefixZoneWarning(keyPrefix, zone.name)
+  if (warning) console.warn(warning)
+}

package/src/components/LanguageSwitcher.astro

@@ -17,9 +17,12 @@ interface Props {
   classes?: Partial<
     Record<'root' | 'trigger' | 'triggerIcon' | 'dropdown' | 'item' | 'itemActive' | 'itemLabel' | 'activeIcon', string>
   >
+  // The component's own words, like MissingTranslationBanner's `texts`: the engine fetches
+  // nothing and assumes no namespace. `trigger` is the toggle's aria-label.
+  texts?: { trigger?: string }
 }
 
-const { flag: Flag, triggerIcon: TriggerIcon, activeIcon: ActiveIcon, classes = {} } = Astro.props
+const { flag: Flag, triggerIcon: TriggerIcon, activeIcon: ActiveIcon, classes = {}, texts } = Astro.props
 const { uiLocale: currentLang } = Astro.locals
 ---
 
@@ -36,7 +39,7 @@ const { uiLocale: currentLang } = Astro.locals
       class={classes.trigger}
       aria-haspopup="true"
       aria-expanded="false"
-      aria-label="Switch language"
+      aria-label={texts?.trigger ?? 'Switch language'}
     >
       {
         TriggerIcon ? (
@@ -66,6 +69,9 @@ const { uiLocale: currentLang } = Astro.locals
           const label = LANGUAGES[locale]
           const flagCode = label.countryCode
 
+          // The label is the language's own name: `lang` lets a screen reader say it in that
+          // language. (A comment here, not among the button's children: there it splits the
+          // whitespace run, and compressHTML keeps two spaces before the label.)
           return (
             <button
               type="button"
@@ -76,7 +82,7 @@ const { uiLocale: currentLang } = Astro.locals
               role="menuitem"
               disabled={isActive}
             >
-              <span class={classes.itemLabel}>
+              <span class={classes.itemLabel} lang={locale}>
                 {Flag && flagCode && <Flag code={flagCode} size={16} />}
                 {label.name}
               </span>

package/src/fetcher.ts

@@ -61,8 +61,9 @@ export async function fetchTranslations<N extends Namespace>(
   const { cache } = getEdgeCache()
 
   if (!cache) {
-    // Cache API unavailable (e.g. Astro dev server without Miniflare)
-    debug('i18n Cache API unavailable, using KV only', {
+    // `caches.default` absent (e.g. an untrusted Workers for Platforms namespace): read KV
+    // directly. The package does not use `caches.open()`.
+    debug('i18n caches.default absent, reading KV directly', {
       locale,
       namespaces,
     })

package/src/integration/index.ts

@@ -38,8 +38,8 @@ export function edgekitsI18n(config: I18nConfig, options: EdgekitsI18nOptions =
           astroConfig.root,
         )
 
-        // Astro computes `preferredLocale` (the middleware's Accept-Language step) only
-        // with an `i18n` block: set it when the project has none, check it when it has one.
+        // 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)
 
         updateConfig({

package/src/locale-fallback.ts

@@ -5,19 +5,19 @@
  *
  * Order (unchanged from the middleware):
  *   1. the lang cookie, if valid;
- *   2. the preferred locale (the middleware passes Astro's `preferredLocale`: its match of
- *      Accept-Language against the project's Astro `i18n.locales`, undefined when nothing
- *      matches or `i18n` is not configured), full match, then its language part
- *      ('pt-br' -> 'pt');
- *   3. ONLY when there is no preferred locale at all: the Cloudflare geo-IP country,
+ *   2. the Accept-Language header (the middleware passes the request header): each tag in
+ *      `q` order, full tag, then its language part ('es-mx' -> 'es'); the first tag that
+ *      names a supported locale wins (accept-language.ts);
+ *   3. ONLY when no tag matched (or there is no header): the Cloudflare geo-IP country,
  *      through the project's `countryToLocale` table (skipped without one);
  *   4. the default locale.
- * A preferred locale that does not parse goes straight to 4: geo is not consulted.
  */
 
+import { matchAcceptLanguage } from './accept-language'
+
 export type FallbackInputs<L extends string> = {
   cookieLocale: () => L | null
-  preferredLocale: () => string | undefined
+  acceptLanguage: () => string | null
   country: () => unknown
 }
 
@@ -32,17 +32,10 @@ export function resolveFallbackLocale<L extends string>(inputs: FallbackInputs<L
   const cookieLocale = inputs.cookieLocale()
   if (cookieLocale) return cookieLocale
 
-  const browserRaw = inputs.preferredLocale()
-  if (browserRaw) {
-    // Currently we support 2-chars locales only.
-    // 1) Try full match (for cases where you actually have 'pt-br' in SUPPORTED_LOCALES)
-    const full = options.parseLocale(browserRaw)
-    if (full) return full
+  const browser = matchAcceptLanguage(inputs.acceptLanguage(), options.parseLocale)
+  if (browser) return browser
 
-    // 2) Fallback: language part only, e.g. 'pt-br' -> 'pt'
-    const short = options.parseLocale(browserRaw.split('-')[0])
-    if (short) return short
-  } else if (options.countryToLocale) {
+  if (options.countryToLocale) {
     // 3) Cloudflare Geo-IP Strategy
     // cf is undefined in local dev unless simulated
     const geo = options.parseLocale(mapCountryToLocale(inputs.country(), options.countryToLocale))

package/src/middleware/i18n.ts

@@ -85,16 +85,16 @@ function buildLocalizedPath(locale: Locale, rest: string[]): string {
 // Resolves the most appropriate locale for the user based on a fallback cascade
 // (locale-fallback.ts, where the order is documented and tested):
 // 1. User's saved cookie preference.
-// 2. Astro's `preferredLocale` (Accept-Language matched against the project's Astro
-//    `i18n.locales`): full tag, then its language part.
-// 3. Only when Astro reports no preferred locale: the Cloudflare Geo-IP country, through
-//    the project's `countryToLocale` table (skipped when the config has none).
+// 2. The Accept-Language header, read here rather than through Astro (which drops
+//    regional tags before matching): each tag by q, full tag, then its language part.
+// 3. Only when no tag matched: the Cloudflare Geo-IP country, through the project's
+//    `countryToLocale` table (skipped when the config has none).
 // 4. Finally, falls back to the application's DEFAULT_LOCALE.
 function resolveFallbackLocale(context: I18nMiddlewareContext): Locale {
   return resolveFallbackFrom<Locale>(
     {
       cookieLocale: () => getCookieLang(context.cookies),
-      preferredLocale: () => context.preferredLocale,
+      acceptLanguage: () => context.request.headers.get('accept-language'),
       // cf is undefined in local dev unless simulated
       country: () => context.request?.cf?.country,
     },

package/src/types.ts

@@ -55,6 +55,14 @@ export function defineI18nConfig<const C extends I18nConfig>(
   if (locales.length === 0) {
     throw new Error('[@edgekits/astro-i18n] `languages` must define at least one locale.')
   }
+  // Lowercase everywhere (config, `locales/` folders, URLs); `toIetfTag` relies on it.
+  for (const locale of locales) {
+    if (locale !== locale.toLowerCase()) {
+      throw new Error(
+        `[@edgekits/astro-i18n] \`languages\` key "${locale}" is not lowercase (use "${locale.toLowerCase()}").`,
+      )
+    }
+  }
   if (!locales.includes(config.defaultLocale)) {
     throw new Error(
       `[@edgekits/astro-i18n] \`defaultLocale\` "${config.defaultLocale}" is not one of \`languages\`: ${locales.join(', ')}.`,