@edgekits/astro-i18n 0.0.0-stage → 0.1.1

package/dist/cli/purge.js

@@ -0,0 +1,94 @@
+// ---------------------------------------------------------------------------
+// Cloudflare Cache Purge API
+// ---------------------------------------------------------------------------
+/**
+ * Purge a list of URLs from Cloudflare's edge cache via the Purge API.
+ *
+ * Handles Cloudflare's rate limits automatically:
+ *   - Max 100 URLs per request (max operations per request)
+ *   - Max 800 URLs per second on Free plan (8 chunks of 100)
+ *   - HTTP 429: up to MAX_RETRIES retries per chunk, waiting `Retry-After` seconds when
+ *     the response sends it, otherwise 2 s, 4 s, 8 s… (every wait capped at
+ *     MAX_RETRY_WAIT_MS); then the chunk counts as failed.
+ *
+ * Reference: https://developers.cloudflare.com/cache/how-to/purge-cache/
+ *
+ * `deps` replaces `fetch` and the wait in tests.
+ *
+ * @returns true if all chunks succeeded, false if any chunk failed
+ */
+export async function purgeTranslationsCache(zoneId, apiToken, urls, deps = {}) {
+    if (!urls.length)
+        return true;
+    const { fetch: fetchFn = fetch, sleep: wait = sleep } = deps;
+    // Cloudflare limit: max 100 URLs per single purge request
+    const CHUNK_SIZE = 100;
+    // Cloudflare Free plan limit: 800 URLs/sec = 8 chunks of 100 per second
+    // Pro and above: 1500 URLs/sec — CHUNK_SIZE * MAX_CHUNKS_PER_SEC covers Free plan
+    const MAX_CHUNKS_PER_SEC = 8;
+    console.log(`[i18n] Purging cache for ${urls.length} URL(s)...`);
+    // 429 retries of the current chunk; reset when a chunk goes through.
+    let retries = 0;
+    for (let i = 0; i < urls.length; i += CHUNK_SIZE) {
+        const chunk = urls.slice(i, i + CHUNK_SIZE);
+        const currentChunkIndex = Math.floor(i / CHUNK_SIZE) + 1;
+        try {
+            const response = await fetchFn(`https://api.cloudflare.com/client/v4/zones/${zoneId}/purge_cache`, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${apiToken}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({ files: chunk }),
+            });
+            // Rate limit hit — wait and retry the same chunk, a bounded number of times
+            if (response.status === 429) {
+                if (retries >= MAX_RETRIES) {
+                    console.error(`[i18n] [Chunk ${currentChunkIndex}] Still rate-limited after ${MAX_RETRIES} retries; ` +
+                        `giving up on ${chunk.length} URL(s):\n` +
+                        chunk.map((url) => `  - ${url}`).join('\n'));
+                    return false;
+                }
+                retries++;
+                const waitMs = retryWaitMs(response.headers.get('retry-after'), retries);
+                console.warn(`[i18n] [Chunk ${currentChunkIndex}] Rate limit hit, retry ${retries}/${MAX_RETRIES} in ${waitMs}ms...`);
+                await wait(waitMs);
+                i -= CHUNK_SIZE; // retry same chunk
+                continue;
+            }
+            if (!response.ok) {
+                const errorData = await response.text();
+                console.error(`[i18n] [Chunk ${currentChunkIndex}] Cloudflare API error:`, errorData);
+                return false;
+            }
+            retries = 0;
+            console.log(`[i18n] [Chunk ${currentChunkIndex}] Purged ${chunk.length} URL(s).`);
+            // After sending MAX_CHUNKS_PER_SEC chunks (= 800 URLs), pause for 1 second
+            // to stay within the Free plan rate limit before the next batch
+            if (currentChunkIndex % MAX_CHUNKS_PER_SEC === 0 && i + CHUNK_SIZE < urls.length) {
+                console.log(`[i18n] Reached 800 URL/sec limit. Waiting 1000ms before next batch...`);
+                await wait(1000);
+            }
+        }
+        catch (error) {
+            console.error(`[i18n] [Chunk ${currentChunkIndex}] Network error calling Cloudflare API:`, error);
+            return false;
+        }
+    }
+    return true;
+}
+export const MAX_RETRIES = 5;
+export const MAX_RETRY_WAIT_MS = 30_000;
+/**
+ * The wait before 429 retry number `attempt` (1-based): `Retry-After` in seconds when
+ * the header holds a non-negative number, otherwise 2 s doubled per attempt. Either way
+ * capped at MAX_RETRY_WAIT_MS, so a large header cannot stall the run.
+ */
+export function retryWaitMs(retryAfter, attempt) {
+    const seconds = retryAfter === null || retryAfter.trim() === '' ? NaN : Number(retryAfter);
+    const ms = Number.isFinite(seconds) && seconds >= 0 ? seconds * 1000 : 2000 * 2 ** (attempt - 1);
+    return Math.min(ms, MAX_RETRY_WAIT_MS);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/cli/wrangler.d.ts

@@ -0,0 +1,10 @@
+export declare const KV_BINDING = "TRANSLATIONS";
+export declare function getKvNamespaceId(root: string, binding: string): string;
+export declare function getWranglerVar(root: string, key: string): string | undefined;
+/**
+ * The absolute path of the project's wrangler entry (`bin.wrangler` in its package.json),
+ * resolved from `root` as the project itself would resolve it. `wrangler/package.json` is
+ * an exported subpath; `bin/` is not, hence the detour through the manifest. Throws when
+ * the project has no wrangler or its manifest declares no `bin.wrangler`.
+ */
+export declare function resolveWranglerBin(root: string): string;

package/dist/cli/wrangler.js

@@ -0,0 +1,71 @@
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { parse as parseJsonc, printParseErrorCode } from 'jsonc-parser';
+// ---------------------------------------------------------------------------
+// Wrangler config reader
+// Parses wrangler.jsonc to extract KV namespace IDs and vars by key.
+// Single source of truth — no hardcoded IDs or zone IDs in package.json.
+// ---------------------------------------------------------------------------
+export const KV_BINDING = 'TRANSLATIONS';
+function readWranglerConfig(root) {
+    const wranglerConfigPath = path.join(root, 'wrangler.jsonc');
+    if (!fs.existsSync(wranglerConfigPath)) {
+        console.error(`[i18n] wrangler.jsonc not found at ${wranglerConfigPath}`);
+        process.exit(1);
+    }
+    const raw = fs.readFileSync(wranglerConfigPath, 'utf8');
+    const errors = [];
+    const config = parseJsonc(raw, errors, { allowTrailingComma: true });
+    if (!config || typeof config !== 'object') {
+        console.error('[i18n] Failed to parse wrangler.jsonc — result is empty.');
+        for (const err of errors) {
+            const snippet = raw.slice(Math.max(0, err.offset - 10), err.offset + 20);
+            console.error(`  ${printParseErrorCode(err.error)} at offset ${err.offset}: ...${JSON.stringify(snippet)}...`);
+        }
+        process.exit(1);
+    }
+    return config;
+}
+export function getKvNamespaceId(root, binding) {
+    const config = readWranglerConfig(root);
+    const kvNamespaces = config.kv_namespaces;
+    const entry = kvNamespaces?.find((kv) => kv.binding === binding);
+    if (!entry) {
+        console.error(`[i18n] KV binding "${binding}" not found in wrangler.jsonc`);
+        process.exit(1);
+    }
+    return entry.id;
+}
+export function getWranglerVar(root, key) {
+    const config = readWranglerConfig(root);
+    const vars = config.vars;
+    return vars?.[key];
+}
+// ---------------------------------------------------------------------------
+// Wrangler binary
+// The CLI runs wrangler's JavaScript entry with the current Node binary, never through
+// a shell (no `.cmd` shim on Windows, nothing for a shell to interpret).
+// ---------------------------------------------------------------------------
+/**
+ * The absolute path of the project's wrangler entry (`bin.wrangler` in its package.json),
+ * resolved from `root` as the project itself would resolve it. `wrangler/package.json` is
+ * an exported subpath; `bin/` is not, hence the detour through the manifest. Throws when
+ * the project has no wrangler or its manifest declares no `bin.wrangler`.
+ */
+export function resolveWranglerBin(root) {
+    const requireFromRoot = createRequire(path.join(root, 'package.json'));
+    let manifestPath;
+    try {
+        manifestPath = requireFromRoot.resolve('wrangler/package.json');
+    }
+    catch {
+        throw new Error(`wrangler is not installed in ${root}. The CLI runs the project's own wrangler: install it there (npm i -D wrangler).`);
+    }
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    const bin = typeof manifest.bin === 'string' ? manifest.bin : manifest.bin?.wrangler;
+    if (!bin) {
+        throw new Error(`wrangler at ${path.dirname(manifestPath)} declares no bin.wrangler in its package.json.`);
+    }
+    return path.join(path.dirname(manifestPath), bin);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { edgekitsI18n, type EdgekitsI18nOptions } from './integration/index.ts';
+export { defineI18nConfig, type I18nBindings, type I18nConfig, type I18nLanguage, type I18nLocales, type Locale, } from './types.ts';

package/dist/index.js

@@ -0,0 +1,4 @@
+// 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 } from "./integration/index.js";
+export { defineI18nConfig, } from "./types.js";

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,80 @@
 {
   "name": "@edgekits/astro-i18n",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "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",
+    "prepublishOnly": "npm run build",
+    "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"
+  }
+}