@rimelight/ui 0.0.1

package/src/domain/cms/types.ts

@@ -0,0 +1,20 @@
+/**
+ * Minimal shape of an Astro Content Collection entry. Explicitly allowing undefined for all common
+ * SEO fields to resolve monorepo type clashes.
+ */
+export interface BaseCMSContentEntry {
+  id: string
+  data: {
+    title?: string | undefined | null
+    description?: string | undefined | null
+    publishedDate?: Date | undefined | null
+    [key: string]: unknown
+  }
+}
+
+/**
+ * Type guard to safely identify a content entry that satisfies the base library requirements.
+ */
+export function isBaseCMSContentEntry(entry: unknown): entry is BaseCMSContentEntry {
+  return !!entry && typeof entry === "object" && entry !== null && "id" in entry && "data" in entry
+}

package/src/domain/i18n/constants.ts

@@ -0,0 +1,21 @@
+// Locales Configuration
+export const SUPPORTED_LOCALES = ["en", "pt", "ja", "de", "es"] as const
+export type SupportedLocales = (typeof SUPPORTED_LOCALES)[number]
+
+// Default locale
+export const DEFAULT_LOCALE: SupportedLocales = "en"
+
+// Missing translation banner flag
+export const ENABLE_MISSING_TRANSLATION_BANNER = true
+
+// UI Labels
+export const LANGUAGES: Record<SupportedLocales, string> = {
+  en: "English",
+  pt: "Português",
+  ja: "日本語",
+  de: "Deutsch",
+  es: "Español"
+}
+
+// Cookie name
+export const LANG_COOKIE_NAME = "lang"

package/src/domain/i18n/cookie-storage.ts

@@ -0,0 +1,13 @@
+import { type AstroCookies } from "astro"
+
+import { type Locale, LocaleSchema } from "./schema"
+import { setCookie, getCookieWithSchema } from "../../utils/server/cookies"
+import { LANG_COOKIE_NAME } from "./constants"
+
+export function setCookieLang(cookies: AstroCookies, locale: Locale) {
+  setCookie(cookies, LANG_COOKIE_NAME, locale)
+}
+
+export function getCookieLang(cookies: AstroCookies): Locale | null {
+  return getCookieWithSchema(cookies, LANG_COOKIE_NAME, LocaleSchema)
+}

package/src/domain/i18n/country-to-locale-map.ts

@@ -0,0 +1,67 @@
+import type { Locale } from "./schema.ts"
+
+// Key: ISO 3166-1 Alpha-2 Country Code (from request.cf.country)
+// Value: The optimal language to serve
+const GEO_MAP: Record<string, Locale> = {
+  // --- ANGLOSPHERE (Explicitly set to EN) ---
+  US: "en", // United States
+  GB: "en", // United Kingdom
+  AU: "en", // Australia
+  NZ: "en", // New Zealand
+  IE: "en", // Ireland
+  CA: "en", // Canada (Majority EN, fallbacks handle FR better via Accept-Language headers)
+
+  // --- DACH (German) ---
+  DE: "de",
+  AT: "de",
+  CH: "de",
+  LI: "de",
+
+  // --- LATAM + SPAIN ---
+  ES: "es",
+  MX: "es",
+  AR: "es",
+  CO: "es",
+  CL: "es",
+  PE: "es",
+  VE: "es",
+  GT: "es",
+  EC: "es",
+
+  // Asia
+  JP: "ja",
+
+  // --- LUSOPHONE (Portuguese) ---
+  PT: "pt",
+  BR: "pt",
+  AO: "pt",
+  MZ: "pt"
+
+  // --- FRANCOPHONE ---
+  //   FR: 'fr',
+  //   BE: 'fr',
+  //   MC: 'fr',
+  //   SN: 'fr',
+
+  // --- SLAVIC / POST-SOVIET ---
+  //   UA: 'uk',
+  //   RU: 'ru',
+  //   KZ: 'ru',
+  //   BY: 'ru',
+
+  // Add other mappings as needed...
+}
+
+/**
+ * Maps a Cloudflare Country Code to a supported App Locale. Returns undefined if no direct mapping
+ * exists (falling back to default strategy).
+ */
+export function mapCountryToLocale(country: unknown): string | undefined {
+  // Safety: In dev mode (localhost), 'country' might be null or undefined.
+  if (typeof country !== "string") return undefined
+
+  // Cloudflare always sends uppercase (e.g., 'US', 'DE'), but safety first.
+  const code = country.toUpperCase()
+
+  return GEO_MAP[code]
+}

package/src/domain/i18n/fallbacks.generated.ts

@@ -0,0 +1,230 @@
+// Auto-generated by scripts/bundle-translations.ts
+// Do not edit manually.
+
+export const FALLBACK_LOCALE = "en" as const
+
+export const FALLBACK_BLOG = {
+  meta_title: "Blog | Daniel Marchi",
+  hero_title: "Blog",
+  hero_description: "My insights throughout my journey as a developer.",
+  latest_article: "Latest Article",
+  latest: "Latest",
+  read_article: "Read Article",
+  all_posts: "All Posts"
+} as const
+
+export const FALLBACK_CHAT = {
+  title: "Join a Chat Room",
+  description: "Enter a room name to start chatting",
+  heading: "Real-time Chat",
+  intro:
+    "Enter a room name below to join a conversation. Each room is a unique Durable Object instance!",
+  label: "Room Name",
+  placeholder: "e.g. general, help, coffee-break",
+  button: "Join Room",
+  room: {
+    title: "Chat Room",
+    connecting: "Connecting…",
+    connected: "Connected",
+    disconnected: "Disconnected",
+    placeholder: "Type a message…",
+    send: "Send",
+    system: {
+      joining: "Joining room…",
+      error: "Connection error",
+      joined: "joined the room",
+      left: "left the room",
+      reconnecting: "Reconnecting in {delay} seconds... (attempt {attempt}/{max})",
+      fail_reconnect: "Failed to reconnect. Please refresh the page.",
+      no_connect: "Cannot send message: not connected",
+      prompt_user: "Enter your username:",
+      you: "(You)",
+      online_users: "Online Users:"
+    }
+  }
+} as const
+
+export const FALLBACK_COMMON = {
+  seo: {
+    title: "Zero-JS i18n Astro Starter for Cloudflare Workers",
+    description:
+      "Ship multilingual apps faster without hydration bloat. Full integration with Cloudflare Workers & KV, automated TypeScript generation, and edge caching out of the box."
+  },
+  nav: {
+    home: "Astro components & islands",
+    blog: "Markdown i18n examples",
+    mobileButton: "Menu"
+  },
+  footer: {
+    license: "Under the MIT license."
+  },
+  notFound: {
+    title: "404 — Page not found",
+    message: "The page you are looking for does not exist or has been moved.",
+    backToHome: "Go back to homepage"
+  }
+} as const
+
+export const FALLBACK_COOKIE_NOTICE = {
+  title: "Cookie Policy",
+  description:
+    "This website does not use cookies, this is a sample of how it could work in your website as per your",
+  privacy_policy: "Privacy Policy",
+  reject_all: "Reject All",
+  accept_all: "Accept All",
+  accepted_toast: "Cookies Accepted",
+  accepted_description: "You have accepted all cookies.",
+  rejected_toast: "Cookies Rejected",
+  rejected_description: "You have rejected all cookies."
+} as const
+
+export const FALLBACK_EDITOR = {
+  title: "Editor",
+  description: "Collaborative real-time document editor",
+  collaborative_editor: "Collaborative Editor",
+  status: {
+    connecting: "Connecting…",
+    connected: "Connected",
+    disconnected: "Disconnected"
+  },
+  history: "History",
+  version_history: "Version History",
+  no_versions: "No versions yet.",
+  placeholder: "Start typing… your changes are synced in real-time.",
+  word_count: {
+    word: "word",
+    words: "words",
+    character: "character",
+    characters: "characters"
+  },
+  save: {
+    saved: "Saved"
+  },
+  restore_confirm: "Restore this version? Current content will be replaced."
+} as const
+
+export const FALLBACK_ERRORS = {
+  "404_title": "Page Not Found",
+  "404_description": "The page you are looking for does not exist.",
+  "500_title": "Internal Server Error",
+  "500_description": "Something went wrong on our end. Please try again later."
+} as const
+
+export const FALLBACK_HOME = {
+  meta_title: "Daniel Marchi | Web Developer",
+  meta_description: "I'm a web developer specialized in Astro and high-performance websites.",
+  hero_title: "Hey, I'm Daniel Marchi",
+  hero_description: "I'm a web developer specialized in Astro and high-performance websites.",
+  hero_view_components: "View Components",
+  hero_contact_me: "Contact Me",
+  stack_title: "Modern Web, Modern Stack",
+  stack_description:
+    "I help individuals and companies build high-performance web applications deployed on the edge. From architecture to deployment, I ensure your project is built for scale.",
+  stack_view_services: "View Services",
+  stack_resume: "Resume",
+  marquee_title: "Built and deployed with these amazing technologies:",
+  projects_title: "Recent Projects",
+  projects_description: "A selection of my latest technical work and open source projects.",
+  projects_view_all: "View All Projects",
+  cta_title: "Ready to Build Something Amazing?",
+  cta_description:
+    "I'm currently available for new projects and consulting. Let's work together to bring your vision to life.",
+  cta_contact: "Get in Touch",
+  cta_resume: "Download Resume"
+} as const
+
+export const FALLBACK_MESSAGES = {
+  errors: {
+    ui: {
+      MISSING_TRANSLATED_UI:
+        "Sorry, this page is not yet fully available in your selected language.",
+      MISSING_TRANSLATED_CONTENT:
+        "Sorry, this article is not yet available in your selected language."
+    }
+  }
+} as const
+
+export const FALLBACK_NAV = {
+  home: "Home",
+  projects: "Projects",
+  blog: "Blog",
+  about: "About",
+  services: "Services",
+  resume: "Resume",
+  contact: "Contact",
+  components: "Components",
+  privacy_policy: "Privacy Policy",
+  terms_of_service: "Terms of Service",
+  cookie_policy: "Cookie Policy"
+} as const
+
+export const FALLBACK_PROJECTS = {
+  meta_title: "Projects | Daniel Marchi",
+  hero_title: "Projects",
+  hero_description: "A showcase of my work and open source contributions.",
+  latest: "Latest Project",
+  latest_badge: "Latest",
+  view_project: "View Project",
+  all: "All Projects"
+} as const
+
+export const FALLBACK_SERVICES = {
+  meta_title: "Services | Daniel Marchi",
+  hero_title: "Premium Services",
+  hero_description:
+    "I provide high-quality development and design services to help your business grow and stand out in the digital landscape.",
+  capabilities_title: "Capabilities",
+  capabilities_description: "An overview of the core services I provide to my clients.",
+  web_dev_title: "Web Development",
+  web_dev_description:
+    "Crafting high-performance, accessible, and scalable web applications using modern technologies like Astro, Vue, and Nuxt.",
+  ui_ux_title: "UI/UX Design",
+  ui_ux_description:
+    "Creating intuitive and visually stunning user interfaces focusing on user experience and brand identity.",
+  perf_title: "Performance Optimization",
+  perf_description:
+    "Audit and optimize your website for speed, SEO, and accessibility to achieve perfect Lighthouse scores.",
+  perf_security_title: "Performance & Security",
+  perf_security_description:
+    "Your users deserve a fast and secure experience. I build websites that load instantly and perform flawlessly across all devices.",
+  testimonials_title: "What Our Users Say",
+  testimonials_description:
+    "Join thousands of developers building the next generation of the web with Astronaut.",
+  faq_title: "Frequently Asked Questions",
+  faq_description:
+    "Everything you need to know about Astronaut and how to build amazing things with it.",
+  cta_title: "Ready to Start?",
+  cta_description:
+    "Let's collaborate on your next big project. I'm currently available for freelance work and consulting.",
+  cta_contact: "Get in Touch",
+  cta_portfolio: "View Portfolio",
+  badge_ceo: "CEO",
+  badge_founder: "Founder",
+  badge_cto: "CTO",
+  badge_senior_ui: "Senior UI Engineer",
+  badge_chef: "Chef",
+  badge_product_designer: "Product Designer",
+  testimonial_1:
+    "Astronaut is hands down the best boilerplate I've ever used. The speed and clean architecture matching perfectly with how I want to build.",
+  testimonial_2:
+    "The component library and the way it handles Tailwind 4 is a game changer. I was able to launch my project in record time.",
+  testimonial_3:
+    "Finally a boilerplate that doesn't feel bloated but gives me all the tools I need. The SSR support on Cloudflare is flawless.",
+  testimonial_4:
+    "The best starting point for any modern web project. The developer experience is world-class and the performance is unbeatable.",
+  testimonial_5:
+    "Incredible attention to detail in the structure. It follows all the best practices without adding unnecessary complexity.",
+  testimonial_6:
+    "Everything is so smooth! Transitions, components, logic - it all just clicks. Best decision for my latest startup.",
+  faq_category_general: "General",
+  faq_q1: "What is Astronaut?",
+  faq_a1:
+    "Astronaut is a production-ready boilerplate for Astro, designed with speed, performance, and best practices in mind. It uses Tailwind CSS 4, Nuxt UI patterns, and a clean architecture.",
+  faq_q2: "How do I get started?",
+  faq_a2:
+    "You can simply clone the repository, install dependencies with pnpm, and run the dev server. The project structure is standard Astro, so you'll feel right at home.",
+  faq_category_technical: "Technical",
+  faq_q3: "Does it support Server-Side Rendering (SSR)?",
+  faq_a3:
+    "Yes, Astronaut fully supports SSR and is configured for deployment on Cloudflare Workers by default, giving you the best of both worlds: static speed and dynamic power."
+} as const

package/src/domain/i18n/fetcher.ts

@@ -0,0 +1,268 @@
+import { SITE_CONFIG } from "../../config"
+import { TRANSLATIONS_VERSION } from "./runtime-constants"
+let env: any = {}
+try {
+  // @ts-ignore
+  const workers = await import(/* @vite-ignore */ "cloudflare:workers")
+  env = workers.env
+} catch {
+  // Safe fallback for Node.js environments (Astro config, local scripts)
+  env = {}
+}
+import type { Locale, Namespace, PickSchema } from "./schema"
+import { deepMerge } from "../../utils/shared/deep-merge"
+import { parseBooleanFlag } from "../../utils/shared/parse-boolean"
+
+// Optional fallbacks (auto-loaded if generated)
+let FALLBACKS: Record<string, unknown> | null = null
+
+try {
+  FALLBACKS = await import("./fallbacks.generated.ts")
+} catch {
+  FALLBACKS = null
+}
+
+const KV_JSON_OPTIONS = { type: "json" as const, cacheTtl: 3600 }
+
+function assertRecord(obj: unknown): asserts obj is Record<string, unknown> {
+  if (!obj || typeof obj !== "object") throw new Error("Expected record")
+}
+
+function assertDefaultCache(obj: unknown): asserts obj is {
+  match: (r: Request) => Promise<Response | undefined>
+  put: (r: Request, res: Response) => Promise<void>
+} {
+  if (!obj || typeof obj !== "object") throw new Error("Expected cache")
+}
+
+function assertSchema<N extends Namespace>(obj: unknown): asserts obj is PickSchema<N> {
+  if (!obj) throw new Error("Expected schema")
+}
+
+function assertA<N extends Namespace>(obj: unknown): asserts obj is PickSchema<N> {
+  if (!obj) throw new Error("Expected result")
+}
+
+/**
+ * Runtime object provided by Astro via Astro.locals.
+ */
+export interface Runtime {
+  cf?: unknown
+  cfContext: { waitUntil: (p: Promise<unknown>) => void }
+}
+
+/**
+ * Fetch translations from KV for a given locale and list of namespaces.
+ *
+ * Responsibilities:
+ *
+ * - Build KV keys using SITE_CONFIG.id, namespace and locale
+ * - Optionally use edge cache (controlled by env flag I18N_CACHE)
+ * - On cache miss, read from KV and merge with optional FALLBACK_* dictionaries
+ * - Persist the merged payload back to the edge cache
+ * - If KV is unavailable, fall back to static FALLBACK_* dictionaries only
+ */
+export async function fetchTranslations<N extends Namespace>(
+  runtime: Runtime,
+  lang: Locale,
+  namespaces: readonly N[]
+): Promise<PickSchema<N>> {
+  const useCache = isCacheEnabled(env)
+
+  if (!useCache) {
+    debug(env, "i18n cache DISABLED, using KV only", { lang, namespaces })
+  }
+
+  const { cache, waitUntil } = useCache ? getEdgeCache(runtime) : { cache: null, waitUntil: null }
+
+  const keys = namespaces.map((ns) => `${SITE_CONFIG.id}:${ns}:${lang}`)
+
+  const { cacheRequest } = buildCacheKey(lang, namespaces)
+
+  // 1. Try to serve from edge cache if available and enabled
+  if (useCache && cache) {
+    try {
+      const cached = await cache.match(cacheRequest)
+
+      if (cached) {
+        const json = await cached.json()
+        assertSchema<N>(json)
+        debug(env, "i18n cache HIT", { lang, namespaces })
+        return json
+      }
+      debug(env, "i18n cache MISS (no entry)", { lang, namespaces })
+    } catch (error) {
+      debug(env, "i18n cache READ error, falling back to KV", error)
+    }
+  }
+
+  // 2. Cache is missing, disabled, or unavailable → read from KV
+  try {
+    const data = await loadTranslationsFromKV(env, keys, namespaces)
+    debug(env, "i18n KV OK", { lang, namespaces })
+
+    // 3. Store the resulting payload in the edge cache asynchronously (if enabled)
+    if (useCache && cache && waitUntil) {
+      try {
+        const response = new Response(JSON.stringify(data), {
+          headers: {
+            "Content-Type": "application/json; charset=utf-8",
+            "Cache-Control": "public, s-maxage=3600, stale-while-revalidate=86400"
+          }
+        })
+
+        const putPromise = cache.put(cacheRequest, response.clone())
+
+        // In real Workers: schedule as a background task.
+        // In dev / non-Workers: just await so cache is actually written.
+        if (waitUntil) {
+          waitUntil(putPromise)
+        } else {
+          await putPromise
+        }
+
+        debug(env, "i18n cache PUT completed", { lang, namespaces })
+      } catch (error) {
+        debug(env, "i18n cache WRITE error", error)
+      }
+    }
+
+    return data
+  } catch (error) {
+    debug(env, "i18n KV ERROR, using FALLBACK_* only", error)
+
+    // 4. Hard fallback to static FALLBACK_* constants if KV is unavailable
+    return buildFallbackOnly(namespaces)
+  }
+}
+
+/**
+ * Narrow runtime.caches and runtime.ctx to the minimal shape needed for using the Cache API and
+ * waitUntil in this module.
+ */
+function getEdgeCache(runtime: Runtime): {
+  cache: {
+    match: (r: Request) => Promise<Response | undefined>
+    put: (r: Request, res: Response) => Promise<void>
+  } | null
+  waitUntil: ((p: Promise<unknown>) => void) | null
+} {
+  return {
+    cache: getCacheFromStorage(),
+    waitUntil: runtime.cfContext?.waitUntil ?? null
+  }
+}
+
+function getCacheFromStorage(): {
+  match: (r: Request) => Promise<Response | undefined>
+  put: (r: Request, res: Response) => Promise<void>
+} | null {
+  const c = Reflect.get(Object(caches), "default")
+  try {
+    assertDefaultCache(c)
+    return c
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Build a stable cache key and synthetic Request object used with the Cache API. The URL origin is
+ * irrelevant; only the string identity matters.
+ */
+function buildCacheKey<N extends Namespace>(
+  lang: Locale,
+  namespaces: readonly N[]
+): { cacheId: string; cacheRequest: Request } {
+  const cacheId = `${SITE_CONFIG.id}:i18n:v${TRANSLATIONS_VERSION}:${lang}:${namespaces.join(",")}`
+
+  const cacheRequest = new Request(`https://i18n-cache/${encodeURIComponent(cacheId)}`)
+
+  return { cacheId, cacheRequest }
+}
+
+/**
+ * Read bulk translations from KV and merge with optional FALLBACK_* dictionaries. This is the main
+ * "happy-path" loader.
+ */
+async function loadTranslationsFromKV<N extends Namespace>(
+  environment: Env,
+  keys: string[],
+  namespaces: readonly N[]
+): Promise<PickSchema<N>> {
+  const resultMap = await environment.TRANSLATIONS.get(keys, KV_JSON_OPTIONS)
+
+  const data: Partial<PickSchema<N>> = {}
+
+  for (let i = 0; i < namespaces.length; i++) {
+    const ns = namespaces[i]!
+    const key = keys[i]!
+    const value = resultMap.get(key) ?? {}
+    assertRecord(value)
+
+    const fallbackConstName = `FALLBACK_${String(ns).toUpperCase()}`
+    const fallback = FALLBACKS?.[fallbackConstName]
+
+    if (fallback) {
+      assertRecord(fallback)
+      Reflect.set(data, ns, deepMerge(fallback, value))
+    } else {
+      Reflect.set(data, ns, value)
+    }
+  }
+
+  assertA<N>(data)
+  return data
+}
+
+/**
+ * Build a payload using only FALLBACK_* dictionaries. Used when KV is unavailable or throws
+ * unexpectedly.
+ */
+function buildFallbackOnly<N extends Namespace>(namespaces: readonly N[]): PickSchema<N> {
+  const empty: Partial<PickSchema<N>> = {}
+
+  for (let i = 0; i < namespaces.length; i++) {
+    const ns = namespaces[i]!
+    const fallbackConstName = `FALLBACK_${String(ns).toUpperCase()}`
+    const fallback = FALLBACKS?.[fallbackConstName]
+
+    ;(empty as Record<string, unknown>)[ns] = fallback ?? {}
+  }
+
+  assertSchema<N>(empty)
+  return empty
+}
+
+/**
+ * Determine whether edge caching is enabled.
+ *
+ * Wrangler var: I18N_CACHE = "on" | "off" | "true" | "false" | "1" | "0"
+ *
+ * After adding the variable:
+ *
+ * - Update wrangler.jsonc / wrangler.toml or .dev.vars
+ * - Run: npm run typegen
+ */
+function isCacheEnabled(environment: Env): boolean {
+  // env.I18N_CACHE is generated by `wrangler types`
+  return parseBooleanFlag(environment.I18N_CACHE, /* defaultValue */ true)
+}
+
+/**
+ * Debug logger controlled by a Wrangler variable.
+ *
+ * Wrangler var: DEBUG_I18N = "on" | "off" | "true" | "false" | "1" | "0"
+ *
+ * After adding the variable:
+ *
+ * - Update wrangler.jsonc / wrangler.toml or .dev.vars
+ * - Run: npm run typegen
+ */
+function debug(environment: Env, ...args: unknown[]) {
+  const enabled = parseBooleanFlag(environment.DEBUG_I18N, /* defaultValue */ false)
+  if (!enabled) return
+
+  // eslint-disable-next-line no-console
+  console.log(...args)
+}

package/src/domain/i18n/flags.ts

@@ -0,0 +1,16 @@
+import type { Locale } from "./schema"
+
+// Explicit locale → flag mapping
+export const FLAG_CODES = {
+  en: "us-4x3",
+  ja: "jp-4x3",
+  de: "de-4x3",
+  es: "es-4x3",
+  pt: "br-4x3"
+} as const
+
+export type FlagCode = (typeof FLAG_CODES)[keyof typeof FLAG_CODES]
+
+export const localeToFlagCode = (locale: Locale): FlagCode | null => {
+  return locale in FLAG_CODES ? FLAG_CODES[locale] : null
+}