@edgekits/astro-i18n 0.0.0-stage → 0.1.0

package/src/locale-fallback.ts

@@ -0,0 +1,65 @@
+/**
+ * The middleware's fallback cascade for a request whose URL carries no valid locale,
+ * as a pure function: the request-bound inputs arrive as getters, so each one is read
+ * exactly when, and only if, the cascade reaches it (same split as `env` in the fetcher).
+ *
+ * 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,
+ *      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.
+ */
+
+export type FallbackInputs<L extends string> = {
+  cookieLocale: () => L | null
+  preferredLocale: () => string | undefined
+  country: () => unknown
+}
+
+export type FallbackOptions<L extends string> = {
+  // Returns the locale when the value is a supported one, otherwise null.
+  parseLocale: (value: unknown) => L | null
+  defaultLocale: L
+  countryToLocale?: Readonly<Record<string, string>>
+}
+
+export function resolveFallbackLocale<L extends string>(inputs: FallbackInputs<L>, options: FallbackOptions<L>): 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
+
+    // 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) {
+    // 3) Cloudflare Geo-IP Strategy
+    // cf is undefined in local dev unless simulated
+    const geo = options.parseLocale(mapCountryToLocale(inputs.country(), options.countryToLocale))
+    if (geo) return geo
+  }
+
+  return options.defaultLocale
+}
+
+/**
+ * Maps a Cloudflare country code (`request.cf.country`) to a locale through the
+ * project's table. Returns undefined if the country is not in it.
+ */
+export function mapCountryToLocale(country: unknown, table: Readonly<Record<string, string>>): string | undefined {
+  // Safety: In dev mode (localhost), 'country' might be null or undefined.
+  if (typeof country !== 'string') return undefined
+
+  // Cloudflare always sends uppercase (e.g., 'US', 'DE'), but safety first.
+  return table[country.toUpperCase()]
+}

package/src/markdown-path.ts

@@ -0,0 +1,31 @@
+/**
+ * The middleware's `.md` normalisation, as a pure function. Markdown endpoints
+ * (`/de/blog/x.md/`, `/blog/x.md`) are served in one locale, the project's
+ * `markdownLocale`; this returns the single redirect target for such a path, or null
+ * when there is nothing to redirect:
+ *   - not a `.md` path, or the project has no `markdownLocale`: null (the middleware
+ *     lets the request through untouched);
+ *   - a leading segment that is a locale is replaced, any other leading segment is kept
+ *     (`/foo.md` -> `/<markdownLocale>/foo.md`, never the homepage);
+ *   - a trailing slash is dropped, in the same redirect;
+ *   - a path already in canonical form: null.
+ */
+
+export const MARKDOWN_PATH = /\.md\/?$/
+
+export type MarkdownOptions = {
+  // True when the segment is a supported locale.
+  isLocale: (segment: string) => boolean
+  markdownLocale?: string
+}
+
+export function markdownRedirectTarget(pathname: string, options: MarkdownOptions): string | null {
+  if (!options.markdownLocale || !MARKDOWN_PATH.test(pathname)) return null
+
+  const segments = pathname.split('/').filter(Boolean)
+  const first = segments[0]
+  const contentSegments = first !== undefined && options.isLocale(first) ? segments.slice(1) : segments
+  const target = `/${options.markdownLocale}/${contentSegments.join('/')}`
+
+  return target === pathname ? null : target
+}

package/src/middleware/i18n.ts

@@ -0,0 +1,223 @@
+import type { MiddlewareHandler } from 'astro'
+import { LocaleSchema } from '../schema'
+import { I18N_CONFIG } from '../config'
+import { DEFAULT_LOCALE, type Locale } from '../constants'
+import { getCookieLang, setCookieLang } from '../cookie-storage'
+import { resolveFallbackLocale as resolveFallbackFrom } from '../locale-fallback'
+import { MARKDOWN_PATH, markdownRedirectTarget } from '../markdown-path'
+import { resolveLocaleForTranslations } from '../resolve-locale'
+
+// Regex to identify public static assets (images, fonts, scripts, etc.)
+// These files should bypass i18n routing and locale detection.
+const PUBLIC_FILE_REGEX = /\.(ico|png|jpg|jpeg|svg|webp|gif|css|js|map|txt|xml|json|woff2?|avif|md)$/i
+
+// List of URL prefixes that should be ignored by the i18n middleware.
+// Includes API endpoints, internal Astro paths, and standard static routes.
+// The Vite dev-server prefixes (/@vite, /@id, /@fs, /src, /node_modules) make
+// dev survive `run_worker_first: ["/*"]` being left on: without them every
+// dev-module request fell through to the locale logic, got redirected to
+// /<locale>/@vite/... and rendered a full 404 page (with its translation
+// fetches) per module. Harmless in prod — no real route starts with these.
+const IGNORED_PREFIXES = [
+  '/api',
+  '/assets',
+  '/_astro',
+  '/_image',
+  '/_actions',
+  '/favicon',
+  '/@vite',
+  '/@id',
+  '/@fs',
+  '/src',
+  '/node_modules',
+]
+
+// Extracts the context type from Astro's MiddlewareHandler for cleaner function signatures.
+type I18nMiddlewareContext = Parameters<MiddlewareHandler>[0]
+
+// Two kinds of redirect, by whether the target depends on the visitor.
+//
+// Deterministic normalisations (a missing trailing slash, a `.md` path moved to
+// `markdownLocale`) always lead to the same URL, so they are permanent in production:
+// 301 consolidates canonical signals in Google. They use REDIRECT_STATUS: 302 under
+// `astro dev` (`import.meta.env.DEV`) so nothing gets cached while testing, 301 in any
+// production build (incl. `astro preview` / `wrangler dev`). `?.`: plain Node (the tests)
+// has no `import.meta.env`, which counts as production.
+//
+// Negotiated redirects (no locale or an invalid one in the URL: the target comes from the
+// visitor's cookie, Accept-Language or country) are always temporary and uncacheable, in
+// dev and production alike: see negotiatedRedirect(). A browser keeps a 301 and never asks
+// the server again, so a language chosen later in the switcher would be bypassed on the
+// next visit to `/`, and the URL-wins cookie sync below would then overwrite that choice.
+const REDIRECT_STATUS = import.meta.env?.DEV ? 302 : 301
+
+// A redirect whose target depends on the visitor: temporary, never stored by a shared
+// cache, and keyed on the request headers that chose it (the country is not a request
+// header, hence `no-store` rather than relying on Vary alone).
+function negotiatedRedirect(target: string): Response {
+  return new Response(null, {
+    status: 302,
+    headers: {
+      Location: target,
+      'Cache-Control': 'private, no-store',
+      Vary: 'Cookie, Accept-Language',
+    },
+  })
+}
+
+// Determines if the current request path matches static assets or ignored prefixes.
+// Returns true to skip i18n processing for this request.
+function shouldBypassI18n(pathname: string): boolean {
+  if (PUBLIC_FILE_REGEX.test(pathname)) return true
+  if (IGNORED_PREFIXES.some((p) => pathname.startsWith(p))) return true
+  // Markdown endpoints: /en/blog/slug.md/ (with or without trailing slash)
+  if (MARKDOWN_PATH.test(pathname)) return true
+  return false
+}
+
+// Constructs a standardized localized URL path ensuring a trailing slash.
+// Example: buildLocalizedPath('en', ['about', 'team']) -> '/en/about/team/'
+function buildLocalizedPath(locale: Locale, rest: string[]): string {
+  const suffix = rest.join('/')
+  return suffix ? `/${locale}/${suffix}/` : `/${locale}/`
+}
+
+// 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).
+// 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,
+      // cf is undefined in local dev unless simulated
+      country: () => context.request?.cf?.country,
+    },
+    {
+      parseLocale: (value) => {
+        const parsed = LocaleSchema.safeParse(value)
+        return parsed.success ? parsed.data : null
+      },
+      defaultLocale: DEFAULT_LOCALE,
+      countryToLocale: I18N_CONFIG.countryToLocale,
+    },
+  )
+}
+
+// Main i18n middleware handler. Intercepts incoming requests, manages routing,
+// sets locale context, and handles soft 404 protections for edge environments.
+export const i18nMiddleware: MiddlewareHandler = async (context, next) => {
+  const url = new URL(context.request.url)
+  const pathname = url.pathname
+
+  // 1. Split the URL early to access its segments
+  const segments = pathname.split('/').filter(Boolean) // "/es/about/" -> ["es", "about"]
+  const firstSegment = segments[0] ?? null
+
+  // 2. SAFETY NET (For static file 404 pages)
+  // Attempt to infer the locale from the URL, or fallback to the default.
+  let safeLocale = DEFAULT_LOCALE
+  if (firstSegment) {
+    const parsed = LocaleSchema.safeParse(firstSegment)
+    if (parsed.success) {
+      safeLocale = parsed.data
+    }
+  }
+
+  // Inject the locale into the context BEFORE the bypass check!
+  context.locals.uiLocale = safeLocale
+  context.locals.translationLocale = resolveLocaleForTranslations(safeLocale)
+
+  // 3. Bypass static files and system paths (with Soft 404 protection)
+  if (shouldBypassI18n(pathname)) {
+    // .md endpoints: one redirect to the project's `markdownLocale`, no trailing slash
+    // (markdown-path.ts). Without `markdownLocale` they pass through untouched.
+    const markdownTarget = markdownRedirectTarget(pathname, {
+      isLocale: (segment) => LocaleSchema.safeParse(segment).success,
+      markdownLocale: I18N_CONFIG.markdownLocale,
+    })
+    if (markdownTarget) {
+      return context.redirect(markdownTarget, REDIRECT_STATUS)
+    }
+
+    const response = await next()
+
+    const contentType = response.headers.get('content-type') || ''
+    const isHtml = contentType.includes('text/html')
+    const isRedirect = response.status >= 300 && response.status < 400
+
+    // If Astro attempts to return HTML for a static/API request (and it's not a redirect),
+    // it means the file wasn't found and Astro rendered a fallback page (404.astro or catch-all).
+    // We strictly intercept this and return a lightweight text-based 404 instead.
+    // Why? To mitigate Directory Bruteforcing / Fuzzing attacks and save resources.
+    if (isHtml && !isRedirect) {
+      // Aggressively save Worker CPU cycles for missing static files
+      return new Response('Not found', {
+        status: 404,
+        headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+      })
+    }
+
+    return response
+  }
+
+  const fallbackLocale = resolveFallbackLocale(context)
+
+  // 1. No locale in URL — redirect to fallback locale root
+  if (!firstSegment) {
+    const target = buildLocalizedPath(fallbackLocale, [])
+    if (pathname !== target) {
+      return negotiatedRedirect(target)
+    }
+    return await next()
+  }
+
+  // 2. URL has first segment — validate as locale
+  const parsed = LocaleSchema.safeParse(firstSegment)
+  const urlLocale: Locale | null = parsed.success ? parsed.data : null
+
+  if (urlLocale) {
+    // Keep the lang cookie in sync with the URL locale — but ONLY update an
+    // EXISTING cookie that differs. Rationale (HTML edge cache, P1/P2):
+    //   - The old unconditional set emitted `Set-Cookie` on EVERY localized
+    //     response, which made every response uncacheable (the edge cache
+    //     refuses anything carrying Set-Cookie).
+    //   - Cookie-less requests (first visits, crawlers, every PSI/GTmetrix run)
+    //     must produce NO Set-Cookie at all, otherwise lab tests never hit the
+    //     cache and the TTFB jitter (P2) stays. So a missing cookie is NOT
+    //     created here — the explicit language choice is persisted client-side
+    //     by the LanguageSwitcher, and an existing cookie is re-synced below
+    //     when the user lands on a different locale by any other means.
+    const cookieLocale = getCookieLang(context.cookies)
+    if (cookieLocale && cookieLocale !== urlLocale) {
+      setCookieLang(context.cookies, urlLocale)
+    }
+    // Set uiLocale to Astro locals
+    context.locals.uiLocale = urlLocale
+    // Define and set translationLocale to Astro locals
+    const translationLocale = resolveLocaleForTranslations(urlLocale)
+    context.locals.translationLocale = translationLocale
+
+    // Normalize trailing slash and structure
+    const normalized = buildLocalizedPath(urlLocale, segments.slice(1))
+    if (pathname !== normalized) {
+      return context.redirect(normalized, REDIRECT_STATUS)
+    }
+
+    return await next()
+  }
+
+  // 3. Invalid locale in URL -> treat the whole path as content missing the locale prefix.
+  const target = buildLocalizedPath(fallbackLocale, segments)
+
+  if (pathname !== target) {
+    return negotiatedRedirect(target)
+  }
+
+  return await next()
+}

package/src/middleware.ts

@@ -0,0 +1,2 @@
+// The middleware entrypoint the integration registers (`middleware: 'auto'`).
+export { i18nMiddleware as onRequest } from './middleware/i18n'

package/src/parse-boolean.ts

@@ -0,0 +1,20 @@
+// Engine-owned copy of src/utils/shared/parse-boolean.ts: the package ships its own.
+// The project copy stays for its other consumers (seo/utils.ts, htmlCacheMiddleware.ts).
+
+/**
+ * Parse a boolean flag from Wrangler-env string.
+ *
+ * Accepts:
+ *   "1", "true", "on"   → true
+ *   "0", "false", "off" → false
+ *   undefined           → defaultValue
+ */
+export function parseBooleanFlag(value: string | undefined, defaultValue: boolean): boolean {
+  if (value === undefined) return defaultValue
+
+  const v = value.toLowerCase()
+  if (v === '1' || v === 'true' || v === 'on') return true
+  if (v === '0' || v === 'false' || v === 'off') return false
+
+  return defaultValue
+}

package/src/resolve-locale.ts

@@ -0,0 +1,57 @@
+import type { AstroGlobal } from 'astro'
+
+import { LocaleSchema } from './schema'
+import type { Locale } from './constants'
+import { DEFAULT_LOCALE, ENABLE_MISSING_TRANSLATION_BANNER } from './constants'
+import { LOCALES_WITH_TRANSLATIONS, FULLY_TRANSLATED_LOCALES } from 'virtual:@edgekits/astro-i18n/runtime-constants'
+
+// Checking for the presence of at least one file with translations
+function hasTranslations(locale: Locale): boolean {
+  return (LOCALES_WITH_TRANSLATIONS as readonly string[]).includes(locale)
+}
+
+// Checking the completeness of translations
+function isFullyTranslated(locale: Locale): boolean {
+  return (FULLY_TRANSLATED_LOCALES as readonly string[]).includes(locale)
+}
+
+/**
+ * Optional: return a “missing translation” banner message
+ * when uiLocale has no translations or (blog) content is missing in required language.
+ *
+ * Returns:
+ *   - MissingTranslationType: type of message to show ('ui' or 'content')
+ *   - null: if banner should not be shown
+ */
+type MissingTranslationType = 'ui' | 'content' | null
+
+export function checkMissingTranslation(
+  uiLocale: Locale,
+  isMissingContent: boolean | undefined,
+): MissingTranslationType {
+  if (!ENABLE_MISSING_TRANSLATION_BANNER) return null
+
+  if (isFullyTranslated(uiLocale) && !isMissingContent) return null
+
+  return isMissingContent ? 'content' : 'ui'
+}
+
+/**
+ * UI / routing locale:
+ * - What user selected
+ * - What is used for <html lang>, URL, etc.
+ */
+export function resolveLocale(Astro: AstroGlobal): Locale {
+  const raw = Astro.currentLocale ?? DEFAULT_LOCALE
+  const parsed = LocaleSchema.safeParse(raw)
+  return parsed.success ? parsed.data : DEFAULT_LOCALE
+}
+
+/**
+ * Translation locale:
+ * - What we actually load from KV
+ * - Falls back if there is no bundle for the UI locale
+ */
+export function resolveLocaleForTranslations(locale: Locale): Locale {
+  return hasTranslations(locale) ? locale : DEFAULT_LOCALE
+}

package/src/runtime.ts

@@ -0,0 +1,19 @@
+// The runtime entry (`@edgekits/astro-i18n/runtime`): what pages, layouts and endpoints
+// import. Ships as source and runs through the project's Vite, next to the virtual
+// modules the integration serves.
+export { fetchTranslations } from './fetcher'
+export { fmt, plural, pluralIcu, toIetfTag, replaceLocaleInPath, getLangFromUrl } from './format'
+export type { PluralCategory, PluralPatterns } from './format'
+export { I18N_CONFIG } from './config'
+export {
+  DEFAULT_LOCALE,
+  ENABLE_MISSING_TRANSLATION_BANNER,
+  LANG_COOKIE_NAME,
+  LANGUAGES,
+  SUPPORTED_LOCALES,
+} from './constants'
+export type { Language, SupportedLocales } from './constants'
+export { LocaleSchema } from './schema'
+export type { Namespace, PickSchema } from './schema'
+export { checkMissingTranslation, resolveLocale, resolveLocaleForTranslations } from './resolve-locale'
+export type { I18nBindings, I18nConfig, I18nLanguage, I18nLocales, Locale } from './types'

package/src/schema.ts

@@ -0,0 +1,28 @@
+import { z } from 'astro/zod'
+
+import { SUPPORTED_LOCALES } from './constants'
+import { NAMESPACE_KEYS } from 'virtual:@edgekits/astro-i18n/runtime-constants'
+
+// Generated namespaces and real supported locales that have translations: the project's
+// runtime-constants.ts through the virtual module (empty lists until the CLI generates it)
+export * from 'virtual:@edgekits/astro-i18n/runtime-constants'
+
+// Locale schema from shared constant
+export const LocaleSchema = z.enum(SUPPORTED_LOCALES)
+
+// Runtime safety: if namespaces are empty (fresh clone), fall back to string
+const hasNamespaces = (NAMESPACE_KEYS as readonly string[]).length > 0
+
+export const NamespaceSchema = hasNamespaces ? z.enum(NAMESPACE_KEYS as [string, ...string[]]) : z.string()
+
+type GlobalSchema = I18n.Schema
+
+// Strictly bind the type to the keys of I18n.Schema.
+// If the interface is empty (e.g., on a fresh project clone), fall back to string.
+export type Namespace = keyof GlobalSchema extends never ? string : keyof GlobalSchema
+
+// Added intersection N & keyof GlobalSchema so the compiler
+// doesn't throw an error inside Pick when Namespace falls back to string.
+export type PickSchema<N extends Namespace> = [N] extends [keyof GlobalSchema]
+  ? Pick<GlobalSchema, N & keyof GlobalSchema>
+  : any

package/src/translations-keys.ts

@@ -0,0 +1,42 @@
+import { I18N_CONFIG } from './config'
+import type { Locale } from './constants'
+import { formatTranslationCacheUrl, formatTranslationKvKey } from './key-format'
+import type { Namespace } from './schema'
+
+/**
+ * Single source of truth for translation KV key construction.
+ *
+ * Used by both:
+ *   - fetcher.ts (runtime: cache.match / cache.put)
+ *   - the CLI (build: KV bulk data), through the same `key-format.ts`
+ *
+ * Format: <I18N_CONFIG.keyPrefix>:<namespace>:<locale>
+ */
+export function buildTranslationKvKey(locale: Locale, ns: Namespace): string {
+  return formatTranslationKvKey(I18N_CONFIG.keyPrefix, locale, ns)
+}
+
+/**
+ * Single source of truth for translation cache URL construction.
+ *
+ * Used by both:
+ *   - fetcher.ts (runtime: cache.match / cache.put)
+ *   - the CLI (build: Cloudflare Purge API), through the same `key-format.ts`
+ *
+ * The URL uses a static, non-versioned structure. Cache invalidation is
+ * handled explicitly via the Cloudflare Purge API in `edgekits-i18n migrate`
+ * rather than by changing the key on every deploy.
+ *
+ * Format: https://<I18N_CONFIG.keyPrefix>/<encodeURIComponent(i18n:<locale>:<namespace>)>
+ */
+export function buildTranslationCacheUrl(locale: Locale, ns: Namespace): string {
+  return formatTranslationCacheUrl(I18N_CONFIG.keyPrefix, locale, ns)
+}
+
+/**
+ * Build a Cache API Request object from a translation cache URL.
+ * The Cache API requires a Request object, not a plain string.
+ */
+export function buildTranslationCacheRequest(locale: Locale, ns: Namespace): Request {
+  return new Request(buildTranslationCacheUrl(locale, ns))
+}

package/src/types.ts

@@ -0,0 +1,119 @@
+/**
+ * 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 type I18nLanguage = { countryCode: string; name: string }
+
+export type I18nConfig = {
+  // The only source of truth for languages: the keys are the locales.
+  languages: Record<string, I18nLanguage>
+  defaultLocale: string
+  // The lang cookie the middleware keeps in sync with the URL locale.
+  cookie: { name: string; maxAge: number }
+  // Prefix of every translation KV key and the host of every edge-cache URL.
+  keyPrefix: string
+  missingTranslationBanner: boolean
+  routing: 'prefix'
+  // Where the CLI writes `fallbacks.generated.ts` and `runtime-constants.ts`,
+  // relative to the project root.
+  generatedDir?: string
+  // Where the CLI reads `<locale>/<namespace>.json`, relative to the project root.
+  localesDir?: string
+  // Geo-IP step of the middleware's locale fallback: ISO 3166-1 alpha-2 country code
+  // (uppercase, as `request.cf.country` sends it) → one of `languages`. Without it the
+  // step is skipped; the package ships no table of its own.
+  countryToLocale?: Record<string, string>
+  // The locale of the project's `.md` endpoints: a `.md` path is redirected once to
+  // `/<markdownLocale>/<rest>` (a leading locale segment replaced, otherwise kept). Without
+  // it, `.md` paths pass through the middleware untouched.
+  markdownLocale?: string
+}
+
+export const DEFAULT_GENERATED_DIR = 'src/i18n'
+export 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>
+
+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<const C extends I18nConfig>(
+  config: C & { countryToLocale?: Record<string, LocaleOf<C>>; markdownLocale?: LocaleOf<C> },
+): C {
+  const locales = Object.keys(config.languages ?? {})
+
+  if (locales.length === 0) {
+    throw new Error('[@edgekits/astro-i18n] `languages` must define at least one locale.')
+  }
+  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
+}
+
+/**
+ * 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>
+
+// Falls back to `string` while `I18nLocales` is empty, like `Namespace` over `I18n.Schema`.
+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
+}
+
+declare global {
+  // Augmented by the consumer's generated `i18n.generated.d.ts`.
+  namespace I18n {
+    interface Schema {}
+  }
+
+  // Set by the i18n middleware on every request.
+  namespace App {
+    interface Locals {
+      uiLocale: Locale
+      translationLocale: Locale
+      isMissingContent?: boolean
+    }
+  }
+}

package/src/virtual.d.ts

@@ -0,0 +1,23 @@
+// The virtual modules served by the integration's Vite plugin (src/integration/vite-plugin.ts),
+// declared for the package's own typecheck. A copy of `virtualModulesDeclaration('./types')`
+// (src/integration/virtual-types.ts), which consumers receive through `injectTypes`; edit
+// that function, then this file. test/virtual-types.test.ts fails while the two differ.
+
+declare module 'virtual:@edgekits/astro-i18n/config' {
+  const config: import('./types').I18nConfig
+  export default config
+}
+
+// The consumer's `<generatedDir>/runtime-constants.ts`, or a stub with empty lists.
+declare module 'virtual:@edgekits/astro-i18n/runtime-constants' {
+  export const NAMESPACE_KEYS: readonly string[]
+  export const LOCALES_WITH_TRANSLATIONS: readonly string[]
+  export const FULLY_TRANSLATED_LOCALES: readonly string[]
+}
+
+// The consumer's `<generatedDir>/fallbacks.generated.ts`, or an empty stub. Its exports
+// (`FALLBACK_<NAMESPACE>`) depend on the project's namespaces, so none are declared here:
+// the fetcher reads the module namespace by name.
+declare module 'virtual:@edgekits/astro-i18n/fallbacks' {
+  export {}
+}