@edgekits/astro-i18n 0.1.6 → 0.1.7

package/CHANGELOG.md

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

@@ -117,7 +117,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 +261,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 +325,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 +399,33 @@ 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` 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.
+- 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 +480,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

package/dist/cli/index.js

@@ -144,7 +144,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 +208,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;
     }

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.7",
   "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

@@ -197,7 +197,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 +290,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
   }

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 ? (
@@ -76,7 +79,8 @@ const { uiLocale: currentLang } = Astro.locals
               role="menuitem"
               disabled={isActive}
             >
-              <span class={classes.itemLabel}>
+              {/* 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}
               </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(', ')}.`,