@edgekits/astro-i18n 0.1.7 → 0.2.0

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.2.0 — 2026-10-27
+
+### Changed
+
+- The package is an adapter over [`@edgekits/i18n-core`](https://github.com/EdgeKits/i18n/tree/main/packages/core#readme), the framework-free engine extracted from it. Same entries, same exports, same generated files. The `edgekits-i18n` command now ships with the core and reaches your project's `.bin` through this package's dependency; `jiti` and `jsonc-parser` are no longer direct dependencies of this package. Config validation errors are prefixed `[@edgekits/i18n-core]`.
+- The switcher's client script builds its target URL through the routing mode, so the one script Astro inlines per page changes.
+- A project's own Astro `i18n` block must keep `prefixDefaultLocale: true`, in both routing modes (the build stops otherwise): Astro checks the URL after the middleware, on the rewritten `/<defaultLocale>/…` path, and with `false` it would answer 404 there.
+
+### Added
+
+- `routing: 'prefix-except-default'`: the default locale at the root (`/`, `/about/`), the other locales under their prefix (`/de/about/`). It is the default when `routing` is left out, so new projects get it. Configs that say `routing: 'prefix'` are unchanged. See README "Routing modes".
+- `localizedPath` in `/runtime` (and `./format`): the path of a page in a locale for either mode, for links, canonical, hreflang and sitemaps.
+- `<language-switcher>` carries `data-routing` and `data-default-locale`.
+
+### Fixed
+
+- After a failed KV read, the fallback text is no longer written to the edge cache for the requested locale. It was cached for a year, so one KV error could leave a locale showing default-locale text until the next `migrate` purged it.
+
+### Docs
+
+- The skill asks the routing question, its SEO references build links, canonical, hreflang and the sitemap with `localizedPath`, and the plugin ships a second skill, `tanstack-i18n`.
+
+## 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
 
@@ -68,23 +69,24 @@ export default defineI18nConfig({
   keyPrefix: 'example.com',
   // Whether MissingTranslationBanner may render.
   missingTranslationBanner: true,
-  // Every URL starts with its locale (/en/, /de/about/). The only routing there is.
+  // Every URL starts with its locale (/en/, /de/about/). Leave it out for the default,
+  // 'prefix-except-default': the default locale at the root (see Routing modes).
   routing: 'prefix',
 })
 ```
 
-| 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`                  | 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
@@ -116,10 +118,10 @@ The integration sets up:
 - a Vite plugin serving the config and your generated files to the runtime as virtual modules;
 - `vite.ssr.noExternal` for the package, whose runtime ships as source;
 - Astro's `i18n` block, when `astro.config` has none: `locales` from `languages`, your
-  `defaultLocale`, `routing: { prefixDefaultLocale: true, redirectToDefaultLocale: false }`.
-  Astro needs it to 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;
+  `defaultLocale`, `routing: { prefixDefaultLocale: true, redirectToDefaultLocale: false }` in
+  both modes. Astro needs it to set `Astro.currentLocale`, which `resolveLocale` reads. If you
+  keep your own block, its `locales` must include every configured locale, its `defaultLocale`
+  must match, and its `routing` must be that one, or the build stops with a message saying which;
 - the `Locale` type: the union of your locales, for the package's exports;
 - type declarations for its virtual modules, so `tsc` and `astro check` accept the package's
   runtime source in your program;
@@ -135,9 +137,10 @@ The integration sets up:
   export const onRequest = sequence(i18n, yourOwnMiddleware)
   ```
 
-The middleware redirects a URL without a locale (`/`, `/about/`) to a localized one and sets
-`Astro.locals.uiLocale` (the URL's locale) and `Astro.locals.translationLocale` (the locale to
-fetch translations for) on every request.
+In `'prefix'` the middleware redirects a URL without a locale (`/`, `/about/`) to a localized
+one; in `'prefix-except-default'` such a URL is a default-locale page (see
+[Routing modes](#routing-modes)). Either way it sets `Astro.locals.uiLocale` (the URL's locale)
+and `Astro.locals.translationLocale` (the locale to fetch translations for) on every request.
 
 ### 5. Write translations
 
@@ -173,6 +176,9 @@ its first element, and a locale that has the list replaces it whole.
 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                                                                                           |
@@ -305,6 +311,56 @@ export default defineI18nConfig({
 Use it when your markdown endpoints exist in one locale only. Without it, the package assumes
 nothing about them.
 
+In `'prefix-except-default'` the default locale has no prefix here either: with
+`markdownLocale: 'en'` (the default locale) the canonical form is `/blog/x.md`, and
+`/en/blog/x.md` redirects to it. A `.md` path without a locale segment is served from
+`src/pages/[lang]/` as the default locale's, like any root page.
+
+### Routing modes
+
+`routing` decides where the default locale lives. Pages stay in `src/pages/[lang]/…` in both.
+
+- `'prefix-except-default'` (the default when `routing` is left out): the default locale at the
+  root (`/`, `/about/`), every other locale under its prefix (`/de/about/`). The middleware
+  serves a root URL by rewriting it internally to `/<defaultLocale>/…`, so the URL stays;
+  `/en/about/` redirects permanently to `/about/`. A root URL consults neither Accept-Language
+  nor the country: only a lang cookie for another locale (the visitor chose it in the switcher)
+  redirects, temporarily, to that locale.
+- `'prefix'`: every URL starts with its locale (`/en/about/`); `/` and a URL without a locale
+  redirect to the visitor's locale (cookie, Accept-Language, country, default). Projects that
+  set `routing: 'prefix'` keep exactly this by leaving their config alone.
+
+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
+here, so `localizedPath` is the one to use:
+
+```astro
+---
+import { DEFAULT_LOCALE, I18N_CONFIG, SUPPORTED_LOCALES, localizedPath, toIetfTag } from '@edgekits/astro-i18n/runtime'
+
+const options = {
+  routing: I18N_CONFIG.routing,
+  defaultLocale: DEFAULT_LOCALE,
+  isLocale: (segment: string) => (SUPPORTED_LOCALES as readonly string[]).includes(segment),
+}
+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)} />
+```
+
+Two limits:
+
+- A root path whose first segment equals a locale code is read as that locale: a default-locale
+  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`.
+
 ### Styling the components
 
 `LanguageSwitcher` and `MissingTranslationBanner` are headless: they carry structure, behaviour
@@ -408,9 +464,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.
@@ -433,7 +493,7 @@ per render.
 `astro-i18n` is a free agent skill that sets up `@edgekits/astro-i18n` in your project and keeps
 working with it afterwards. It runs in Claude Code as a plugin, and in Cursor, OpenCode or any other
 coding agent that reads `SKILL.md`. Its source is in
-[`plugins/astro-i18n`](https://github.com/EdgeKits/astro-i18n/tree/main/plugins/astro-i18n).
+[`plugins/astro-i18n`](https://github.com/EdgeKits/i18n/tree/main/plugins/astro-i18n).
 
 ### What it does
 
@@ -505,7 +565,7 @@ folder. In both cases the plugin itself is still installed once per contributor
 Any other agent, with the [skills CLI](https://skills.sh):
 
 ```sh
-npx skills add EdgeKits/astro-i18n --skill astro-i18n
+npx skills add EdgeKits/i18n --skill astro-i18n
 ```
 
 ### Prerequisites
@@ -521,6 +581,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
 
@@ -544,12 +606,18 @@ The skill asks before it writes any code, and waits for the answers:
 | Should a visitor's country pick the locale when nothing else does? How?      | `DE`, `AT`, `CH` → `de`; `BR` → `pt-br`       |
 | Middleware: registered by the integration (`auto`), or in your own sequence? | `auto`                                        |
 | Flags in the language switcher?                                              | Yes: `en` → `us`, `de` → `de`, `pt-br` → `br` |
+| Routing: the default locale at the root, or every locale prefixed?           | At the root                                   |
 
 For flags, a regional locale takes its region (`pt-br` → `br`, `en-gb` → `gb`), and for a
 language-only locale the skill proposes the obvious country (`en` → `us`) for you to confirm. It
 shows the full list back before it writes the config. If you have no preference on any of
 these, it uses the defaults: no geo table, no markdown locale, `auto` middleware, flags on.
 
+For routing, the default locale at the root (`/`, `/about/`; other locales prefixed) is
+`routing: 'prefix-except-default'`, the default; every locale prefixed (`/en/about/`) is
+`routing: 'prefix'`. The skill asks only with two or more locales; with one, the root mode is
+the only sensible one and needs no question.
+
 #### What it creates
 
 - `edgekits-i18n.config.ts` with your answers, and the integration in `astro.config`.
@@ -559,11 +627,14 @@ these, it uses the defaults: no geo table, no markdown locale, `auto` middleware
   `src/i18n.generated.d.ts`, `src/i18n/runtime-constants.ts`, `src/i18n/fallbacks.generated.ts`.
   Commit them.
 - The route layout: `src/pages/about.astro` becomes `src/pages/[lang]/about.astro`, and so on.
-  The root `index.astro` moves too, since the middleware redirects `/` to `/<locale>/`.
+  The root `index.astro` moves too: in `'prefix'` the middleware redirects `/` to
+  `/<locale>/`, and in `'prefix-except-default'` it serves the default locale's page there.
   Endpoints that are not localized (`robots.txt`, `sitemap.xml`, `/api/*`) and `public/` stay
   where they are.
 - `src/components/Flag.astro` and one SVG per flag in `public/flags/`, if you chose flags (the
   recipe is below).
+- The language switcher and the hreflang tags work in both routing modes: the hreflang
+  component builds its URLs with `localizedPath`, which knows the mode.
 - A KV namespace on your Cloudflare account (`wrangler kv namespace create`). The skill asks
   before it runs that command. Until then, local development works with a placeholder id of 32
   hexadecimal characters, such as `00000000000000000000000000000000`: the CLI checks the id's

package/dist/integration/index.d.ts

@@ -1,5 +1,5 @@
 import type { AstroConfig, AstroIntegration } from 'astro';
-import { type I18nConfig } from '../types.ts';
+import { type I18nConfig, type I18nRouting } from '@edgekits/i18n-core';
 export type EdgekitsI18nOptions = {
     middleware?: 'auto' | 'manual';
 };
@@ -10,6 +10,14 @@ export declare const PACKAGE_NAME = "@edgekits/astro-i18n";
  * plugin's virtual modules.
  */
 export declare function edgekitsI18n(config: I18nConfig, options?: EdgekitsI18nOptions): AstroIntegration;
+/**
+ * The validated config with `routing` resolved: absent means 'prefix-except-default', the
+ * mode for new projects. Resolved here, before the Vite plugin serialises it, so the
+ * virtual config (and `I18N_CONFIG`) always carries the mode the middleware runs.
+ */
+export declare function resolveConfig(config: I18nConfig): I18nConfig & {
+    routing: I18nRouting;
+};
 /**
  * Augments `I18nLocales` with the configured locales, so `Locale` narrows from
  * `string` to their union in the project, through both entries. The `export {}` keeps
@@ -19,8 +27,21 @@ export declare function edgekitsI18n(config: I18nConfig, options?: EdgekitsI18nO
 export declare function localesDeclaration(locales: readonly string[]): string;
 /**
  * The Astro `i18n` block set when the project has none: locales and default from the
- * config; every URL locale-prefixed (the middleware redirects `/` itself, so Astro
- * does not). Complete, `fallbackType` included: Astro does not re-validate what
- * `updateConfig` merges, so its schema defaults never fill a partial block.
+ * config; routed as locale-prefixed in both modes (the middleware redirects `/` itself in
+ * 'prefix', so Astro does not). Complete, `fallbackType` included: Astro does not
+ * 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
+ * passes and `Astro.currentLocale` works on root pages.
  */
 export declare function astroI18n(config: I18nConfig): NonNullable<AstroConfig['i18n']>;
+/**
+ * A project's own Astro `i18n` block must cover every configured locale (as a string
+ * entry, a `path` or one of its `codes`), share the default locale, and route as
+ * `astroI18n` does (`prefixDefaultLocale: true`, `redirectToDefaultLocale: false`).
+ */
+export declare function assertAstroI18n(block: NonNullable<AstroConfig['i18n']>, config: I18nConfig): void;

package/dist/integration/index.js

@@ -1,4 +1,4 @@
-import { DEFAULT_GENERATED_DIR, defineI18nConfig } from "../types.js";
+import { DEFAULT_GENERATED_DIR, defineI18nConfig } from '@edgekits/i18n-core';
 import { i18nVitePlugin } from "./vite-plugin.js";
 import { virtualModulesDeclaration } from "./virtual-types.js";
 const MIDDLEWARE_MODES = ['auto', 'manual'];
@@ -9,7 +9,7 @@ export const PACKAGE_NAME = '@edgekits/astro-i18n';
  * plugin's virtual modules.
  */
 export function edgekitsI18n(config, options = {}) {
-    const i18nConfig = defineI18nConfig(config);
+    const i18nConfig = resolveConfig(config);
     const middleware = options.middleware ?? 'auto';
     if (!MIDDLEWARE_MODES.includes(middleware)) {
         throw new Error(`[@edgekits/astro-i18n] \`middleware\` "${String(middleware)}" is not supported; use 'auto' or 'manual'.`);
@@ -45,8 +45,18 @@ export function edgekitsI18n(config, options = {}) {
         },
     };
 }
-// Each entry that exports `I18nLocales` from its own declaration: the root entry's comes
-// from dist/types.d.ts, the runtime entry's from the shipped source (src/types.ts).
+/**
+ * The validated config with `routing` resolved: absent means 'prefix-except-default', the
+ * mode for new projects. Resolved here, before the Vite plugin serialises it, so the
+ * virtual config (and `I18N_CONFIG`) always carries the mode the middleware runs.
+ */
+export function resolveConfig(config) {
+    const validated = defineI18nConfig(config);
+    return { ...validated, routing: validated.routing ?? 'prefix-except-default' };
+}
+// Each entry that exports `I18nLocales`: both re-export the core's interface (root through
+// dist/types.d.ts, runtime through the shipped src/types.ts), so either augmentation
+// merges into it; both are kept so neither entry depends on how the other resolves.
 const LOCALE_MODULES = ['@edgekits/astro-i18n', '@edgekits/astro-i18n/runtime'];
 /**
  * Augments `I18nLocales` with the configured locales, so `Locale` narrows from
@@ -71,9 +81,16 @@ export function localesDeclaration(locales) {
 }
 /**
  * The Astro `i18n` block set when the project has none: locales and default from the
- * config; every URL locale-prefixed (the middleware redirects `/` itself, so Astro
- * does not). Complete, `fallbackType` included: Astro does not re-validate what
- * `updateConfig` merges, so its schema defaults never fill a partial block.
+ * config; routed as locale-prefixed in both modes (the middleware redirects `/` itself in
+ * 'prefix', so Astro does not). Complete, `fallbackType` included: Astro does not
+ * 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
+ * passes and `Astro.currentLocale` works on root pages.
  */
 export function astroI18n(config) {
     return {
@@ -84,9 +101,10 @@ export function astroI18n(config) {
 }
 /**
  * A project's own Astro `i18n` block must cover every configured locale (as a string
- * entry, a `path` or one of its `codes`) and share the default locale.
+ * entry, a `path` or one of its `codes`), share the default locale, and route as
+ * `astroI18n` does (`prefixDefaultLocale: true`, `redirectToDefaultLocale: false`).
  */
-function assertAstroI18n(block, config) {
+export function assertAstroI18n(block, config) {
     const declared = new Set(block.locales.flatMap((entry) => (typeof entry === 'string' ? [entry] : [entry.path, ...entry.codes])));
     const missing = Object.keys(config.languages).filter((locale) => !declared.has(locale));
     if (missing.length > 0) {
@@ -97,6 +115,14 @@ function assertAstroI18n(block, config) {
         throw new Error(`[@edgekits/astro-i18n] Astro \`i18n.defaultLocale\` "${block.defaultLocale}" differs from \`defaultLocale\` "${config.defaultLocale}". ` +
             'Make them equal, or remove the `i18n` block from astro.config and the integration sets it for you.');
     }
+    // Absent values are Astro's schema defaults (both false): `redirectToDefaultLocale` left
+    // out is fine, `prefixDefaultLocale` left out is not.
+    const routing = typeof block.routing === 'object' ? block.routing : undefined;
+    if (routing?.prefixDefaultLocale !== true || routing.redirectToDefaultLocale === true) {
+        throw new Error('[@edgekits/astro-i18n] Astro `i18n.routing` must set `prefixDefaultLocale: true` and `redirectToDefaultLocale: false` ' +
+            `(found ${JSON.stringify(block.routing)}): the middleware handles the default locale itself, and Astro's ` +
+            'own check would otherwise answer 404 or redirect the pages it serves. Set them, or remove the `i18n` block from astro.config and the integration sets it for you.');
+    }
 }
 function trimSlashes(path) {
     return path.replace(/^\/+|\/+$/g, '');

package/dist/integration/vite-plugin.d.ts

@@ -1,5 +1,5 @@
 import type { AstroConfig } from 'astro';
-import type { I18nConfig } from '../types.ts';
+import type { I18nConfig } from '@edgekits/i18n-core';
 type VitePlugin = NonNullable<NonNullable<AstroConfig['vite']>['plugins']>[number];
 export declare const CONFIG_ID = "virtual:@edgekits/astro-i18n/config";
 export declare const FALLBACKS_ID = "virtual:@edgekits/astro-i18n/fallbacks";

package/dist/types.d.ts

@@ -1,60 +1,13 @@
 /**
- * Public types of the package and the config validator. Pure: no virtual modules,
- * no `cloudflare:workers`, so the consumer's `astro.config` and the CLI can import it
- * under plain Node.
+ * The core's public types and config helpers, re-exported for this package's entries
+ * (root, `./config`, `./runtime`), plus what only Astro needs: the `App.Locals` the
+ * middleware fills. `I18nLocales` is the core's interface: augmenting it through either
+ * entry (the integration's injected `locales.d.ts`) merges into that one declaration.
  */
-export type I18nLanguage = {
-    countryCode?: string;
-    name: string;
-};
-export type I18nConfig = {
-    languages: Record<string, I18nLanguage>;
-    defaultLocale: string;
-    cookie: {
-        name: string;
-        maxAge: number;
-    };
-    keyPrefix: string;
-    missingTranslationBanner: boolean;
-    routing: 'prefix';
-    generatedDir?: string;
-    localesDir?: string;
-    countryToLocale?: Record<string, string>;
-    markdownLocale?: string;
-};
-export declare const DEFAULT_GENERATED_DIR = "src/i18n";
-export declare const DEFAULT_LOCALES_DIR = "locales";
-/** The locale keys of a config's `languages`: a literal union for a literal config. */
-export type LocaleOf<C extends I18nConfig> = Extract<keyof C['languages'], string>;
-/**
- * Validates and returns the config unchanged. Throws at config time on an empty
- * `languages`, a `defaultLocale` or `markdownLocale` that is not one of its keys, an
- * unknown `routing`, or a `countryToLocale` entry whose key is not an uppercase country
- * code or whose value is not one of `languages` (also a type error for a literal config).
- */
-export declare function defineI18nConfig<const C extends I18nConfig>(config: C & {
-    countryToLocale?: Record<string, LocaleOf<C>>;
-    markdownLocale?: LocaleOf<C>;
-}): C;
-/**
- * The project's locales, as keys. Empty here; the integration augments it from the
- * config's `languages` (`injectTypes` at `astro:config:done`).
- */
-export interface I18nLocales {
-}
-type LocaleKey = Extract<keyof I18nLocales, string>;
-export type Locale = [LocaleKey] extends [never] ? string : LocaleKey;
-/** The Worker bindings the engine reads from `cloudflare:workers`. */
-export interface I18nBindings {
-    TRANSLATIONS: KVNamespace;
-    I18N_CACHE?: string;
-    DEBUG_I18N?: string;
-}
+import type { Locale } from '@edgekits/i18n-core';
+export { DEFAULT_GENERATED_DIR, defineI18nConfig, localesOf } from '@edgekits/i18n-core';
+export type { I18nBindings, I18nConfig, I18nLanguage, I18nLocales, Locale, LocaleOf, LocalesOf, } from '@edgekits/i18n-core';
 declare global {
-    namespace I18n {
-        interface Schema {
-        }
-    }
     namespace App {
         interface Locals {
             uiLocale: Locale;
@@ -63,4 +16,3 @@ declare global {
         }
     }
 }
-export {};

package/dist/types.js

@@ -1,44 +1 @@
-/**
- * Public types of the package and the config validator. Pure: no virtual modules,
- * no `cloudflare:workers`, so the consumer's `astro.config` and the CLI can import it
- * under plain Node.
- */
-export const DEFAULT_GENERATED_DIR = 'src/i18n';
-export const DEFAULT_LOCALES_DIR = 'locales';
-const COUNTRY_CODE = /^[A-Z]{2}$/;
-/**
- * Validates and returns the config unchanged. Throws at config time on an empty
- * `languages`, a `defaultLocale` or `markdownLocale` that is not one of its keys, an
- * unknown `routing`, or a `countryToLocale` entry whose key is not an uppercase country
- * code or whose value is not one of `languages` (also a type error for a literal config).
- */
-export function defineI18nConfig(config) {
-    const locales = Object.keys(config.languages ?? {});
-    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(', ')}.`);
-    }
-    if (config.markdownLocale !== undefined && !locales.includes(config.markdownLocale)) {
-        throw new Error(`[@edgekits/astro-i18n] \`markdownLocale\` "${config.markdownLocale}" is not one of \`languages\`: ${locales.join(', ')}.`);
-    }
-    if (config.routing !== 'prefix') {
-        throw new Error(`[@edgekits/astro-i18n] \`routing\` "${String(config.routing)}" is not supported; the only routing is 'prefix'.`);
-    }
-    for (const [country, locale] of Object.entries(config.countryToLocale ?? {})) {
-        if (!COUNTRY_CODE.test(country)) {
-            throw new Error(`[@edgekits/astro-i18n] \`countryToLocale\` key "${country}" is not an uppercase ISO 3166-1 alpha-2 country code.`);
-        }
-        if (!locales.includes(locale)) {
-            throw new Error(`[@edgekits/astro-i18n] \`countryToLocale\` maps "${country}" to "${locale}", which is not one of \`languages\`: ${locales.join(', ')}.`);
-        }
-    }
-    return config;
-}
+export { DEFAULT_GENERATED_DIR, defineI18nConfig, localesOf } from '@edgekits/i18n-core';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgekits/astro-i18n",
-  "version": "0.1.7",
+  "version": "0.2.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",
@@ -16,11 +16,12 @@
   "author": "Gary Stupak",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/EdgeKits/astro-i18n.git"
+    "url": "git+https://github.com/EdgeKits/i18n.git",
+    "directory": "packages/astro"
   },
-  "homepage": "https://github.com/EdgeKits/astro-i18n#readme",
+  "homepage": "https://github.com/EdgeKits/i18n#readme",
   "bugs": {
-    "url": "https://github.com/EdgeKits/astro-i18n/issues"
+    "url": "https://github.com/EdgeKits/i18n/issues"
   },
   "engines": {
     "node": ">=22"
@@ -37,9 +38,6 @@
     "./components/*": "./src/components/*.astro",
     "./package.json": "./package.json"
   },
-  "bin": {
-    "edgekits-i18n": "dist/cli/index.js"
-  },
   "files": [
     "dist",
     "src",
@@ -59,8 +57,7 @@
     "format:check": "prettier --check ."
   },
   "dependencies": {
-    "jiti": "^2.7.0",
-    "jsonc-parser": "^3.3.1"
+    "@edgekits/i18n-core": "0.2.0"
   },
   "peerDependencies": {
     "@astrojs/cloudflare": "^14.3.0",
@@ -68,13 +65,6 @@
     "wrangler": "^4.125.0"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "^5.20261011.1",
-    "@types/node": "^25.9.1",
-    "astro": "^7.3.8",
-    "prettier": "3.9.4",
-    "prettier-plugin-astro": "0.14.1",
-    "prettier-plugin-tailwindcss": "0.8.0",
-    "tsx": "^4.23.12",
-    "typescript": "~5.9.3"
+    "astro": "^7.3.8"
   }
 }