@edgekits/astro-i18n 0.0.0-stage → 0.1.0

package/src/cli/wrangler.ts

@@ -0,0 +1,96 @@
+import fs from 'node:fs'
+import { createRequire } from 'node:module'
+import path from 'node:path'
+
+import { parse as parseJsonc, printParseErrorCode, type ParseError } 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: string): Record<string, unknown> {
+  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: ParseError[] = []
+  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: string, binding: string): string {
+  const config = readWranglerConfig(root)
+  const kvNamespaces = config.kv_namespaces as
+    | Array<{
+        binding: string
+        id: string
+      }>
+    | undefined
+
+  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: string, key: string): string | undefined {
+  const config = readWranglerConfig(root)
+  const vars = config.vars as Record<string, string> | undefined
+  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: string): string {
+  const requireFromRoot = createRequire(path.join(root, 'package.json'))
+
+  let manifestPath: string
+  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')) as { bin?: string | Record<string, string> }
+  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/src/components/LanguageSwitcher.astro

@@ -0,0 +1,210 @@
+---
+import { I18N_CONFIG } from '../config'
+import { SUPPORTED_LOCALES, LANGUAGES, LANG_COOKIE_NAME } from '../constants'
+import type { Locale } from '../constants'
+
+interface Props {
+  // The project's flag component (an Astro component reference), passed in so the
+  // engine imports no project UI. Without it, items render label-only.
+  flag?: (props: { code: string; size?: number }) => any
+  // The project's icons for the trigger button and the active item (Astro component
+  // references, like `flag`). Without them, the minimal inline defaults below render.
+  triggerIcon?: (props: Record<string, unknown>) => any
+  activeIcon?: (props: Record<string, unknown>) => any
+  // The component is headless: every class comes from here. A slot left out renders no
+  // `class` attribute; `itemActive` is appended to `item` on the active entry.
+  classes?: Partial<
+    Record<'root' | 'trigger' | 'triggerIcon' | 'dropdown' | 'item' | 'itemActive' | 'itemLabel' | 'activeIcon', string>
+  >
+}
+
+const { flag: Flag, triggerIcon: TriggerIcon, activeIcon: ActiveIcon, classes = {} } = Astro.props
+const { uiLocale: currentLang } = Astro.locals
+---
+
+<language-switcher
+  data-current-lang={currentLang}
+  data-cookie-name={LANG_COOKIE_NAME}
+  data-cookie-max-age={I18N_CONFIG.cookie.maxAge}
+  data-open="false"
+>
+  <div class={classes.root}>
+    <button
+      type="button"
+      data-ls-trigger
+      class={classes.trigger}
+      aria-haspopup="true"
+      aria-expanded="false"
+      aria-label="Switch language"
+    >
+      {
+        TriggerIcon ? (
+          <TriggerIcon class={classes.triggerIcon} stroke-width="1" />
+        ) : (
+          <svg
+            class={classes.triggerIcon}
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="1"
+            aria-hidden="true"
+          >
+            <circle cx="12" cy="12" r="9" />
+            <ellipse cx="12" cy="12" rx="4" ry="9" />
+            <path d="M3 12h18" />
+          </svg>
+        )
+      }
+    </button>
+
+    <div data-ls-dropdown class={classes.dropdown} role="menu" hidden>
+      {
+        SUPPORTED_LOCALES.map((lang) => {
+          const locale = lang as Locale
+          const isActive = locale === currentLang
+          const label = LANGUAGES[locale]
+          const flagCode = label.countryCode
+
+          return (
+            <button
+              type="button"
+              class:list={[classes.item, isActive && classes.itemActive]}
+              data-ls-item
+              data-lang={locale}
+              data-active={isActive ? 'true' : undefined}
+              role="menuitem"
+              disabled={isActive}
+            >
+              <span class={classes.itemLabel}>
+                {Flag && <Flag code={flagCode} size={16} />}
+                {label.name}
+              </span>
+              {isActive &&
+                (ActiveIcon ? (
+                  <ActiveIcon class={classes.activeIcon} />
+                ) : (
+                  <svg class={classes.activeIcon} viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+                    <circle cx="12" cy="12" r="3" />
+                  </svg>
+                ))}
+            </button>
+          )
+        })
+      }
+    </div>
+  </div>
+</language-switcher>
+
+<script>
+  // Config arrives as data attributes on the element: a client script in the engine
+  // cannot import the project's config.
+  import type { Locale } from '../constants'
+
+  class LanguageSwitcher extends HTMLElement {
+    private trigger: HTMLButtonElement | null = null
+    private dropdown: HTMLElement | null = null
+
+    connectedCallback() {
+      this.trigger = this.querySelector('[data-ls-trigger]')
+      this.dropdown = this.querySelector('[data-ls-dropdown]')
+
+      if (!this.trigger || !this.dropdown) return
+
+      this.trigger.addEventListener('click', this.onToggle)
+      this.dropdown.addEventListener('click', this.onSelect)
+    }
+
+    disconnectedCallback() {
+      this.trigger?.removeEventListener('click', this.onToggle)
+      this.dropdown?.removeEventListener('click', this.onSelect)
+      this.removeGlobalListeners()
+    }
+
+    private open() {
+      if (!this.dropdown || !this.trigger) return
+      this.dropdown.hidden = false
+      this.dataset.open = 'true'
+      this.trigger.setAttribute('aria-expanded', 'true')
+
+      document.addEventListener('click', this.onDocumentClick)
+      document.addEventListener('keydown', this.onKeyDown)
+    }
+
+    private close() {
+      if (!this.dropdown || !this.trigger) return
+      this.dropdown.hidden = true
+      this.dataset.open = 'false'
+      this.trigger.setAttribute('aria-expanded', 'false')
+
+      this.removeGlobalListeners()
+    }
+
+    private removeGlobalListeners() {
+      document.removeEventListener('click', this.onDocumentClick)
+      document.removeEventListener('keydown', this.onKeyDown)
+    }
+
+    private onToggle = (e: MouseEvent) => {
+      e.stopPropagation()
+      if (!this.dropdown) return
+
+      this.dropdown.hidden ? this.open() : this.close()
+    }
+
+    // Isolated logic for getting language from URL
+    private getLangFromUrl(pathname: string): string | undefined {
+      const segments = pathname.split('/')
+      return segments[1] || undefined
+    }
+
+    // Isolated logic for substituting language in URLs
+    private replaceLocaleInPath(pathname: string, currentLang: string, targetLang: string): string {
+      const segments = pathname.split('/')
+      if (segments[1] === currentLang) {
+        segments[1] = targetLang
+      }
+      return segments.join('/')
+    }
+
+    private onSelect = (event: Event) => {
+      const target = event.target as HTMLElement
+      const button = target.closest<HTMLButtonElement>('[data-ls-item]')
+      if (!button) return
+
+      const lang = button.dataset.lang as Locale | undefined
+      if (!lang) return
+
+      const pathname = window.location.pathname
+      const currentLang = this.getLangFromUrl(pathname)
+
+      if (!currentLang) return
+
+      const { cookieName, cookieMaxAge } = this.dataset
+
+      // Persist the EXPLICIT language choice client-side. The i18n middleware
+      // no longer creates the cookie on plain page views (a cookie-less request
+      // must stay free of Set-Cookie so the HTML edge cache can serve it), so
+      // the switcher is the place where the preference is born. Not httpOnly —
+      // the server only ever reads it (schema-validated), never trusts it.
+      document.cookie = `${cookieName}=${lang}; path=/; max-age=${cookieMaxAge}; SameSite=Lax; Secure`
+
+      window.location.href = this.replaceLocaleInPath(pathname, currentLang, lang)
+    }
+
+    private onDocumentClick = (event: MouseEvent) => {
+      if (!this.contains(event.target as Node)) {
+        this.close()
+      }
+    }
+
+    private onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        this.close()
+      }
+    }
+  }
+
+  if (!customElements.get('language-switcher')) {
+    customElements.define('language-switcher', LanguageSwitcher)
+  }
+</script>

package/src/components/MissingTranslationBanner.astro

@@ -0,0 +1,31 @@
+---
+import { checkMissingTranslation } from '../resolve-locale'
+
+interface Props {
+  // The project's copy for both cases, from its own translations: the engine fetches
+  // nothing here and assumes no namespace. `content`: the page's content is missing in
+  // the selected language; `ui`: the interface is not fully translated.
+  texts: { content: string; ui: string }
+  // Headless: the class comes from here; without it the banner renders no `class`.
+  classes?: Partial<Record<'root', string>>
+}
+
+const { texts, classes = {} } = Astro.props
+const { uiLocale, isMissingContent } = Astro.locals
+
+const missingType = checkMissingTranslation(uiLocale, isMissingContent)
+
+let bannerText: string | null = null
+
+if (missingType) {
+  bannerText = missingType === 'content' ? texts.content : texts.ui
+}
+---
+
+{
+  bannerText && (
+    <div class={classes.root} data-missing={missingType}>
+      {bannerText}
+    </div>
+  )
+}

package/src/config.entry.ts

@@ -0,0 +1,38 @@
+// The `./config` entry: Node-safe. It imports nothing from workerd and no virtual module,
+// so a project's pure modules (unit tests under Node, `src/content.config.ts` evaluated by
+// `astro sync`) can derive the locale constants from the config file directly.
+// `test/node-safe-entries.test.ts` loads it under plain Node to keep it that way.
+import { defineI18nConfig, type I18nConfig, type I18nLanguage, type LocaleOf } from './types'
+
+export { defineI18nConfig }
+export type { I18nBindings, I18nConfig, I18nLanguage, I18nLocales, Locale, LocaleOf } from './types'
+
+export type LocalesOf<C extends I18nConfig> = {
+  DEFAULT_LOCALE: LocaleOf<C>
+  SUPPORTED_LOCALES: [LocaleOf<C>, ...LocaleOf<C>[]]
+  LANGUAGES: Record<LocaleOf<C>, I18nLanguage>
+}
+
+/**
+ * The locale constants of a config: the one derivation, shared by the runtime
+ * (`constants.ts`, over the virtual config) and by project code (over its own
+ * `edgekits-i18n.config.ts`, typed by its own keys without the `I18nLocales` augmentation).
+ *
+ * `defaultLocale` must be one of `languages` at the type level, and is validated at run time.
+ */
+export function localesOf<const C extends I18nConfig>(
+  config: C & {
+    defaultLocale: LocaleOf<C>
+    countryToLocale?: Record<string, LocaleOf<C>>
+    markdownLocale?: LocaleOf<C>
+  },
+): LocalesOf<C> {
+  defineI18nConfig<C>(config)
+
+  return {
+    DEFAULT_LOCALE: config.defaultLocale,
+    // Object.keys widens to string[]; the keys are the config's own `languages` keys.
+    SUPPORTED_LOCALES: Object.keys(config.languages) as [LocaleOf<C>, ...LocaleOf<C>[]],
+    LANGUAGES: config.languages as Record<LocaleOf<C>, I18nLanguage>,
+  }
+}

package/src/config.ts

@@ -0,0 +1,11 @@
+import config from 'virtual:@edgekits/astro-i18n/config'
+
+/**
+ * The project values the i18n engine uses, in one place.
+ *
+ * Contract: this is the ONLY file in `src/` that reads the config, and it reads it
+ * from the virtual module the integration's Vite plugin serves (`test/i18n-boundary.test.ts`
+ * enforces it). The rest of the engine reads these values through `constants.ts` and
+ * `translations-keys.ts`.
+ */
+export const I18N_CONFIG = config

package/src/constants.ts

@@ -0,0 +1,29 @@
+import { I18N_CONFIG } from './config'
+import { localesOf } from './config.entry'
+import type { I18nLanguage, Locale } from './types'
+
+export type { Locale }
+
+export type Language = I18nLanguage
+
+// Languages are configured in the project's edgekits-i18n.config.ts; the derivation is
+// `localesOf` (config.entry.ts), shared with project code. Inside the package the config
+// is not literal, so its keys are narrowed to the augmented `Locale` here.
+const LOCALES = localesOf(I18N_CONFIG)
+
+export const LANGUAGES = LOCALES.LANGUAGES as Record<Locale, Language>
+
+// Locales Configuration
+export const SUPPORTED_LOCALES = LOCALES.SUPPORTED_LOCALES as [Locale, ...Locale[]]
+
+// export const SUPPORTED_LOCALES = ['en', 'de', 'es', 'pt-br', 'ja'] as const
+export type SupportedLocales = (typeof SUPPORTED_LOCALES)[number]
+
+// Default locale
+export const DEFAULT_LOCALE: SupportedLocales = LOCALES.DEFAULT_LOCALE as Locale
+
+// Missing translation banner flag
+export const ENABLE_MISSING_TRANSLATION_BANNER = I18N_CONFIG.missingTranslationBanner
+
+// Cookie name
+export const LANG_COOKIE_NAME = I18N_CONFIG.cookie.name

package/src/cookie-storage.ts

@@ -0,0 +1,32 @@
+import { type AstroCookies } from 'astro'
+
+import { I18N_CONFIG } from './config'
+import { LocaleSchema } from './schema'
+import type { Locale } from './constants'
+import { LANG_COOKIE_NAME } from './constants'
+
+// Self-contained on purpose: the same options and the same invalid-value warning
+// as the project's src/utils/server/cookies.ts, without importing it.
+export function setCookieLang(cookies: AstroCookies, locale: Locale) {
+  cookies.set(LANG_COOKIE_NAME, locale, {
+    path: '/',
+    httpOnly: true,
+    secure: import.meta.env.PROD,
+    sameSite: 'lax',
+    maxAge: I18N_CONFIG.cookie.maxAge,
+  })
+}
+
+export function getCookieLang(cookies: AstroCookies): Locale | null {
+  const entry = cookies.get(LANG_COOKIE_NAME)
+  if (!entry) return null
+
+  const result = LocaleSchema.safeParse(entry.value)
+  if (result.success) return result.data
+
+  if (!import.meta.env.PROD) {
+    console.warn(`Invalid cookie "${LANG_COOKIE_NAME}"`, result.error.issues)
+  }
+
+  return null
+}

package/src/deep-merge.ts

@@ -0,0 +1,38 @@
+function isObject(value: unknown): value is Record<string, unknown> {
+  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
+ */
+export function deepMerge<A extends object, B extends Partial<A>>(base: A, overrides: B): A {
+  const result: any = { ...base }
+
+  for (const key of Object.keys(overrides) as (keyof A)[]) {
+    if (UNSAFE_KEYS.has(key as string)) continue
+
+    const overrideValue = overrides[key]
+    const baseValue = base[key]
+
+    if (overrideValue === undefined) continue
+
+    // For primitives or different types — override directly
+    if (!isObject(baseValue) || !isObject(overrideValue)) {
+      result[key] = overrideValue
+      continue
+    }
+
+    // Both are objects — recurse
+    result[key] = deepMerge(baseValue as any, overrideValue as any)
+  }
+
+  return result
+}