@edgekits/astro-i18n 0.1.7 → 0.1.8

package/CHANGELOG.md

@@ -4,6 +4,20 @@ 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

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
@@ -408,9 +409,13 @@ a regular Worker: `request.cf`, `caches.default` and `env` behave as usual, and
 language cookie and the relative redirects keep visitors on their custom hostname. Two
 constraints:
 
-- `keyPrefix` must be a hostname inside the zone that `CLOUDFLARE_ZONE_ID` names: the zone name
-  itself or a subdomain of it. Single-file purge reaches only URLs on hostnames that zone owns.
-  With a `keyPrefix` on another domain, `migrate` reports success and nothing is purged.
+- `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.
@@ -521,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.
@@ -256,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/package.json

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

@@ -69,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"
@@ -79,7 +82,6 @@ const { uiLocale: currentLang } = Astro.locals
               role="menuitem"
               disabled={isActive}
             >
-              {/* The label is the language's own name: `lang` lets a screen reader say it in that language. */}
               <span class={classes.itemLabel} lang={locale}>
                 {Flag && flagCode && <Flag code={flagCode} size={16} />}
                 {label.name}