@edgekits/astro-i18n 0.0.0-stage → 0.1.0

package/dist/integration/index.d.ts

@@ -0,0 +1,26 @@
+import type { AstroConfig, AstroIntegration } from 'astro';
+import { type I18nConfig } from '../types.ts';
+export type EdgekitsI18nOptions = {
+    middleware?: 'auto' | 'manual';
+};
+export declare 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 declare function edgekitsI18n(config: I18nConfig, options?: EdgekitsI18nOptions): AstroIntegration;
+/**
+ * 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 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.
+ */
+export declare function astroI18n(config: I18nConfig): NonNullable<AstroConfig['i18n']>;

package/dist/integration/index.js

@@ -0,0 +1,103 @@
+import { DEFAULT_GENERATED_DIR, defineI18nConfig } from "../types.js";
+import { i18nVitePlugin } from "./vite-plugin.js";
+import { virtualModulesDeclaration } from "./virtual-types.js";
+const MIDDLEWARE_MODES = ['auto', 'manual'];
+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, options = {}) {
+    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) {
+    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) {
+    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, 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) {
+        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) {
+    return path.replace(/^\/+|\/+$/g, '');
+}

package/dist/integration/virtual-types.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 declare function virtualModulesDeclaration(typesModule: string): string;

package/dist/integration/virtual-types.js

@@ -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) {
+    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/dist/integration/vite-plugin.d.ts

@@ -0,0 +1,17 @@
+import type { AstroConfig } from 'astro';
+import type { I18nConfig } from '../types.ts';
+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";
+export declare const RUNTIME_CONSTANTS_ID = "virtual:@edgekits/astro-i18n/runtime-constants";
+/**
+ * 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 declare function i18nVitePlugin(config: I18nConfig, generatedDir: URL): VitePlugin;
+export {};

package/dist/integration/vite-plugin.js

@@ -0,0 +1,56 @@
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+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) => `\0${id}`;
+const STUBS = {
+    [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, generatedDir) {
+    const generatedFiles = {
+        [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) {
+            if (id === CONFIG_ID)
+                return resolved(id);
+            const file = generatedFiles[id];
+            if (file === undefined)
+                return undefined;
+            return existsSync(file) ? file : resolved(id);
+        },
+        load(id) {
+            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) {
+    return fileURLToPath(url).replace(/\\/g, '/');
+}

package/dist/key-format.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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`.
+ */
+export declare function formatTranslationKvKey(keyPrefix: string, locale: string, ns: string): string;
+export declare function formatTranslationCacheUrl(keyPrefix: string, locale: string, ns: string): string;

package/dist/key-format.js

@@ -0,0 +1,15 @@
+/**
+ * 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, locale, ns) {
+    return `${keyPrefix}:${ns}:${locale}`;
+}
+// Format: https://<keyPrefix>/<encodeURIComponent(i18n:<locale>:<namespace>)>
+export function formatTranslationCacheUrl(keyPrefix, locale, ns) {
+    const cacheId = `i18n:${locale}:${ns}`;
+    return `https://${keyPrefix}/${encodeURIComponent(cacheId)}`;
+}

package/dist/types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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 = {
+    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;
+}
+declare global {
+    namespace I18n {
+        interface Schema {
+        }
+    }
+    namespace App {
+        interface Locals {
+            uiLocale: Locale;
+            translationLocale: Locale;
+            isMissingContent?: boolean;
+        }
+    }
+}
+export {};

package/dist/types.js

@@ -0,0 +1,38 @@
+/**
+ * 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.');
+    }
+    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;
+}

package/package.json

@@ -1,6 +1,79 @@
 {
   "name": "@edgekits/astro-i18n",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.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",
+    "astro-integration",
+    "i18n",
+    "cloudflare",
+    "cloudflare-workers",
+    "kv",
+    "edge"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "author": "Gary Stupak",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/EdgeKits/astro-i18n"
+  },
+  "homepage": "https://github.com/EdgeKits/astro-i18n#readme",
+  "bugs": {
+    "url": "https://github.com/EdgeKits/astro-i18n/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./config": "./src/config.entry.ts",
+    "./format": "./src/format.ts",
+    "./runtime": "./src/runtime.ts",
+    "./middleware": "./src/middleware.ts",
+    "./components/*": "./src/components/*.astro",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "edgekits-i18n": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "node --import ./test/register.mjs --test test/**/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "dependencies": {
+    "jiti": "^2.7.0",
+    "jsonc-parser": "^3.3.1"
+  },
+  "peerDependencies": {
+    "@astrojs/cloudflare": "^14.3.0",
+    "astro": "^7.3.0",
+    "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"
+  }
+}

package/src/assemble.ts

@@ -0,0 +1,29 @@
+import { deepMerge } from './deep-merge'
+
+/**
+ * Assemble a single translation namespace from a raw value and its compiled
+ * fallback dictionary.
+ *
+ * This is the ONLY place namespace assembly happens: `fetchTranslations` routes
+ * its cache-HIT branch, its cache-miss/KV branch and `fetchAllFromKV` through it,
+ * so a cached namespace and a freshly read one can never diverge in shape.
+ *
+ * Semantics (unchanged from the original miss path):
+ *   - the fallback provides the full known key set,
+ *   - the raw value (cached entry or KV read) overrides it wherever it has a value,
+ *   - `null` / `undefined` are tolerated for either argument.
+ *
+ * Consequence for stale cache entries: a namespace cached before a schema addition
+ * degrades to default-locale text for the keys it predates instead of handing pages
+ * `undefined` (see ADR-0014 and the 2026-07-18 `/en/blog/` incident).
+ *
+ * Deliberately pure — no `cloudflare:workers` imports, so it is testable under
+ * plain Node (`npm test`).
+ */
+export function assembleNamespace(rawValue: unknown, fallback: unknown): object {
+  const raw = (rawValue as object | null | undefined) ?? {}
+
+  if (!fallback) return raw
+
+  return deepMerge(fallback as object, raw)
+}