@edgekits/astro-i18n 0.0.0-stage → 0.1.1

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)
+}

package/src/cli/generate.ts

@@ -0,0 +1,175 @@
+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 generateSchemaTs(schema: TranslationTree, indent = 4): string {
+  const pad = ' '.repeat(indent)
+  const padInner = ' '.repeat(indent + 2)
+
+  if (schema && typeof schema === 'object' && !Array.isArray(schema)) {
+    const entries = Object.entries(schema)
+    if (entries.length === 0) return '{}'
+
+    const lines = entries.map(([key, value]) => {
+      const valueTs =
+        value && typeof value === 'object' && !Array.isArray(value)
+          ? generateSchemaTs(value as TranslationTree, indent + 2)
+          : 'string'
+      return `${padInner}${JSON.stringify(key)}: ${valueTs}`
+    })
+
+    return `{\n${lines.join(';\n')};\n${pad}}`
+  }
+
+  return 'string'
+}
+
+/** `src/i18n.generated.d.ts`: the global `I18n.Schema`, from the schema source locale. */
+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 as TranslationTree, 10)
+    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

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