@edgekits/astro-i18n 0.1.8 → 0.2.0

package/dist/cli/zone.d.ts

@@ -1,21 +0,0 @@
-export type ZoneDeps = {
-    fetch?: (input: string, init: RequestInit) => Promise<Response>;
-};
-/**
- * Read the zone's name: `GET /zones/{zoneId}`, `result.name`. Needs Zone › Zone › Read
- * on the token. Never throws: any failure (non-2xx, network error, unexpected body)
- * comes back as `{ error }`.
- *
- * `deps` replaces `fetch` in tests.
- */
-export declare function readZoneName(zoneId: string, apiToken: string, deps?: ZoneDeps): Promise<{
-    name: string;
-} | {
-    error: string;
-}>;
-/**
- * Print the keyPrefix warning when `keyPrefix` lies outside the zone, or one info line
- * when the zone name cannot be read. Advisory only: it returns nothing, and the purge
- * runs the same either way.
- */
-export declare function checkKeyPrefixZone(keyPrefix: string, zoneId: string, apiToken: string, deps?: ZoneDeps): Promise<void>;

package/dist/cli/zone.js

@@ -1,42 +0,0 @@
-import { keyPrefixZoneWarning } from "./key-prefix-check.js";
-/**
- * Read the zone's name: `GET /zones/{zoneId}`, `result.name`. Needs Zone › Zone › Read
- * on the token. Never throws: any failure (non-2xx, network error, unexpected body)
- * comes back as `{ error }`.
- *
- * `deps` replaces `fetch` in tests.
- */
-export async function readZoneName(zoneId, apiToken, deps = {}) {
-    const { fetch: fetchFn = fetch } = deps;
-    try {
-        const response = await fetchFn(`https://api.cloudflare.com/client/v4/zones/${zoneId}`, {
-            method: 'GET',
-            headers: { Authorization: `Bearer ${apiToken}` },
-        });
-        if (!response.ok)
-            return { error: `HTTP ${response.status}` };
-        const body = (await response.json());
-        const name = body?.result?.name;
-        if (typeof name !== 'string' || name.trim() === '')
-            return { error: 'no result.name in the response' };
-        return { name };
-    }
-    catch (err) {
-        return { error: err instanceof Error ? err.message : String(err) };
-    }
-}
-/**
- * Print the keyPrefix warning when `keyPrefix` lies outside the zone, or one info line
- * when the zone name cannot be read. Advisory only: it returns nothing, and the purge
- * runs the same either way.
- */
-export async function checkKeyPrefixZone(keyPrefix, zoneId, apiToken, deps = {}) {
-    const zone = await readZoneName(zoneId, apiToken, deps);
-    if ('error' in zone) {
-        console.log(`[i18n] ℹ️  Could not read the zone name (${zone.error}), so the keyPrefix check was skipped (needs Zone › Zone › Read on the token).`);
-        return;
-    }
-    const warning = keyPrefixZoneWarning(keyPrefix, zone.name);
-    if (warning)
-        console.warn(warning);
-}

package/dist/key-format.d.ts

@@ -1,8 +0,0 @@
-/**
- * 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

@@ -1,15 +0,0 @@
-/**
- * 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/src/accept-language.ts

@@ -1,56 +0,0 @@
-/**
- * The Accept-Language step of the middleware's fallback cascade, read from the header
- * itself. Astro's own match is no substitute: it keeps only the tags that equal a
- * configured locale before choosing, so a regional tag (`es-MX`) never reaches a
- * language-part match. Pure: no Astro, no virtual module, no `cloudflare:`.
- */
-
-export type AcceptLanguageEntry = { tag: string; q: number }
-
-/**
- * The header's language ranges, highest `q` first (header order among equals). A missing
- * or unparsable `q` is 1; `q=0` entries and the `*` wildcard are dropped.
- */
-export function parseAcceptLanguage(header: string | null): AcceptLanguageEntry[] {
-  if (!header) return []
-
-  const entries: AcceptLanguageEntry[] = []
-  for (const part of header.split(',')) {
-    const [rawTag = '', ...params] = part.split(';')
-    const tag = rawTag.trim()
-    if (!tag || tag === '*') continue
-
-    let q = 1
-    for (const param of params) {
-      const [name, value] = param.split('=').map((s) => s.trim())
-      if (name?.toLowerCase() !== 'q' || value === undefined) continue
-      const parsed = Number.parseFloat(value)
-      if (!Number.isNaN(parsed)) q = parsed
-    }
-    if (q <= 0) continue
-
-    entries.push({ tag, q })
-  }
-
-  // Array.prototype.sort is stable: equal q keeps header order.
-  return entries.sort((a, b) => b.q - a.q)
-}
-
-/**
- * The first supported locale the header names: for each tag in `q` order, the full tag
- * (lowercased), then its language subtag (before the first `-` or `_`). Null when none.
- */
-export function matchAcceptLanguage<L extends string>(
-  header: string | null,
-  parseLocale: (value: unknown) => L | null,
-): L | null {
-  for (const { tag } of parseAcceptLanguage(header)) {
-    const lower = tag.toLowerCase()
-    const full = parseLocale(lower)
-    if (full) return full
-
-    const language = parseLocale(lower.split(/[-_]/)[0])
-    if (language) return language
-  }
-  return null
-}

package/src/assemble.ts

@@ -1,29 +0,0 @@
-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)
-}

package/src/cli/generate.ts

@@ -1,205 +0,0 @@
-import { formatTranslationKvKey } from '../key-format.ts'
-
-/**
- * The CLI's code generation, as pure functions of the collected locale tree: no
- * filesystem, so the emitted text is testable. Formats are those of the site's
- * `scripts/bundle-translations.ts`, header aside.
- */
-
-export type TranslationTree = Record<string, unknown>
-
-// <locale> → <namespace> → the namespace's JSON
-export type CollectedData = Record<string, Record<string, TranslationTree>>
-
-export type KvBulkEntry = { key: string; value: string }
-
-const HEADER = `// Auto-generated by @edgekits/astro-i18n (edgekits-i18n CLI)
-// Do not edit manually.
-`
-
-// A namespace becomes part of a KV key, a cache URL and the `FALLBACK_<NAMESPACE>`
-// identifier, so its file name is restricted to what is valid in all three.
-export const NAMESPACE_NAME = /^[a-z0-9][a-z0-9_]*$/
-
-/**
- * Throws, naming the offender, when a locale folder is not one of the config's
- * `languages` or a namespace file name does not match NAMESPACE_NAME. Run on the
- * collected tree before anything is generated or pushed.
- */
-export function assertValidNames(collected: CollectedData, languages: Readonly<Record<string, unknown>>): void {
-  const configured = Object.keys(languages)
-
-  for (const [locale, namespaces] of Object.entries(collected)) {
-    if (!configured.includes(locale)) {
-      throw new Error(
-        `Locale folder "${locale}" is not one of \`languages\` in edgekits-i18n.config.ts: ${configured.join(', ')}.`,
-      )
-    }
-    for (const ns of Object.keys(namespaces)) {
-      if (!NAMESPACE_NAME.test(ns)) {
-        throw new Error(
-          `Namespace "${ns}" (${locale}/${ns}.json) must match ${NAMESPACE_NAME}: lowercase letters, digits and underscores.`,
-        )
-      }
-    }
-  }
-}
-
-/**
- * A single-quoted TS string literal, escaped by JSON.stringify. For every name the
- * validation accepts it is byte-identical to the plain `'name'` the CLI always wrote, so
- * existing generated files do not change; anything else comes out escaped, not injected.
- */
-export function quoteString(value: string): string {
-  const escaped = JSON.stringify(value).slice(1, -1).replace(/\\"/g, '"').replace(/'/g, "\\'")
-  return `'${escaped}'`
-}
-
-/** Locales that have at least one namespace, sorted. */
-export function localesWithTranslations(collected: CollectedData): string[] {
-  return Object.keys(collected).sort()
-}
-
-/**
- * The locale the schema and the namespace list are derived from: the default locale
- * when it has translations, otherwise the first locale that does.
- */
-export function schemaSourceLocale(collected: CollectedData, defaultLocale: string): string | undefined {
-  if (collected[defaultLocale]) return defaultLocale
-  return localesWithTranslations(collected)[0]
-}
-
-/** `wrangler kv bulk put` input: one entry per locale and namespace. */
-export function buildBulkData(collected: CollectedData, keyPrefix: string): KvBulkEntry[] {
-  const bulkData: KvBulkEntry[] = []
-
-  for (const [locale, namespaces] of Object.entries(collected)) {
-    for (const [ns, json] of Object.entries(namespaces)) {
-      bulkData.push({ key: formatTranslationKvKey(keyPrefix, locale, ns), value: JSON.stringify(json) })
-    }
-  }
-
-  return bulkData
-}
-
-function isTree(value: unknown): value is TranslationTree {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
-
-// The JSON kind of an array element; an array is typed only when all its elements share one.
-function jsonKind(value: unknown): string {
-  if (value === null) return 'null'
-  if (Array.isArray(value)) return 'array'
-  return typeof value
-}
-
-/**
- * The TS type of one JSON value. Objects become object types; arrays become `string[]`
- * (strings, other scalars, or empty) or `Array<…>` typed from their first element
- * (objects, nested arrays); every other leaf stays `string`. `keyPath` and `file` name the
- * value in the error a mixed array raises.
- */
-function generateSchemaTs(value: unknown, indent: number, keyPath: string, file: string): string {
-  if (Array.isArray(value)) {
-    if (value.length === 0) return 'string[]'
-
-    const kinds = [...new Set(value.map(jsonKind))]
-    if (kinds.length > 1) {
-      throw new Error(
-        `Key "${keyPath}" (${file}) is an array that mixes ${kinds.join(', ')} elements: ` +
-          'I18n.Schema cannot type it. Use one kind of element per array.',
-      )
-    }
-
-    const first = value[0]
-    if (!isTree(first) && !Array.isArray(first)) return 'string[]'
-    return `Array<${generateSchemaTs(first, indent, `${keyPath}[0]`, file)}>`
-  }
-
-  if (!isTree(value)) return 'string'
-
-  const entries = Object.entries(value)
-  if (entries.length === 0) return '{}'
-
-  const pad = ' '.repeat(indent)
-  const padInner = ' '.repeat(indent + 2)
-  const lines = entries.map(
-    ([key, child]) =>
-      `${padInner}${JSON.stringify(key)}: ${generateSchemaTs(child, indent + 2, `${keyPath}.${key}`, file)}`,
-  )
-
-  return `{\n${lines.join(';\n')};\n${pad}}`
-}
-
-/**
- * `src/i18n.generated.d.ts`: the global `I18n.Schema`, from the schema source locale.
- * Throws, naming the key, when an array in it mixes kinds of elements.
- */
-export function buildTypesContent(collected: CollectedData, defaultLocale: string): string {
-  const source = schemaSourceLocale(collected, defaultLocale)
-  const schemaObject: TranslationTree = (source && collected[source]) || {}
-
-  const namespaceLines = Object.entries(schemaObject).map(([ns, value]) => {
-    const valueTs = generateSchemaTs(value, 10, ns, `${source}/${ns}.json`)
-    return `      ${JSON.stringify(ns)}: ${valueTs}`
-  })
-
-  const interfaceBody =
-    namespaceLines.length > 0
-      ? `    export interface Schema {\n${namespaceLines.join(';\n')};\n    }`
-      : `    export interface Schema {}`
-
-  return `${HEADER}
-declare global {
-  namespace I18n {
-${interfaceBody}
-  }
-}
-
-export {}
-`
-}
-
-/**
- * `runtime-constants.ts`:
- *   - NAMESPACE_KEYS            -> from the schema source locale (default locale preferred)
- *   - LOCALES_WITH_TRANSLATIONS -> from all collected locales
- *   - FULLY_TRANSLATED_LOCALES  -> locales that have ALL namespace keys
- */
-export function buildRuntimeConstantsContent(collected: CollectedData, defaultLocale: string): string {
-  const source = schemaSourceLocale(collected, defaultLocale)
-  const namespaceKeys = Object.keys((source && collected[source]) || {}).sort()
-  const locales = localesWithTranslations(collected)
-
-  const fullyTranslatedLocales = locales.filter((locale) => {
-    const localeNamespaces = Object.keys(collected[locale] || {})
-    return namespaceKeys.every((ns) => localeNamespaces.includes(ns))
-  })
-
-  return `${HEADER}
-export const NAMESPACE_KEYS = [${namespaceKeys.map(quoteString).join(', ')}] as [string, ...string[]];
-
-export const LOCALES_WITH_TRANSLATIONS = [${locales.map(quoteString).join(', ')}] as const;
-
-export const FULLY_TRANSLATED_LOCALES = [${fullyTranslatedLocales.map(quoteString).join(', ')}] as const;
-`
-}
-
-/**
- * `fallbacks.generated.ts`: one `FALLBACK_<NAMESPACE>` per default-locale namespace.
- * Null when the default locale has no translations (nothing to fall back to).
- */
-export function buildFallbacksContent(collected: CollectedData, defaultLocale: string): string | null {
-  const fallbackNamespaces = collected[defaultLocale]
-  if (!fallbackNamespaces) return null
-
-  const lines: string[] = [HEADER]
-  lines.push(`export const FALLBACK_LOCALE = ${JSON.stringify(defaultLocale)} as const;\n`)
-
-  for (const [ns, json] of Object.entries(fallbackNamespaces)) {
-    const constName = `FALLBACK_${ns.toUpperCase()}`
-    lines.push(`export const ${constName} = ${JSON.stringify(json, null, 2)} as const;\n`)
-  }
-
-  return lines.join('\n')
-}

package/src/cli/hashes.ts

@@ -1,66 +0,0 @@
-import crypto from 'node:crypto'
-
-import { formatTranslationCacheUrl } from '../key-format.ts'
-import type { CollectedData } from './generate.ts'
-
-/**
- * Per-namespace content hashes and the change diff that drives the cache purge.
- * Pure apart from hashing. Same algorithm as the site's `scripts/bundle-translations.ts`,
- * so an existing `.i18n-hashes.json` stays a valid baseline.
- */
-
-// Persisted hash map: "<locale>:<namespace>" → content hash
-export type HashMap = Record<string, string>
-
-export function stableStringify(value: unknown): string {
-  if (value === null || typeof value !== 'object') {
-    return JSON.stringify(value)
-  }
-
-  if (Array.isArray(value)) {
-    return '[' + value.map(stableStringify).join(',') + ']'
-  }
-
-  const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b))
-
-  return '{' + entries.map(([k, v]) => JSON.stringify(k) + ':' + stableStringify(v)).join(',') + '}'
-}
-
-export function computeHash(value: unknown): string {
-  const json = stableStringify(value)
-  return crypto.createHash('sha256').update(json).digest('hex').slice(0, 12)
-}
-
-/**
- * Hash every collected namespace and list the "<locale>:<namespace>" pairs whose hash
- * differs from the previous run (all of them when there is no previous run).
- */
-export function diffHashes(
-  collected: CollectedData,
-  previousHashes: HashMap,
-): { currentHashes: HashMap; changedKeys: string[] } {
-  const currentHashes: HashMap = {}
-  const changedKeys: string[] = []
-
-  for (const [locale, namespaces] of Object.entries(collected)) {
-    for (const [ns, json] of Object.entries(namespaces)) {
-      const hashKey = `${locale}:${ns}`
-      const hash = computeHash(json)
-      currentHashes[hashKey] = hash
-
-      if (previousHashes[hashKey] !== hash) {
-        changedKeys.push(hashKey)
-      }
-    }
-  }
-
-  return { currentHashes, changedKeys }
-}
-
-/** Purge API URLs for the changed "<locale>:<namespace>" pairs. */
-export function purgeUrlsFor(changedKeys: readonly string[], keyPrefix: string): string[] {
-  return changedKeys.map((hashKey) => {
-    const [locale, ns] = hashKey.split(':') as [string, string]
-    return formatTranslationCacheUrl(keyPrefix, locale, ns)
-  })
-}