@edgekits/astro-i18n 0.0.0-stage → 0.1.0

package/src/fetcher.ts

@@ -0,0 +1,304 @@
+import { env, waitUntil } from 'cloudflare:workers'
+import * as fallbacksModule from 'virtual:@edgekits/astro-i18n/fallbacks'
+
+import { assembleNamespace } from './assemble'
+import { buildTranslationKvKey, buildTranslationCacheRequest } from './translations-keys'
+import { parseBooleanFlag } from './parse-boolean'
+import type { Locale } from './constants'
+import type { Namespace, PickSchema } from './schema'
+import type { I18nBindings } from './types'
+
+// The bindings this module reads, typed by the package rather than the project's Env.
+const i18nEnv = env as unknown as I18nBindings
+
+// Optional fallbacks: the project's fallbacks.generated.ts if generated, otherwise an
+// empty stub module (no FALLBACK_* exports), served by the integration's Vite plugin.
+const FALLBACKS: Record<string, unknown> = fallbacksModule
+
+const KV_JSON_OPTIONS = { type: 'json' as const }
+
+/**
+ * Fetch translations from KV for a given locale and list of namespaces.
+ *
+ * Cache strategy — per-namespace static cache keys:
+ *
+ * Each namespace is cached individually under a static (non-versioned) URL:
+ *   https://<I18N_CONFIG.keyPrefix>/<encodeURIComponent(i18n:<locale>:<ns>)>
+ *
+ * Cache invalidation is handled explicitly by the Cloudflare Purge API
+ * in `edgekits-i18n migrate` — only namespaces whose content actually changed
+ * are purged, leaving untouched namespaces warm in the cache.
+ *
+ * Hot path (all namespaces cached):
+ *   Parallel cache.match() for each namespace → all HIT → merge each with
+ *   FALLBACK_* → return immediately. Zero KV reads.
+ *
+ * Partial or full cache miss:
+ *   Missing namespaces collected → single KV getAll() batch →
+ *   merge with FALLBACK_* → individual cache.put() per namespace → return.
+ *
+ * Every namespace — cached or freshly read — is assembled through
+ * assembleNamespace(), so a cache HIT is merged with FALLBACK_* exactly like a
+ * miss. An entry cached before a schema addition therefore degrades to
+ * default-locale text for the keys it predates instead of yielding `undefined`
+ * (ADR-0014).
+ *
+ * KV unavailable:
+ *   Falls back to FALLBACK_* compiled dictionaries (always available).
+ *   If none were generated, returns empty objects per namespace — no crash.
+ */
+export async function fetchTranslations<N extends Namespace>(
+  locale: Locale,
+  namespaces: readonly N[],
+): Promise<PickSchema<N>> {
+  const useCache = isCacheEnabled()
+
+  if (!useCache) {
+    debug('i18n cache DISABLED, using KV only', { locale, namespaces })
+    return fetchAllFromKV(locale, namespaces)
+  }
+
+  const { cache } = getEdgeCache()
+
+  if (!cache) {
+    // Cache API unavailable (e.g. Astro dev server without Miniflare)
+    debug('i18n Cache API unavailable, using KV only', {
+      locale,
+      namespaces,
+    })
+    return fetchAllFromKV(locale, namespaces)
+  }
+
+  // ---------------------------------------------------------------------------
+  // 1. Check Cache API in parallel for each namespace individually
+  // ---------------------------------------------------------------------------
+
+  const cacheResults = await Promise.all(
+    namespaces.map(async (ns) => {
+      const cacheRequest = buildTranslationCacheRequest(locale, ns)
+      try {
+        const cached = await cache.match(cacheRequest)
+        if (cached) {
+          return { ns, data: await cached.json(), hit: true }
+        }
+      } catch (error) {
+        debug(`i18n cache READ error for ${ns}`, error)
+      }
+      return { ns, data: null, hit: false }
+    }),
+  )
+
+  // ---------------------------------------------------------------------------
+  // 2. Separate hits from misses
+  // ---------------------------------------------------------------------------
+
+  const finalData: Partial<PickSchema<N>> = {}
+  const missingNamespaces: N[] = []
+
+  for (const { ns, data, hit } of cacheResults) {
+    if (hit) {
+      // Cached entries are merged with FALLBACK_* too. A namespace cached before
+      // a schema addition is missing the newer keys; without this merge it would
+      // reach pages as-is and any read of a new key would throw (ADR-0014).
+      ;(finalData as any)[ns] = assembleNamespace(data, getFallback(ns))
+    } else {
+      missingNamespaces.push(ns)
+    }
+  }
+
+  // All namespaces were in cache — return immediately, zero KV reads
+  if (missingNamespaces.length === 0) {
+    debug('i18n cache FULL HIT', { locale, namespaces })
+    return finalData as PickSchema<N>
+  }
+
+  debug('i18n cache PARTIAL/FULL MISS', {
+    locale,
+    hit: namespaces.length - missingNamespaces.length,
+    miss: missingNamespaces.length,
+  })
+
+  // ---------------------------------------------------------------------------
+  // 3. Batch KV read for missing namespaces only
+  // ---------------------------------------------------------------------------
+
+  const missingKvKeys = missingNamespaces.map((ns) => buildTranslationKvKey(locale, ns))
+
+  let kvResults = new Map<string, unknown | null>()
+  let kvFailed = false
+
+  try {
+    kvResults = (await i18nEnv.TRANSLATIONS.get(missingKvKeys, KV_JSON_OPTIONS)) as Map<string, unknown | null>
+
+    debug('i18n KV batch OK', { locale, missingNamespaces })
+  } catch (error) {
+    kvFailed = true
+    debug('i18n KV ERROR, using FALLBACK_* for missing namespaces', error)
+  }
+
+  // ---------------------------------------------------------------------------
+  // 4. Assemble missing namespaces + schedule individual cache writes
+  // ---------------------------------------------------------------------------
+
+  const putPromises: Promise<void>[] = []
+
+  for (let i = 0; i < missingNamespaces.length; i++) {
+    const ns = missingNamespaces[i] as N
+    const kvKey = missingKvKeys[i] as string
+
+    // Use KV value if available, otherwise empty object (fallback will fill it)
+    const kvValue = kvFailed ? {} : ((kvResults.get(kvKey) as object) ?? {})
+
+    // Merge with FALLBACK_* compiled dictionary if present
+    const fallback = getFallback(ns)
+
+    const nsData = assembleNamespace(kvValue, fallback)
+
+    if (kvFailed && !fallback) {
+      debug(`i18n namespace "${ns}" unavailable: KV failed and no fallback`)
+    }
+
+    ;(finalData as any)[ns] = nsData
+
+    // Cache the resolved namespace individually with a long TTL.
+    // Invalidation is handled explicitly via Cloudflare Purge API —
+    // no TTL-based expiry needed here.
+    const cacheRequest = buildTranslationCacheRequest(locale, ns)
+    const response = new Response(JSON.stringify(nsData), {
+      headers: {
+        'Content-Type': 'application/json; charset=utf-8',
+        'Cache-Control': 'public, s-maxage=31536000, immutable',
+      },
+    })
+
+    putPromises.push(
+      cache.put(cacheRequest, response.clone()).catch((error: unknown) => {
+        const errorMsg = error instanceof Error ? error.message : String(error)
+        debug(`i18n cache WRITE error for ${ns}`, errorMsg)
+      }),
+    )
+  }
+
+  // ---------------------------------------------------------------------------
+  // 5. Schedule cache writes as background tasks
+  // ---------------------------------------------------------------------------
+
+  if (putPromises.length > 0) {
+    // Top-level waitUntil (cloudflare:workers): same semantics as
+    // ctx.waitUntil, no need to plumb an ExecutionContext through callers.
+    // putPromises only exist when the Cache API is available, so this never
+    // runs in plain `astro dev`.
+    waitUntil(Promise.all(putPromises))
+
+    debug('i18n cache PUT scheduled', { locale, missingNamespaces })
+  }
+
+  return finalData as PickSchema<N>
+}
+
+// ---------------------------------------------------------------------------
+// KV helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch all requested namespaces directly from KV, bypassing the cache.
+ * Used when caching is disabled or the Cache API is unavailable.
+ */
+async function fetchAllFromKV<N extends Namespace>(locale: Locale, namespaces: readonly N[]): Promise<PickSchema<N>> {
+  const keys = namespaces.map((ns) => buildTranslationKvKey(locale, ns))
+
+  let kvResults = new Map<string, unknown | null>()
+  let kvFailed = false
+
+  try {
+    kvResults = (await i18nEnv.TRANSLATIONS.get(keys, KV_JSON_OPTIONS)) as Map<string, unknown | null>
+  } catch (error) {
+    kvFailed = true
+    debug('i18n KV ERROR (cache bypassed), using FALLBACK_* for all namespaces', error)
+  }
+
+  if (kvFailed) {
+    return buildFallbackOnly(namespaces)
+  }
+
+  const data: Partial<PickSchema<N>> = {}
+
+  for (let i = 0; i < namespaces.length; i++) {
+    const ns = namespaces[i]
+    const kvValue = kvResults.get(keys[i] as string) as object | null
+    ;(data as any)[ns] = assembleNamespace(kvValue, getFallback(ns as N))
+  }
+
+  return data as PickSchema<N>
+}
+
+/**
+ * Look up the compiled FALLBACK_* dictionary for a namespace, if one was generated.
+ */
+function getFallback(ns: Namespace): unknown {
+  return FALLBACKS[`FALLBACK_${String(ns).toUpperCase()}`]
+}
+
+/**
+ * Build a payload using only FALLBACK_* compiled dictionaries.
+ * Used when KV is completely unavailable.
+ */
+function buildFallbackOnly<N extends Namespace>(namespaces: readonly N[]): PickSchema<N> {
+  const data: Partial<PickSchema<N>> = {}
+
+  for (const ns of namespaces) {
+    ;(data as any)[ns] = getFallback(ns) ?? {}
+  }
+
+  return data as PickSchema<N>
+}
+
+// ---------------------------------------------------------------------------
+// Runtime helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Narrow the global `caches` to the minimal shape this module needs.
+ * (waitUntil comes straight from 'cloudflare:workers' — no ctx plumbing.)
+ */
+function getEdgeCache(): {
+  cache: { match: any; put: any } | null
+} {
+  const cacheStorage = caches as { default?: { match: any; put: any } }
+
+  return {
+    cache: cacheStorage?.default ?? null,
+  }
+}
+
+/**
+ * Determine whether edge caching is enabled.
+ *
+ * Wrangler var:
+ *   I18N_CACHE = "on" | "off" | "true" | "false" | "1" | "0"
+ *
+ * After adding the variable:
+ *   - Update wrangler.jsonc / wrangler.toml or .dev.vars
+ *   - Run: wrangler types (if the project generates its Env)
+ */
+function isCacheEnabled(): boolean {
+  return parseBooleanFlag(i18nEnv.I18N_CACHE, /* defaultValue */ true)
+}
+
+/**
+ * Debug logger controlled by a Wrangler variable.
+ *
+ * Wrangler var:
+ *   DEBUG_I18N = "on" | "off" | "true" | "false" | "1" | "0"
+ *
+ * After adding the variable:
+ *   - Update wrangler.jsonc / wrangler.toml or .dev.vars
+ *   - Run: wrangler types (if the project generates its Env)
+ */
+function debug(...args: unknown[]): void {
+  const enabled = parseBooleanFlag(i18nEnv.DEBUG_I18N, /* defaultValue */ false)
+  if (!enabled) return
+
+  // eslint-disable-next-line no-console
+  console.log(...args)
+}

package/src/format.ts

@@ -0,0 +1,107 @@
+// Sanitizer: Turns <script> into &lt;script&gt;
+function escapeHtml(unsafe: string | number): string {
+  return String(unsafe)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#039;')
+}
+
+type TemplateValues = Record<string, string | number>
+
+// `./format` is a Node-safe entry: under plain Node (a project's unit tests, `astro sync`)
+// there is no `import.meta.env`, and a missing one counts as "not production", so the
+// dev warnings below still fire instead of throwing.
+function isProd(): boolean {
+  return import.meta.env?.PROD === true
+}
+
+/**
+ * Interpolates {placeholders} in a template string and escapes values.
+ * - If `template` is undefined/null, returns an empty string (and logs in dev).
+ * - If `values` is undefined, returns the template unchanged.
+ */
+export function fmt(template: string | null | undefined, values?: TemplateValues): string {
+  if (template == null) {
+    if (!isProd()) {
+      console.warn('[i18n] fmt() called with null/undefined template')
+    }
+    return ''
+  }
+
+  if (!values) return template
+
+  return template.replace(/{([^}]+)}/g, (match, key) => {
+    const replacement = values[key]
+
+    if (replacement === undefined || replacement === null) {
+      return match
+    }
+
+    return escapeHtml(replacement)
+  })
+}
+
+/**
+ * Simple two-form plural helper.
+ * Good for English-like languages where "1" vs "other" is enough.
+ */
+export function plural(count: number, singular: string, plural: string): string {
+  return count === 1 ? singular : fmt(plural, { count })
+}
+
+/**
+ * ICU-style plural categories used by Intl.PluralRules.
+ */
+export type PluralCategory = 'zero' | 'one' | 'two' | 'few' | 'many' | 'other'
+
+export type PluralPatterns = Partial<Record<PluralCategory, string>>
+
+/**
+ * Advanced plural helper using Intl.PluralRules + fmt().
+ *
+ * - `locale` controls plural categories (en, de, es, ja, ...).
+ * - `patterns` comes from KV (e.g. { zero, one, other }).
+ * - Missing categories fall back to `other`.
+ *
+ * Example:
+ *   pluralIcu(5, 'en', {
+ *     zero: 'No items',
+ *     one: '{count} item',
+ *     other: '{count} items'
+ *   })
+ */
+export function pluralIcu(count: number, locale: string, patterns: PluralPatterns): string {
+  const rules = new Intl.PluralRules(locale)
+  const cat = rules.select(count) as PluralCategory
+
+  const template =
+    patterns[cat] ??
+    patterns.other ??
+    (isProd() ? '' : (console.warn('[i18n] pluralIcu(): missing "other" pattern'), ''))
+
+  return fmt(template, { count })
+}
+
+// Used in the LanguageSwitcher and SeoHreflangs components
+export function replaceLocaleInPath(currentPath: string, currentLocale: string, newLocale: string): string {
+  const prefixRegex = new RegExp(`^/${currentLocale}/`)
+  return currentPath.replace(prefixRegex, `/${newLocale}/`)
+}
+
+// Used in the LanguageSwitcher component
+export function getLangFromUrl(pathname: string) {
+  // Remove leading/trailing slashes: '/en/about/' -> 'en/about'
+  const cleaned = pathname.replace(/^\/+|\/+$/g, '')
+  const [lang] = cleaned.split('/')
+  return lang
+}
+
+// Converts a URL locale code to an IETF BCP 47 language tag.
+// Used for the HTML lang attribute and hreflang values.
+// 'pt-br' → 'pt-BR', 'en-us' → 'en-US', 'en' → 'en'
+export function toIetfTag(locale: string): string {
+  const [lang, region] = locale.split('-')
+  return region ? `${lang}-${region.toUpperCase()}` : locale
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+// The config-time entry: what `astro.config` and `edgekits-i18n.config.ts` import.
+// Pure under Node: nothing here reaches a virtual module or `cloudflare:workers`.
+export { edgekitsI18n, type EdgekitsI18nOptions } from './integration/index.ts'
+export {
+  defineI18nConfig,
+  type I18nBindings,
+  type I18nConfig,
+  type I18nLanguage,
+  type I18nLocales,
+  type Locale,
+} from './types.ts'

package/src/integration/index.ts

@@ -0,0 +1,136 @@
+import type { AstroConfig, AstroIntegration } from 'astro'
+
+import { DEFAULT_GENERATED_DIR, defineI18nConfig, type I18nConfig } from '../types.ts'
+import { i18nVitePlugin } from './vite-plugin.ts'
+import { virtualModulesDeclaration } from './virtual-types.ts'
+
+export type EdgekitsI18nOptions = {
+  // 'auto' registers the i18n middleware; 'manual' leaves it to the project, which
+  // then imports `i18nMiddleware` and places it in its own sequence.
+  middleware?: 'auto' | 'manual'
+}
+
+const MIDDLEWARE_MODES = ['auto', 'manual'] as const
+
+export const PACKAGE_NAME = '@edgekits/astro-i18n'
+
+/**
+ * The Astro integration. Build time only: it runs in Node while Astro loads its
+ * config, so it reaches the engine's runtime modules through nothing but the Vite
+ * plugin's virtual modules.
+ */
+export function edgekitsI18n(config: I18nConfig, options: EdgekitsI18nOptions = {}): AstroIntegration {
+  const i18nConfig = defineI18nConfig(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'.`,
+    )
+  }
+
+  return {
+    name: '@edgekits/astro-i18n',
+    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.
+        if (astroConfig.i18n) assertAstroI18n(astroConfig.i18n, i18nConfig)
+
+        updateConfig({
+          vite: {
+            plugins: [i18nVitePlugin(i18nConfig, generatedDir)],
+            // The runtime ships as source and imports the virtual modules above: Vite
+            // must process it rather than hand it to Node as an external dependency.
+            ssr: { noExternal: [PACKAGE_NAME] },
+          },
+          ...(astroConfig.i18n ? {} : { i18n: astroI18n(i18nConfig) }),
+        })
+
+        if (middleware === 'auto') {
+          addMiddleware({ entrypoint: '@edgekits/astro-i18n/middleware', order: 'pre' })
+        }
+      },
+      'astro:config:done': ({ injectTypes }) => {
+        injectTypes({ filename: 'locales.d.ts', content: localesDeclaration(Object.keys(i18nConfig.languages)) })
+        // The shipped runtime imports the virtual modules; a consumer's program needs their
+        // declarations too. A separate file: these must not sit in a module (see virtual-types.ts).
+        injectTypes({ filename: 'virtual-modules.d.ts', content: virtualModulesDeclaration(PACKAGE_NAME) })
+      },
+    },
+  }
+}
+
+// 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).
+const LOCALE_MODULES = ['@edgekits/astro-i18n', '@edgekits/astro-i18n/runtime']
+
+/**
+ * Augments `I18nLocales` with the configured locales, so `Locale` narrows from
+ * `string` to their union in the project, through both entries. The `export {}` keeps
+ * the file a module: without it `declare module` would replace the package's types
+ * instead of merging.
+ */
+export function localesDeclaration(locales: readonly string[]): string {
+  const members = locales.map((locale) => `    ${JSON.stringify(locale)}: true`)
+
+  return [
+    'export {}',
+    ...LOCALE_MODULES.flatMap((specifier) => [
+      '',
+      `declare module '${specifier}' {`,
+      '  interface I18nLocales {',
+      ...members,
+      '  }',
+      '}',
+    ]),
+    '',
+  ].join('\n')
+}
+
+/**
+ * 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.
+ */
+export function astroI18n(config: I18nConfig): NonNullable<AstroConfig['i18n']> {
+  return {
+    locales: Object.keys(config.languages),
+    defaultLocale: config.defaultLocale,
+    routing: { prefixDefaultLocale: true, redirectToDefaultLocale: false, fallbackType: 'redirect' },
+  }
+}
+
+/**
+ * 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.
+ */
+function assertAstroI18n(block: NonNullable<AstroConfig['i18n']>, config: I18nConfig): void {
+  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) {
+    throw new Error(
+      `[@edgekits/astro-i18n] Astro \`i18n.locales\` is missing ${missing.join(', ')} from \`languages\`. ` +
+        'Add them, or remove the `i18n` block from astro.config and the integration sets it for you.',
+    )
+  }
+  if (block.defaultLocale !== config.defaultLocale) {
+    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.',
+    )
+  }
+}
+
+function trimSlashes(path: string): string {
+  return path.replace(/^\/+|\/+$/g, '')
+}

package/src/integration/virtual-types.ts

@@ -0,0 +1,34 @@
+/**
+ * The declarations of the three `virtual:@edgekits/astro-i18n/*` modules, in one place
+ * for both programs that need them:
+ *   - the package's own typecheck, through `src/virtual.d.ts` (`typesModule` './types');
+ *     test/virtual-types.test.ts fails when that file stops matching this text;
+ *   - the consumer's, through the `virtual-modules.d.ts` the integration injects
+ *     (`typesModule` the package name), because a consumer's program never loads
+ *     `src/virtual.d.ts` from node_modules but does import the shipped `src/` files.
+ *
+ * The text has no top-level import or export on purpose: in a module file,
+ * `declare module 'virtual:…'` would augment a module that does not exist instead of
+ * declaring one. (The injected `locales.d.ts` is a module, so it cannot carry these.)
+ */
+export function virtualModulesDeclaration(typesModule: string): string {
+  return `declare module 'virtual:@edgekits/astro-i18n/config' {
+  const config: import('${typesModule}').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 {}
+}
+`
+}

package/src/integration/vite-plugin.ts

@@ -0,0 +1,67 @@
+import { existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import type { AstroConfig } from 'astro'
+
+import type { I18nConfig } from '../types.ts'
+
+type VitePlugin = NonNullable<NonNullable<AstroConfig['vite']>['plugins']>[number]
+
+export const CONFIG_ID = 'virtual:@edgekits/astro-i18n/config'
+export const FALLBACKS_ID = 'virtual:@edgekits/astro-i18n/fallbacks'
+export const RUNTIME_CONSTANTS_ID = 'virtual:@edgekits/astro-i18n/runtime-constants'
+
+// Rollup convention: a `\0` prefix marks a resolved id as virtual, so no other plugin
+// tries to read it from disk.
+const resolved = (id: string) => `\0${id}`
+
+const STUBS: Record<string, string> = {
+  [FALLBACKS_ID]: 'export {}\n',
+  [RUNTIME_CONSTANTS_ID]: [
+    'export const NAMESPACE_KEYS = []',
+    'export const LOCALES_WITH_TRANSLATIONS = []',
+    'export const FULLY_TRANSLATED_LOCALES = []',
+    '',
+  ].join('\n'),
+}
+
+/**
+ * Serves the three virtual modules the engine imports:
+ *   - the config, serialised as JSON;
+ *   - the project's generated `fallbacks.generated.ts` and `runtime-constants.ts` under
+ *     `generatedDir`, or a stub module when the file does not exist (yet).
+ *
+ * The file check runs on every resolve, so files the CLI generates while the dev
+ * server runs are picked up on the next resolve.
+ */
+export function i18nVitePlugin(config: I18nConfig, generatedDir: URL): VitePlugin {
+  const generatedFiles: Record<string, string> = {
+    [FALLBACKS_ID]: toPath(new URL('fallbacks.generated.ts', generatedDir)),
+    [RUNTIME_CONSTANTS_ID]: toPath(new URL('runtime-constants.ts', generatedDir)),
+  }
+
+  return {
+    name: '@edgekits/astro-i18n',
+    resolveId(id: string) {
+      if (id === CONFIG_ID) return resolved(id)
+
+      const file = generatedFiles[id]
+      if (file === undefined) return undefined
+
+      return existsSync(file) ? file : resolved(id)
+    },
+    load(id: string) {
+      if (id === resolved(CONFIG_ID)) return `export default ${JSON.stringify(config)}\n`
+
+      for (const [virtualId, stub] of Object.entries(STUBS)) {
+        if (id === resolved(virtualId)) return stub
+      }
+
+      return undefined
+    },
+  }
+}
+
+// Vite ids use forward slashes on every platform.
+function toPath(url: URL): string {
+  return fileURLToPath(url).replace(/\\/g, '/')
+}

package/src/key-format.ts

@@ -0,0 +1,17 @@
+/**
+ * The translation KV key and edge-cache URL formats, as pure functions of the key
+ * prefix. Shared by the runtime (`translations-keys.ts`, prefix from the virtual config)
+ * and the CLI (prefix from the loaded config), so the key a value is stored under and
+ * the URL a purge targets can never drift apart. Pinned by `test/i18n-keys.test.ts`.
+ */
+
+// Format: <keyPrefix>:<namespace>:<locale>
+export function formatTranslationKvKey(keyPrefix: string, locale: string, ns: string): string {
+  return `${keyPrefix}:${ns}:${locale}`
+}
+
+// Format: https://<keyPrefix>/<encodeURIComponent(i18n:<locale>:<namespace>)>
+export function formatTranslationCacheUrl(keyPrefix: string, locale: string, ns: string): string {
+  const cacheId = `i18n:${locale}:${ns}`
+  return `https://${keyPrefix}/${encodeURIComponent(cacheId)}`
+}