@edgekits/i18n-core 0.2.1 → 0.3.0

package/dist/cli/wrangler.d.ts

@@ -1,6 +1,20 @@
 export declare const KV_BINDING = "TRANSLATIONS";
-export declare function getKvNamespaceId(wranglerConfigPath: string, binding: string): string;
-export declare function getWranglerVar(wranglerConfigPath: string, key: string): string | undefined;
+/** What the CLI reads from the Worker's wrangler config, for one environment or the top level. */
+export type WorkerSettings = {
+    kvId: string;
+    previewId?: string;
+    zoneId?: string;
+    otherEnvs: string[];
+    topLevelKvId?: string;
+    sameZoneScopes: string[];
+};
+/**
+ * The `binding` KV namespace and `CLOUDFLARE_ZONE_ID` of the top level, or of `env.<env>`
+ * when `env` is given: wrangler does not inherit `kv_namespaces` and `vars` into an
+ * environment, so nothing falls back to the top level. Exits, naming the file and the
+ * scope, when the environment or the binding (or its `id`) is missing.
+ */
+export declare function readWorkerSettings(wranglerConfigPath: string, binding: string, env?: string): WorkerSettings;
 /**
  * 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

package/dist/cli/wrangler.js

@@ -5,7 +5,8 @@ import { parse as parseJsonc, printParseErrorCode } from 'jsonc-parser';
 // ---------------------------------------------------------------------------
 // Wrangler config reader
 // Parses the Worker's wrangler.jsonc (the path `--wrangler` names, ./wrangler.jsonc by
-// default) to extract KV namespace IDs and vars by key.
+// default) for the translations binding and the zone id, at the top level or in one
+// `env.<name>`.
 // Single source of truth — no hardcoded IDs or zone IDs in package.json.
 // ---------------------------------------------------------------------------
 export const KV_BINDING = 'TRANSLATIONS';
@@ -27,20 +28,72 @@ function readWranglerConfig(wranglerConfigPath) {
     }
     return config;
 }
-export function getKvNamespaceId(wranglerConfigPath, binding) {
+function findBinding(scope, binding) {
+    const kvNamespaces = Array.isArray(scope?.kv_namespaces) ? scope.kv_namespaces : [];
+    return kvNamespaces.find((kv) => kv?.binding === binding);
+}
+/**
+ * The `binding` KV namespace and `CLOUDFLARE_ZONE_ID` of the top level, or of `env.<env>`
+ * when `env` is given: wrangler does not inherit `kv_namespaces` and `vars` into an
+ * environment, so nothing falls back to the top level. Exits, naming the file and the
+ * scope, when the environment or the binding (or its `id`) is missing.
+ */
+export function readWorkerSettings(wranglerConfigPath, binding, env) {
     const config = readWranglerConfig(wranglerConfigPath);
-    const kvNamespaces = config.kv_namespaces;
-    const entry = kvNamespaces?.find((kv) => kv.binding === binding);
+    const envs = (config.env ?? {});
+    let scope = config;
+    let where = wranglerConfigPath;
+    if (env !== undefined) {
+        if (!Object.hasOwn(envs, env) || typeof envs[env] !== 'object' || envs[env] === null) {
+            console.error(`[i18n] Environment "${env}" not found in ${wranglerConfigPath} (no env.${env}).`);
+            process.exit(1);
+        }
+        scope = envs[env];
+        where = `env.${env} of ${wranglerConfigPath}`;
+    }
+    const entry = findBinding(scope, binding);
     if (!entry) {
-        console.error(`[i18n] KV binding "${binding}" not found in ${wranglerConfigPath}`);
+        console.error(`[i18n] KV binding "${binding}" not found in ${where}` +
+            (env !== undefined ? ' (wrangler does not inherit kv_namespaces into an environment).' : ''));
+        process.exit(1);
+    }
+    if (typeof entry.id !== 'string') {
+        console.error(`[i18n] KV binding "${binding}" in ${where} has no id.`);
         process.exit(1);
     }
-    return entry.id;
+    const zoneId = zoneIdOf(scope);
+    const otherEnvs = env === undefined
+        ? Object.keys(envs).filter((name) => {
+            const other = findBinding(envs[name], binding);
+            return other !== undefined && other.id !== entry.id;
+        })
+        : [];
+    const topLevel = findBinding(config, binding);
+    const scopes = [
+        ['the top level', config],
+        ...Object.keys(envs).map((name) => [`env.${name}`, envs[name]]),
+    ];
+    const sameZoneScopes = zoneId === undefined
+        ? []
+        : scopes
+            .filter(([name]) => name !== (env === undefined ? 'the top level' : `env.${env}`))
+            .filter(([, other]) => {
+            const otherEntry = findBinding(other, binding);
+            return otherEntry !== undefined && otherEntry.id !== entry.id && zoneIdOf(other) === zoneId;
+        })
+            .map(([name]) => name);
+    return {
+        kvId: entry.id,
+        previewId: typeof entry.preview_id === 'string' ? entry.preview_id : undefined,
+        zoneId,
+        otherEnvs,
+        topLevelKvId: typeof topLevel?.id === 'string' ? topLevel.id : undefined,
+        sameZoneScopes,
+    };
 }
-export function getWranglerVar(wranglerConfigPath, key) {
-    const config = readWranglerConfig(wranglerConfigPath);
-    const vars = config.vars;
-    return vars?.[key];
+function zoneIdOf(scope) {
+    const zoneId = scope?.vars?.CLOUDFLARE_ZONE_ID;
+    return typeof zoneId === 'string' && zoneId !== '' ? zoneId : undefined;
 }
 // ---------------------------------------------------------------------------
 // Wrangler binary

package/dist/create-i18n.js

@@ -35,10 +35,10 @@ export function createI18n(config, generated, bindings) {
     }
     /**
      * Single source of truth for translation cache URL construction, shared with the CLI
-     * (Purge API) through `key-format.ts`. The URL is static, not versioned: invalidation
-     * is the explicit purge in `edgekits-i18n migrate`.
+     * (Purge API) through `key-format.ts`. The URL carries the entry format (`v2`), not a
+     * content version: invalidation is the explicit purge in `edgekits-i18n migrate`.
      *
-     * Format: https://<keyPrefix>/<encodeURIComponent(i18n:<locale>:<namespace>)>
+     * Format: https://<keyPrefix>/<encodeURIComponent(i18n:v2:<locale>:<namespace>)>
      */
     function buildTranslationCacheUrl(locale, ns) {
         return formatTranslationCacheUrl(config.keyPrefix, locale, ns);

package/dist/deep-merge.d.ts

@@ -3,6 +3,9 @@
  * - `base` provides known structure (fallback)
  * - `overrides` can provide partial values
  * - Both types are preserved and merged correctly
- * - `__proto__`, `constructor` and `prototype` keys in `overrides` are skipped
+ * - `__proto__` in `overrides` is skipped: JSON.parse creates it as an own key, so a KV
+ *   value could carry one, and assigning it would replace the result's prototype.
+ *   `constructor` and `prototype` are ordinary keys: assigning them on the fresh result
+ *   object creates own properties and reaches no prototype.
  */
 export declare function deepMerge<A extends object, B extends Partial<A>>(base: A, overrides: B): A;

package/dist/deep-merge.js

@@ -1,23 +1,24 @@
 function isObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-// Keys that would reach an object's prototype instead of its own properties. JSON.parse
-// creates `__proto__` as an own key, so a KV value could carry one.
-const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
 /**
  * Deep-merge two dictionaries.
  * - `base` provides known structure (fallback)
  * - `overrides` can provide partial values
  * - Both types are preserved and merged correctly
- * - `__proto__`, `constructor` and `prototype` keys in `overrides` are skipped
+ * - `__proto__` in `overrides` is skipped: JSON.parse creates it as an own key, so a KV
+ *   value could carry one, and assigning it would replace the result's prototype.
+ *   `constructor` and `prototype` are ordinary keys: assigning them on the fresh result
+ *   object creates own properties and reaches no prototype.
  */
 export function deepMerge(base, overrides) {
     const result = { ...base };
     for (const key of Object.keys(overrides)) {
-        if (UNSAFE_KEYS.has(key))
+        if (key === '__proto__')
             continue;
         const overrideValue = overrides[key];
-        const baseValue = base[key];
+        // Own keys only: `base.constructor` would otherwise be the inherited `Object`.
+        const baseValue = Object.hasOwn(base, key) ? base[key] : undefined;
         if (overrideValue === undefined)
             continue;
         // For primitives or different types — override directly

package/dist/fetcher.js

@@ -1,14 +1,31 @@
 import { assembleNamespace } from "./assemble.js";
 import { fallbackIdentifier } from "./key-format.js";
 const KV_JSON_OPTIONS = { type: 'json' };
+// The most keys one KV bulk read accepts.
+const KV_BATCH_LIMIT = 100;
+// A value read from KV: a year, until `migrate` purges it. A key KV does not have (a locale
+// without that namespace): a `null` marker for a minute, so a later `seed` shows without a purge.
+const CACHE_CONTROL_VALUE = 'public, s-maxage=31536000, immutable';
+const CACHE_CONTROL_MISSING = 'public, s-maxage=60';
+// The fetcher's mark on its own entries. The cache URL sits on a hostname of the site's zone,
+// so a response something else left at that URL is a miss, never read as translations.
+// The value is the entry format, as in the URL (`i18n:v2:…`).
+const ENTRY_MARKER = 'X-EdgeKits-I18n';
+const ENTRY_FORMAT = 'v2';
 export function createFetchTranslations({ fallbacks: FALLBACKS, bindings, buildTranslationKvKey, buildTranslationCacheRequest, }) {
     /**
      * Fetch translations from KV for a given locale and list of namespaces.
      *
-     * Cache strategy — per-namespace static cache keys:
+     * Cache strategy — per-namespace cache keys, versioned by entry format:
      *
-     * Each namespace is cached individually under a static (non-versioned) URL:
-     *   https://<keyPrefix>/<encodeURIComponent(i18n:<locale>:<ns>)>
+     * Each namespace is cached individually under
+     *   https://<keyPrefix>/<encodeURIComponent(i18n:v2:<locale>:<ns>)>
+     *
+     * An entry holds what KV holds: the raw value of the namespace's key, or a `null`
+     * marker when KV has none (cached for 60 s). Never the merged namespace: the
+     * compiled fallback is merged on every read, so a fallback change reaches every
+     * locale on the next deploy (ADR-0033). Each entry carries `X-EdgeKits-I18n: v2`; a
+     * response at the URL without it is a miss, read again from KV and replaced.
      *
      * Cache invalidation is handled explicitly by the Cloudflare Purge API
      * in `edgekits-i18n migrate` — only namespaces whose content actually changed
@@ -19,19 +36,19 @@ export function createFetchTranslations({ fallbacks: FALLBACKS, bindings, buildT
      *   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.
+     *   Missing namespaces collected → KV bulk reads of at most 100 keys, in
+     *   parallel → merge with FALLBACK_* → individual cache.put() of the raw value
+     *   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`
+     * miss: a newer fallback key shows as default-locale text instead of `undefined`
      * (ADR-0014).
      *
-     * KV unavailable:
-     *   Falls back to FALLBACK_* compiled dictionaries (always available), and caches
-     *   nothing: only values read from KV are written to the cache.
-     *   If none were generated, returns empty objects per namespace — no crash.
+     * KV unavailable (per bulk read):
+     *   That read's namespaces fall back to FALLBACK_* compiled dictionaries (always
+     *   available), and none of them is cached: only values read from KV are written
+     *   to the cache. If none were generated, returns empty objects — no crash.
      */
     async function fetchTranslations(locale, namespaces) {
         const useCache = bindings.cacheEnabled;
@@ -56,9 +73,11 @@ export function createFetchTranslations({ fallbacks: FALLBACKS, bindings, buildT
             const cacheRequest = buildTranslationCacheRequest(locale, ns);
             try {
                 const cached = await cache.match(cacheRequest);
-                if (cached) {
+                if (cached?.headers.get(ENTRY_MARKER) === ENTRY_FORMAT) {
                     return { ns, data: await cached.json(), hit: true };
                 }
+                if (cached)
+                    debug(`i18n cache entry for ${ns} lacks ${ENTRY_MARKER}: treated as a miss`);
             }
             catch (error) {
                 debug(`i18n cache READ error for ${ns}`, error);
@@ -72,9 +91,8 @@ export function createFetchTranslations({ fallbacks: FALLBACKS, bindings, buildT
         const missingNamespaces = [];
         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).
+                // The raw KV value (or a null marker: the fallback alone), merged with the
+                // current FALLBACK_* like a miss (ADR-0014, ADR-0033).
                 ;
                 finalData[ns] = assembleNamespace(data, getFallback(ns));
             }
@@ -93,19 +111,10 @@ export function createFetchTranslations({ fallbacks: FALLBACKS, bindings, buildT
             miss: missingNamespaces.length,
         });
         // ---------------------------------------------------------------------------
-        // 3. Batch KV read for missing namespaces only
+        // 3. Batched KV reads for missing namespaces only
         // ---------------------------------------------------------------------------
         const missingKvKeys = missingNamespaces.map((ns) => buildTranslationKvKey(locale, ns));
-        let kvResults = new Map();
-        let kvFailed = false;
-        try {
-            kvResults = (await bindings.kv.get(missingKvKeys, KV_JSON_OPTIONS));
-            debug('i18n KV batch OK', { locale, missingNamespaces });
-        }
-        catch (error) {
-            kvFailed = true;
-            debug('i18n KV ERROR, using FALLBACK_* for missing namespaces', error);
-        }
+        const { values: kvResults, failed: failedKvKeys } = await readKv(missingKvKeys);
         // ---------------------------------------------------------------------------
         // 4. Assemble missing namespaces + schedule individual cache writes
         // ---------------------------------------------------------------------------
@@ -113,32 +122,32 @@ export function createFetchTranslations({ fallbacks: FALLBACKS, bindings, buildT
         for (let i = 0; i < missingNamespaces.length; i++) {
             const ns = missingNamespaces[i];
             const kvKey = missingKvKeys[i];
-            // Use KV value if available, otherwise empty object (fallback will fill it)
-            const kvValue = kvFailed ? {} : (kvResults.get(kvKey) ?? {});
+            const kvFailed = failedKvKeys.has(kvKey);
+            // The KV value, or null when KV has none or its read failed (the fallback fills it)
+            const kvValue = kvFailed ? null : (kvResults.get(kvKey) ?? null);
             // 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[ns] = nsData;
-            // Only a value that came from KV is cached. After a KV failure nsData is the
-            // compiled fallback alone (the default locale's text, whatever `locale` asked for),
-            // and an immutable year-long entry would serve it until the next purge.
+            finalData[ns] = assembleNamespace(kvValue, fallback);
+            // Only what KV answered is cached. After a KV failure there is no answer: a null
+            // marker would hide the namespace's real value for a minute.
             if (kvFailed)
                 continue;
-            // Cache the resolved namespace individually with a long TTL.
-            // Invalidation is handled explicitly via Cloudflare Purge API —
-            // no TTL-based expiry needed here.
+            // Cache the raw KV value, never the merged namespace: the fallback is merged on
+            // every read. A value lives until the Purge API removes it, a missing key's null
+            // marker for a minute.
             const cacheRequest = buildTranslationCacheRequest(locale, ns);
-            const response = new Response(JSON.stringify(nsData), {
+            const response = new Response(JSON.stringify(kvValue), {
                 headers: {
                     'Content-Type': 'application/json; charset=utf-8',
-                    'Cache-Control': 'public, s-maxage=31536000, immutable',
+                    'Cache-Control': kvValue === null ? CACHE_CONTROL_MISSING : CACHE_CONTROL_VALUE,
+                    [ENTRY_MARKER]: ENTRY_FORMAT,
                 },
             });
-            putPromises.push(cache.put(cacheRequest, response.clone()).catch((error) => {
+            putPromises.push(cache.put(cacheRequest, response).catch((error) => {
                 const errorMsg = error instanceof Error ? error.message : String(error);
                 debug(`i18n cache WRITE error for ${ns}`, errorMsg);
             }));
@@ -153,8 +162,8 @@ export function createFetchTranslations({ fallbacks: FALLBACKS, bindings, buildT
             bindings.waitUntil(Promise.all(putPromises));
             debug('i18n cache PUT scheduled', { locale, missingNamespaces });
         }
-        else if (kvFailed) {
-            debug('i18n cache PUT skipped: KV failed, the fallbacks are not cached', { locale, missingNamespaces });
+        if (failedKvKeys.size > 0) {
+            debug('i18n cache PUT skipped where KV failed: the fallbacks are not cached', { locale, failedKvKeys });
         }
         return finalData;
     }
@@ -167,43 +176,48 @@ export function createFetchTranslations({ fallbacks: FALLBACKS, bindings, buildT
      */
     async function fetchAllFromKV(locale, namespaces) {
         const keys = namespaces.map((ns) => buildTranslationKvKey(locale, ns));
-        let kvResults = new Map();
-        let kvFailed = false;
-        try {
-            kvResults = (await bindings.kv.get(keys, KV_JSON_OPTIONS));
-        }
-        catch (error) {
-            kvFailed = true;
-            debug('i18n KV ERROR (cache bypassed), using FALLBACK_* for all namespaces', error);
-        }
-        if (kvFailed) {
-            return buildFallbackOnly(namespaces);
-        }
+        const { values: kvResults, failed: failedKvKeys } = await readKv(keys);
         const data = {};
         for (let i = 0; i < namespaces.length; i++) {
             const ns = namespaces[i];
-            const kvValue = kvResults.get(keys[i]);
+            const key = keys[i];
+            // A namespace whose read failed gets its compiled fallback alone (a copy, as every
+            // assembled namespace is).
+            const kvValue = failedKvKeys.has(key) ? null : (kvResults.get(key) ?? null);
             data[ns] = assembleNamespace(kvValue, getFallback(ns));
         }
         return data;
     }
     /**
-     * Look up the compiled FALLBACK_* dictionary for a namespace, if one was generated.
+     * Read `keys` from KV in bulk reads of at most KV_BATCH_LIMIT keys, in parallel. A read
+     * that throws marks its own keys failed; the other reads' values still arrive.
      */
-    function getFallback(ns) {
-        return FALLBACKS[fallbackIdentifier(String(ns))];
+    async function readKv(keys) {
+        const batches = [];
+        for (let i = 0; i < keys.length; i += KV_BATCH_LIMIT) {
+            batches.push(keys.slice(i, i + KV_BATCH_LIMIT));
+        }
+        const values = new Map();
+        const failed = new Set();
+        await Promise.all(batches.map(async (batch) => {
+            try {
+                for (const [key, value] of await bindings.kv.get(batch, KV_JSON_OPTIONS))
+                    values.set(key, value);
+                debug('i18n KV batch OK', { keys: batch.length });
+            }
+            catch (error) {
+                for (const key of batch)
+                    failed.add(key);
+                debug('i18n KV ERROR, using FALLBACK_* for this batch', error);
+            }
+        }));
+        return { values, failed };
     }
     /**
-     * Build a payload using only FALLBACK_* compiled dictionaries.
-     * Used when KV is completely unavailable.
+     * Look up the compiled FALLBACK_* dictionary for a namespace, if one was generated.
      */
-    function buildFallbackOnly(namespaces) {
-        const data = {};
-        for (const ns of namespaces) {
-            ;
-            data[ns] = getFallback(ns) ?? {};
-        }
-        return data;
+    function getFallback(ns) {
+        return FALLBACKS[fallbackIdentifier(String(ns))];
     }
     // ---------------------------------------------------------------------------
     // Runtime helpers

package/dist/format.d.ts

@@ -9,6 +9,7 @@ export declare function fmt(template: string | null | undefined, values?: Templa
 /**
  * Simple two-form plural helper.
  * Good for English-like languages where "1" vs "other" is enough.
+ * Both forms interpolate `{count}`.
  */
 export declare function plural(count: number, singular: string, plural: string): string;
 /**
@@ -37,11 +38,20 @@ export type LocalizedPathOptions = {
     isLocale: (segment: string) => boolean;
 };
 /**
- * The path of a page in `locale`, for either routing mode, always with a trailing slash.
- * A leading locale segment is stripped first, so a prefixed `/de/about/`, a rewritten
- * `/en/about/` and a bare `/about/` all name the same page. 'prefix': `/<locale>/<rest>/`.
- * 'prefix-except-default': the same, except `/<rest>/` (`/` for the root) for the default
- * locale.
+ * True when the path's last segment ends in a file extension (`/rss.xml`, `/doc.pdf`).
+ * A path that ends in a slash is a page (`/rss.xml/` included).
+ */
+export declare function isFilePath(pathname: string): boolean;
+/**
+ * The path of a page in `locale`, for either routing mode: with a trailing slash, or
+ * without one for a file path (`isFilePath`). A leading locale segment is stripped first,
+ * so a prefixed `/de/about/`, a rewritten `/en/about/` and a bare `/about/` all name the
+ * same page. 'prefix': `/<locale>/<rest>/`. 'prefix-except-default': the same, except
+ * `/<rest>/` (`/` for the root) for the default locale. A `?query` and a `#hash` in the
+ * input are kept after the path. The path is rebuilt from its non-empty segments, read as
+ * the WHATWG parser reads an https path: `\` separates segments like `/`, and a tab or
+ * newline is dropped. So no result starts with `//` or `/\`, even for a decoded path
+ * (Astro's `originPathname` turns `%5C` into `\`); an encoded `%5C` stays one segment.
  */
 export declare function localizedPath(locale: string, pathname: string, options: LocalizedPathOptions): string;
 export declare function replaceLocaleInPath(currentPath: string, currentLocale: string, newLocale: string): string;

package/dist/format.js

@@ -38,9 +38,10 @@ export function fmt(template, values) {
 /**
  * Simple two-form plural helper.
  * Good for English-like languages where "1" vs "other" is enough.
+ * Both forms interpolate `{count}`.
  */
 export function plural(count, singular, plural) {
-    return count === 1 ? singular : fmt(plural, { count });
+    return fmt(count === 1 ? singular : plural, { count });
 }
 /**
  * Advanced plural helper using Intl.PluralRules + fmt().
@@ -64,20 +65,38 @@ export function pluralIcu(count, locale, patterns) {
         (isProd() ? '' : (console.warn('[i18n] pluralIcu(): missing "other" pattern'), ''));
     return fmt(template, { count });
 }
+// An extension that starts with a letter, up to 11 characters (`.webmanifest`, the
+// longest common one): `.xml`, `.md`; not `.0` (`/blog/v2.0` is a page).
+const FILE_EXTENSION = /\.[a-z][a-z0-9]{0,10}$/i;
 /**
- * The path of a page in `locale`, for either routing mode, always with a trailing slash.
- * A leading locale segment is stripped first, so a prefixed `/de/about/`, a rewritten
- * `/en/about/` and a bare `/about/` all name the same page. 'prefix': `/<locale>/<rest>/`.
- * 'prefix-except-default': the same, except `/<rest>/` (`/` for the root) for the default
- * locale.
+ * True when the path's last segment ends in a file extension (`/rss.xml`, `/doc.pdf`).
+ * A path that ends in a slash is a page (`/rss.xml/` included).
+ */
+export function isFilePath(pathname) {
+    const last = pathname.slice(pathname.lastIndexOf('/') + 1);
+    return FILE_EXTENSION.test(last);
+}
+/**
+ * The path of a page in `locale`, for either routing mode: with a trailing slash, or
+ * without one for a file path (`isFilePath`). A leading locale segment is stripped first,
+ * so a prefixed `/de/about/`, a rewritten `/en/about/` and a bare `/about/` all name the
+ * same page. 'prefix': `/<locale>/<rest>/`. 'prefix-except-default': the same, except
+ * `/<rest>/` (`/` for the root) for the default locale. A `?query` and a `#hash` in the
+ * input are kept after the path. The path is rebuilt from its non-empty segments, read as
+ * the WHATWG parser reads an https path: `\` separates segments like `/`, and a tab or
+ * newline is dropped. So no result starts with `//` or `/\`, even for a decoded path
+ * (Astro's `originPathname` turns `%5C` into `\`); an encoded `%5C` stays one segment.
  */
 export function localizedPath(locale, pathname, options) {
-    const segments = pathname.split('/').filter(Boolean);
+    const suffixAt = pathname.search(/[?#]/);
+    const path = (suffixAt === -1 ? pathname : pathname.slice(0, suffixAt)).replace(/[\t\n\r]/g, '');
+    const suffix = suffixAt === -1 ? '' : pathname.slice(suffixAt);
+    const segments = path.split(/[/\\]/).filter(Boolean);
     if (segments.length > 0 && options.isLocale(segments[0]))
         segments.shift();
-    const rest = segments.length > 0 ? `${segments.join('/')}/` : '';
+    const rest = segments.length > 0 ? `${segments.join('/')}${isFilePath(path) ? '' : '/'}` : '';
     const unprefixed = options.routing !== 'prefix' && locale === options.defaultLocale;
-    return unprefixed ? `/${rest}` : `/${locale}/${rest}`;
+    return (unprefixed ? `/${rest}` : `/${locale}/${rest}`) + suffix;
 }
 // Used in the LanguageSwitcher and SeoHreflangs components. Prefix-only by construction:
 // a path without a locale prefix (the default locale in 'prefix-except-default') comes
@@ -95,9 +114,18 @@ export function getLangFromUrl(pathname) {
     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'
+// Used for the HTML lang attribute and hreflang values. After the language, each subtag
+// is cased by its length: 2 letters (a region) upper, 4 letters (a script) title case,
+// anything else (`419`) as is.
+// 'pt-br' → 'pt-BR', 'zh-hant-tw' → 'zh-Hant-TW', 'en' → 'en'
 export function toIetfTag(locale) {
-    const [lang, region] = locale.split('-');
-    return region ? `${lang}-${region.toUpperCase()}` : locale;
+    const [lang = '', ...subtags] = locale.split('-');
+    const cased = subtags.map((subtag) => {
+        if (/^[a-z]{2}$/i.test(subtag))
+            return subtag.toUpperCase();
+        if (/^[a-z]{4}$/i.test(subtag))
+            return subtag[0].toUpperCase() + subtag.slice(1).toLowerCase();
+        return subtag;
+    });
+    return [lang, ...cased].join('-');
 }

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { createI18n, type GeneratedModules, type I18nInstance, type InstanceLoca
 export { localesOf, type LocalesOf } from './config.ts';
 export { DEFAULT_GENERATED_DIR, DEFAULT_LOCALES_DIR, defineI18nConfig, type I18nBindings, type I18nConfig, type I18nLanguage, type I18nLocales, type I18nRouting, type Locale, type LocaleOf, type Namespace, type PickSchema, } from './types.ts';
 export type { Bindings, EdgeCache, FetcherInputs, TranslationsKv } from './fetcher.ts';
-export { fmt, getLangFromUrl, localizedPath, plural, pluralIcu, replaceLocaleInPath, toIetfTag, type LocalizedPathOptions, type PluralCategory, type PluralPatterns, } from './format.ts';
+export { fmt, getLangFromUrl, isFilePath, localizedPath, plural, pluralIcu, replaceLocaleInPath, toIetfTag, type LocalizedPathOptions, type PluralCategory, type PluralPatterns, } from './format.ts';
 export { matchAcceptLanguage, parseAcceptLanguage, type AcceptLanguageEntry } from './accept-language.ts';
 export { mapCountryToLocale, resolveFallbackLocale, type FallbackInputs, type FallbackOptions, } from './locale-fallback.ts';
 export { MARKDOWN_PATH, markdownRedirectTarget, type MarkdownOptions } from './markdown-path.ts';

package/dist/index.js

@@ -3,7 +3,7 @@
 export { createI18n, } from "./create-i18n.js";
 export { localesOf } from "./config.js";
 export { DEFAULT_GENERATED_DIR, DEFAULT_LOCALES_DIR, defineI18nConfig, } from "./types.js";
-export { fmt, getLangFromUrl, localizedPath, plural, pluralIcu, replaceLocaleInPath, toIetfTag, } from "./format.js";
+export { fmt, getLangFromUrl, isFilePath, localizedPath, plural, pluralIcu, replaceLocaleInPath, toIetfTag, } from "./format.js";
 export { matchAcceptLanguage, parseAcceptLanguage } from "./accept-language.js";
 export { mapCountryToLocale, resolveFallbackLocale, } from "./locale-fallback.js";
 export { MARKDOWN_PATH, markdownRedirectTarget } from "./markdown-path.js";

package/dist/key-format.js

@@ -8,9 +8,12 @@
 export function formatTranslationKvKey(keyPrefix, locale, ns) {
     return `${keyPrefix}:${ns}:${locale}`;
 }
-// Format: https://<keyPrefix>/<encodeURIComponent(i18n:<locale>:<namespace>)>
+// The cache entry format: `v2` entries hold the raw KV value (ADR-0033). 0.2.x wrote merged
+// namespaces under the unversioned `i18n:<locale>:<namespace>`, which is never read again.
+const CACHE_FORMAT = 'v2';
+// Format: https://<keyPrefix>/<encodeURIComponent(i18n:v2:<locale>:<namespace>)>
 export function formatTranslationCacheUrl(keyPrefix, locale, ns) {
-    const cacheId = `i18n:${locale}:${ns}`;
+    const cacheId = `i18n:${CACHE_FORMAT}:${locale}:${ns}`;
     return `https://${keyPrefix}/${encodeURIComponent(cacheId)}`;
 }
 // Format: FALLBACK_<NAMESPACE>, upper-cased, every `.` as `__` (`app.billing` ->

package/dist/types.d.ts

@@ -28,7 +28,8 @@ 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
+ * Validates and returns the config unchanged. Throws at config time on a `keyPrefix` that
+ * is not a URL host as written, an empty
  * `languages`, a `defaultLocale` or `markdownLocale` that is not one of its keys, a
  * `routing` other than the two modes (absent is valid), 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).

package/dist/types.js

@@ -7,8 +7,21 @@ const ROUTINGS = ['prefix', 'prefix-except-default'];
 export const DEFAULT_GENERATED_DIR = 'src/i18n';
 export const DEFAULT_LOCALES_DIR = 'locales';
 const COUNTRY_CODE = /^[A-Z]{2}$/;
+// True when `https://<value>` parses with exactly `value` as its host: no scheme, path,
+// port syntax error, space or upper case (the URL parser would change any of them).
+function isOwnUrlHost(value) {
+    if (typeof value !== 'string' || value === '')
+        return false;
+    try {
+        return new URL(`https://${value}`).host === value;
+    }
+    catch {
+        return false;
+    }
+}
 /**
- * Validates and returns the config unchanged. Throws at config time on an empty
+ * Validates and returns the config unchanged. Throws at config time on a `keyPrefix` that
+ * is not a URL host as written, an empty
  * `languages`, a `defaultLocale` or `markdownLocale` that is not one of its keys, a
  * `routing` other than the two modes (absent is valid), 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).
@@ -24,6 +37,11 @@ export function defineI18nConfig(config) {
             throw new Error(`[@edgekits/i18n-core] \`languages\` key "${locale}" is not lowercase (use "${locale.toLowerCase()}").`);
         }
     }
+    if (!isOwnUrlHost(config.keyPrefix)) {
+        throw new Error(`[@edgekits/i18n-core] \`keyPrefix\` ${JSON.stringify(config.keyPrefix)} is not a URL host as written: ` +
+            'it is the host of every edge-cache URL (https://<keyPrefix>/…). Use lowercase letters, digits, dots ' +
+            'and hyphens, with no scheme or path ("example.com", "my-site").');
+    }
     if (!locales.includes(config.defaultLocale)) {
         throw new Error(`[@edgekits/i18n-core] \`defaultLocale\` "${config.defaultLocale}" is not one of \`languages\`: ${locales.join(', ')}.`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgekits/i18n-core",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "The EdgeKits edge-native i18n engine, free of any framework: translations in Workers KV, a per-namespace edge cache invalidated by the Purge API, typed keys, and the edgekits-i18n CLI.",
   "keywords": [
     "i18n",
@@ -22,7 +22,7 @@
     "url": "https://github.com/EdgeKits/i18n/issues"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=22.23.4"
   },
   "exports": {
     ".": {