DEV Community: Gary Stupak

Stop Shipping Translations to the Client: Edge-Native i18n with Astro & Cloudflare (Part 2)

Gary Stupak — Tue, 31 Mar 2026 09:16:10 +0000

What you are about to see in this article is not a search for easy paths.

Let me be upfront (and I probably should have mentioned this in Part 1: if you have a simple site with two or three pages, two languages, and no interactive React Islands - just use Astro's built-in i18n routing, build it to static (output: 'static'), and don't overcomplicate your life.

But if it's a complex marketing site and/or you are building a B2B SaaS with a dynamic dashboard, tons of forms, and UGC, where users generate data and marketing demands green LCP metrics despite heavy trackers - that's when classic approaches break down, and our custom architecture pays back every minute invested in its maintenance.

All of this is dictated by my pragmatic love (if love can be pragmatic :)) for this stack and the desire to achieve maximum user convenience alongside premium Lighthouse metrics, Core Web Vitals, and proper SEO.

For a modern business, high website performance is a baseline condition for survival. You cannot count on intensive organic traffic and ad ROI if your architecture allows a "beautiful" React component to block the main thread for three long seconds.

At first glance, this task is woven from unsolvable contradictions - well then, let's try to tackle it.

Spoiler alert: I already realize that fitting all aspects of SEO-readiness and dynamic database localization into this single post is impossible. So today, I will focus strictly on the technical implementation of what was promised in Part 1.

We are still building on top of the Astro EdgeKits Core foundation, but with expanded cases. I will show you everything exactly as it is implemented in production on edgekits.dev.

The first bottleneck where the Zero-JS Astro i18n concept usually breaks down is client-side form validation. Let's see how to master react-hook-form and Zod localization on the Edge, making them work seamlessly with Shadcn UI - all without shipping heavy JSON dictionaries or client-side translation engines to the browser.

Under the Hood: The Subscription Flow Stack

To demonstrate this architecture, we will dissect the Newsletter Subscription flow. It's not just a single <input>; it's a two-step State Machine (Subscribe -> Segment -> Done) that interacts with our database.

Here is the tooling we use to make it happen:

Database: Cloudflare D1.
ORM & Schema Validation: Drizzle (drizzle-orm, drizzle-kit, drizzle-zod).
Server Logic: Astro Actions.
Client State Management: react-hook-form, @hookform/resolvers.
UI Components: Extended Shadcn UI (FieldGroup, Field, FieldLabel, Input, Select, and MultiSelect from the WebDevSimplified (WDS) Shadcn Registry by Kyle Cook.

The Bottleneck: Zod i18n and Client Bundle Bloat

When you build an interactive form in React, the industry-standard reflex is to pair react-hook-form with Zod for validation.

But when you need to internationalize those validation errors (e.g., turning "Invalid email" into "Correo electrónico no válido"), the standard ecosystem pushes you toward packages like zod-i18n-map.

This is a dead end for performance.

To make it work, you have to ship the entire Zod translation dictionary to the client. Suddenly, your carefully optimized, lightweight React Island is dragging an extra 30-50KB of JSON and localization logic into the browser. The main thread chokes, TBT (Total Blocking Time) spikes, and your Web Vitals turn yellow.

We need to validate data on the client to provide instant feedback, but we cannot afford to ship the translations. How do we break this loop?

Zero-JS Validation: Error Codes as a Domain Contract

The root of the problem is treating an error as a string of text.

In a typical application, the UI, the API routes, and the domain logic all know about the t() function. Errors are translated the moment they are created. This creates a chaotic system where it is impossible to understand where an error originated, how to log it, or how to reliably change its language context.

In EdgeKits, we introduced a strict paradigm shift: An error is a part of the domain, not the UI.

Step 1: Strict Literal Types

We replaced translated strings with strict, language-agnostic literal types. We created a single, unified dictionary of error codes for the entire application.

// src/domain/messages/error-codes.ts

// Server actions/apis errors
export const SERVER_ERROR_CODES = {
  INTERNAL_SERVER_ERROR: 'INTERNAL_SERVER_ERROR',
} as const

export type ServerErrorCode =
  (typeof SERVER_ERROR_CODES)[keyof typeof SERVER_ERROR_CODES]

// UI / Validation Errors
export const UI_ERROR_CODES = {
  // Newsletter / identity
  INVALID_EMAIL: 'INVALID_EMAIL',
  EMAIL_ALREADY_EXISTS: 'EMAIL_ALREADY_EXISTS',
  FAILED_TO_INSERT_SUBSCRIBER: 'FAILED_TO_INSERT_SUBSCRIBER',
  // Segmentation
  INTERESTS_REQUIRED: 'INTERESTS_REQUIRED',
  BILLING_OTHER_REQUIRED: 'BILLING_OTHER_REQUIRED',
} as const

export type UiErrorCode = (typeof UI_ERROR_CODES)[keyof typeof UI_ERROR_CODES]

// Merge for usecases where both groups are needed
export const ERROR_MESSAGE_CODES = {
  ...SERVER_ERROR_CODES,
  ...UI_ERROR_CODES,
} as const

export type ErrorMessageCode =
  (typeof ERROR_MESSAGE_CODES)[keyof typeof ERROR_MESSAGE_CODES]

Why this matters:

as const ensures these are strict literal types, not generic strings.
We avoid TypeScript enums, which are better for edge compatibility and serialization.
There is only one set of error codes across the entire product.

Step 2: Zod Speaks in Codes

Now, we enforce this contract at the schema level. When we define our Zod schema for the newsletter form, we don't write human-readable messages. We map the validation failures directly to our domain codes.

// src/db/forms.ts

// In reality, this schema is wider and collects analytics data (e.g. subscription source). We are omitting those fields here for brevity and focusing on validation.

import { z } from 'zod'
import { createInsertSchema } from 'drizzle-zod'
import { subscribers } from '@/db/schema'
import { ERROR_MESSAGE_CODES } from '@/domain/messages'

const SubscriberInsertSchema = createInsertSchema(subscribers)

export const NewsletterFormSchema = SubscriberInsertSchema.pick({
  email: true,
}).extend({
  // Zod returns a domain code instead of a string
  email: z.email({ message: ERROR_MESSAGE_CODES.INVALID_EMAIL }),
})

export type NewsletterFormData = z.infer<typeof NewsletterFormSchema>

If a user enters foo@bar into the client-side form, Zod doesn't try to figure out if the user is German or Japanese. It simply returns "INVALID_EMAIL".

The validation logic is now completely decoupled from the localization layer. The client bundle remains incredibly small because it only contains the schema rules, not the dictionaries.

But what happens when the error doesn't come from Zod, but from the backend? This is where Astro Actions step in.

Astro Actions Error Handling & The `DomainContext` Pattern

So, Zod now returns "INVALID_EMAIL" instead of a human-readable string. But client-side validation is only the first line of defense. What happens when the data is valid, but the business logic fails on the backend? For example, the user submits an email that already exists in your database.

In Astro, the bridge between the client and the server is handled by Astro Actions. However, when running on Cloudflare Workers, we face a unique architectural challenge: bindings.

To access your D1 database or KV namespaces, you need the Cloudflare Env object. Passing this env object through every single service, repository, and utility function is a notorious DX nightmare that pollutes your domain logic with infrastructure details.

(A quick side note: If you are already using the shiny new Astro 6.x with the updated Cloudflare adapter, you can now import { env } from 'cloudflare:workers' directly anywhere in your server code. However, this project is built on Astro 5.x, where env is strictly injected into the request context. More importantly, regardless of the framework version, keeping infrastructure imports out of your domain logic remains a superior architectural pattern for testability and decoupling).

The `DomainContext` Solution

To keep our actions clean and our domain edge-native, we use a strict DomainContext pattern.

A DomainContext is a request-scoped composition root. It is the only place where the Cloudflare Env is used to wire up repositories and services. The Astro Action simply creates the context and delegates the work.

Here is a simplified diagram of this architecture:

graph TD
    A[Astro Action] -->|Passes Env| B(createNewsletterContext)
    B -->|Initializes| C[NewsletterDrizzleRepository]
    B -->|Wires up| D[Domain Services]
    D -.->|Uses| C
    C -.->|Queries| E[(Cloudflare D1)]

Let's break down what is happening here:

Astro Action: The starting point. This is the Astro server function that receives data from the user. It passes the environment variables (Cloudflare bindings) further down the chain.
createNewsletterContext: The initializer. It creates the execution "context" - gathering all the necessary tools for the newsletter operations in one place.
NewsletterDrizzleRepository: The data access layer. It uses the Drizzle ORM to translate our code into raw SQL queries.
Domain Services: The business logic. This is the "brain" of the application that decides exactly what needs to be done with the data before saving it. It uses the repository to communicate with the database.
Cloudflare D1: The final destination. The serverless relational SQL database on the Cloudflare platform where the data is physically stored.

The takeaway: What we have here is a classic manual Dependency Injection pattern. The business logic (Services) is completely decoupled from the database operations (Repository), and everything is cleanly wired together inside a single context the exact moment the Action is invoked.

And here is the actual implementation from our codebase:

// src/domain/newsletter/context.ts

import { NewsletterDrizzleRepository } from './repository'
import { validateContact } from './services'

export function createNewsletterContext(env: Env) {
  // 1. Initialize the concrete repository with Env (D1 binding)
  const repository = new NewsletterDrizzleRepository(env)

  // 2. Return the public API of the domain
  return {
    repository,

    validateContact(input: { email: string }) {
      // The service knows about the repository interface, but knows nothing about Env
      return validateContact(repository, input)
    },

    addContactToDb: async (input: any) => {
      return await repository.insertContact(input)
    },
  }
}

To complete the picture, let's take a look at the validateContact service itself, which is invoked inside the context:

// src/domain/newsletter/services/validate-contact.ts

import { checkEmailExists } from './validation/check-email-exists'
import type { NewsletterRepository } from '../repository/interface'

export async function validateContact(
  repo: NewsletterRepository,
  input: { email: string }
) {
  await checkEmailExists(repo, input.email)
}

But where does that strict error code actually come from? Let's go one level deeper into the checkEmailExists helper to see how the circle completes:

// src/domain/newsletter/services/validation/check-email-exists.ts

import { ERROR_MESSAGE_CODES } from '@/domain/messages/error-codes'
import type { NewsletterRepository } from '../../repository'

export async function checkEmailExists(
  repo: NewsletterRepository,
  email: string
): Promise<void> {
  const exists = await repo.existsByEmail(email)

  if (exists) {
    // We throw the strict domain code, not a localized string!
    throw new Error(ERROR_MESSAGE_CODES.EMAIL_ALREADY_EXISTS)
  }
}

This is the core of our error contract. When the database confirms the email is taken, we don't throw a generic Error("Email already in use") or trigger a translation function. We throw our strict literal type. This error bubbles up through the validateContact service, gets caught by the Astro Action, and is safely passed to the React Orchestrator without ever exposing database internals or coupling the backend to a specific UI language.

Everything here is crystal clear: the services layer knows absolutely nothing about Cloudflare, the Env object, or the D1 database. It simply accepts a strict, abstract repository interface (NewsletterRepository) and executes pure business logic.

This makes your domain 100% testable and completely independent of the underlying infrastructure. If you decide to migrate from D1 to PostgreSQL, or swap Drizzle for Prisma (or even raw SQL) tomorrow, this code won't change by a single line.

Now, look how clean and readable the actual Astro Action becomes:

// src/actions/newsletter.ts

import { ActionError, defineAction } from 'astro:actions'
import { NewsletterActionInputSchema } from './schema'
import { createNewsletterContext } from '@/domain/newsletter/context'
import { ERROR_MESSAGE_CODES, isErrorMessageCode } from '@/domain/messages'

export const newsLetter = {
  subscribe: defineAction({
    input: NewsletterActionInputSchema,
    handler: async (input, context) => {
      // 1. Initialize the domain context using Cloudflare Env
      const newsletter = createNewsletterContext(context.locals.runtime.env)

      try {
        // 2. Execute business logic
        await newsletter.validateContact(input) // Throws if email is filthy or exists

        // Enrich data with Cloudflare Geo-IP before saving
        const { timezone, country, city } = context.locals.runtime.cf ?? {}
        const subscriberId = await newsletter.addContactToDb({
          ...input,
          timezone,
          country,
          city,
        })

        return subscriberId
      } catch (error) {
        // 3. Catch domain errors and safely escalate them to the client
        if (error instanceof Error && isErrorMessageCode(error.message)) {
          throw new ActionError({
            message: error.message, // e.g., "EMAIL_ALREADY_EXISTS"
            code: 'BAD_REQUEST',
          })
        }

        // Fallback for unexpected system crashes
        throw new ActionError({
          message: ERROR_MESSAGE_CODES.INTERNAL_SERVER_ERROR,
          code: 'INTERNAL_SERVER_ERROR',
        })
      }
    },
  }),
}

Two important details here:

The Input Schema: Notice that we use NewsletterActionInputSchema instead of directly reusing the database insert schema. Why? Because API inputs rarely match the database 1:1. The client sends a locale and an email, but the action enriches the payload with Cloudflare's cf object (like country and city) before passing it to the database.
The Type Guard (isErrorMessageCode): When the domain throws an error, we need to ensure we don't accidentally leak a raw SQL error or a stack trace to the frontend. isErrorMessageCode is a strict TypeScript type guard that checks if error.message exactly matches one of our predefined codes in ERROR_MESSAGE_CODES. If it doesn't, we swallow it and return a generic INTERNAL_SERVER_ERROR.

Reducing React Bundle Size: Lazy Loading & State

We now have a client that sends data and a server that safely returns strict Error Codes. How does the UI manage this communication flow without turning into a tangled mess of useEffect hooks?

We decouple the UI components from the business process by introducing a custom hook: useSubscribeNewsletter.

This hook acts as the Orchestrator. It doesn't know anything about CSS or HTML. Its only job is to manage the form's State Machine (subscribe -> segment -> done), communicate with the Astro Action, and route the Error Codes to the React components.

// src/hooks/useSubscribeNewsletter.ts

import { useState } from 'react'
import { actions } from 'astro:actions'
import { isErrorMessageCode, ERROR_MESSAGE_CODES } from '@/domain/messages'

export function useSubscribeNewsletter(locale: string) {
  const [step, setStep] = useState<'subscribe' | 'segment' | 'done'>(
    'subscribe'
  )
  const [pending, setPending] = useState(false)
  const [actionError, setActionError] = useState<string | null>(null)
  const [subscriberId, setSubscriberId] = useState<number | null>(null)

  const subscribeAction = async (values: any) => {
    setPending(true)

    try {
      const { data, error } = await actions.newsLetter.subscribe({
        ...values,
        locale,
      })

      if (error) {
        if (error.code === 'BAD_REQUEST') {
          // Store the strict domain code (e.g., "EMAIL_ALREADY_EXISTS")
          if (isErrorMessageCode(error.message)) {
            setActionError(error.message)
            return
          }
          // Fallback for an uncovered key
          setActionError(ERROR_MESSAGE_CODES.INVALID_EMAIL)
          return
        }
        throw error
      }

      if (data) {
        setActionError(null)
        setSubscriberId(data) // Save ID for the next step
        setStep('segment') // Move state machine forward
      }
    } catch {
      // We will handle global toast notifications here later
    } finally {
      setPending(false)
    }
  }

  // segmentationAction omitted for brevity, but it follows the exact same pattern

  return { pending, step, actionError, setActionError, subscribeAction }
}

The Performance Hack: Lazy Loading

The State Machine pattern gives us a massive performance advantage.

Our subscription flow has two parts: asking for the email (Step 1), and asking for the user's preferences via a complex SegmentationForm using heavy Shadcn Select and MultiSelect components (Step 2).

If we bundle all of this into one file, the client has to download the dropdown logic just to render a simple email input. Instead, we use React's lazy feature right inside our main component, conditionally rendering UI based on the step variable:

// src/components/islands/NewsletterFlow.tsx

import { lazy } from 'react'
import { NewsletterForm } from '@/domain/forms/components/NewsletterForm'
import { useSubscribeNewsletter } from '@/hooks/useSubscribeNewsletter'

// 1. We load the heavy Segmentation form ONLY when the user reaches that step
const LazySegmentationForm = lazy(() =>
  import('@/domain/forms/components/SegmentationForm').then((module) => ({
    default: module.SegmentationForm,
  }))
)

export const NewsletterFlow = ({ t, locale }) => {
  const {
    pending,
    step,
    actionError,
    setActionError,
    subscribeAction,
    segmentationAction,
  } = useSubscribeNewsletter(locale)

  // Step 3: Success State
  if (step === 'done') {
    return (
      <div>
        <h2>{t.newsletter.subscribed.title}</h2>
        <p>{t.newsletter.subscribed.description}</p>
      </div>
    )
  }

  // Step 2: Segmentation State (Lazy Loaded)
  if (step === 'segment') {
    return (
      <div>
        <h3>{t.newsletter.step.segment.title}</h3>
        <LazySegmentationForm
          t={t}
          onSubmit={segmentationAction}
          actionError={actionError}
          setActionError={setActionError}
          pending={pending}
        />
      </div>
    )
  }

  // Step 1: Initial Subscribe State (Rendered by default)
  if (step === 'subscribe') {
    return (
      <div>
        <div>{t.newsletter.step.subscribe.title}</div>
        <NewsletterForm
          t={t.messages}
          source='landing-hero'
          onSubmit={subscribeAction}
          actionError={actionError}
          setActionError={setActionError}
          pending={pending}
        />
      </div>
    )
  }
}

Because our State Machine explicitly defines the step state, Webpack/Vite knows exactly when to request the next chunk of JavaScript.

The user loads the page, downloads almost zero JS, types their email, and clicks "Subscribe." Only while the Astro Action is executing on the Cloudflare Worker does the browser silently download the chunk for the SegmentationForm.

This is how you achieve a 0ms Total Blocking Time (TBT) on the initial load while still building a rich, interactive SaaS application.

Now, we have a fully functioning flow that operates entirely on Domain Error Codes. The final piece of the puzzle is the Final Mile: transforming those codes into human-readable, localized text right before they hit the screen.

The Final Mile: React Hook Form Localization

We have successfully purged human-readable strings from our validation schemas and our server actions. Both Zod and Astro Actions now speak a universal, language-agnostic language of strict literal codes (like "INVALID_EMAIL" or "EMAIL_ALREADY_EXISTS").

But end-users don't speak in literal codes. They need to see "Invalid email address" in English, or "Correo electrónico no válido" in Spanish.

If the domain logic is decoupled from the language, where exactly does the translation happen?

It happens at the very boundary of our application - at the exact moment of rendering the React UI. This is the Final Mile.

The Bridge: Passing Lightweight Dictionaries

Instead of bundling a heavy i18n library (like react-i18next) and initializing translation contexts inside our React tree, we treat translations as pure data.

When the Astro server renders the page, it fetches the necessary translation namespace (e.g., messages.json) from Cloudflare KV (or the Edge Cache) and passes it directly to the React Island as a standard prop.

// src/components/islands/NewsletterFlow.tsx (Simplified)

export const NewsletterFlow = ({ t, locale }) => {
  // 't' is just a lightweight JavaScript object containing our localized strings
  const { messages, newsletter } = t

  return (
    <NewsletterForm
      // We pass only the specific dictionary needed for errors
      t={messages}
      onSubmit={subscribeAction}
      actionError={actionError} // This holds our strict code from the server
      // ...
    />
  )
}

This is the essence of Zero-JS React Hook Form localization. There are no network requests for JSON files from the client, no suspense boundaries, and no bulky i18n engines. The dictionary is just a POJO (Plain Old JavaScript Object) injected during Server-Side Rendering (SSR).

To make this completely clear, here is what that lightweight messages.json dictionary actually looks like:

// locales/en/messages.json

{
  "errors": {
    "ui": {
      "INVALID_EMAIL": "Invalid email address.",
      "EMAIL_ALREADY_EXISTS": "This email address already exists.",
      "INTERESTS_REQUIRED": "Please select at least one product.",
      "BILLING_OTHER_REQUIRED": "Please specify your billing provider."
    },
    "server": {
      "INTERNAL_SERVER_ERROR": "Something went wrong. Please try again."
    }
  },
  "common": {
    "PENDING": "Please wait",
    "SUBSCRIPTION_SUCCEED": "Thanks for your subscription!"
  }
}

Notice the keys in the ui object. They are not random strings; they exactly match the ERROR_MESSAGE_CODES we defined in our domain contract. This is the missing link that ties the backend validation directly to the UI translation without any intermediary mapping logic.

The Component: `FieldErrorLocalized`

Inside our form, we need a component that knows how to read our domain codes and translate them using the provided dictionary.

Let's look at the anatomy of <FieldErrorLocalized />. It receives the error state from react-hook-form (which originates from Zod) and the error state from our Action (which originates from the D1 database).

// src/ui/forms/FieldErrorLocalized.tsx

import { FieldError } from '@/components/ui/field'
import { mapErrorsToI18n } from './error-mapper'

type ErrorLike = { message?: string }

interface FieldErrorLocalizedProps {
  fieldError?: ErrorLike // Error from Zod (react-hook-form)
  actionError?: string | null // Error from Astro Action
  tErrors: Record<string, string> // Our lightweight dictionary
  className?: string
}

export function FieldErrorLocalized({
  fieldError,
  actionError,
  tErrors,
  className,
}: FieldErrorLocalizedProps) {
  if (!fieldError && !actionError) return null

  // We map the domain codes to actual localized strings
  const errors = mapErrorsToI18n(
    [fieldError, actionError ? { message: actionError } : undefined],
    tErrors
  )

  if (!errors.length) return null

  // We render the standard Shadcn UI FieldError component
  return (
    <FieldError
      errors={errors}
      className={className}
    />
  )
}

The component is entirely dumb. It doesn't know what language the user selected. It simply delegates the translation to a pure mapping function.

The Pure Mapper

Here is the function that performs the actual translation. Because Zod and our Actions both output the domain code inside the message property, the mapping logic is beautifully simple:

// src/ui/forms/error-mapper.ts

type ErrorLike = { message?: string }

/**
 * Maps multiple error-like objects (containing domain codes) to localized messages.
 */
export function mapErrorsToI18n(
  issues: Array<ErrorLike | undefined>,
  tErrors: Record<string, string>
): ErrorLike[] {
  return issues
    .map((issue) => {
      // 1. Check if an error exists
      if (!issue?.message) return undefined

      // 2. Use the domain code (e.g., "INVALID_EMAIL") as a key in the dictionary
      const localized = tErrors[issue.message]

      // 3. If no translation is found, we don't render an empty string
      if (!localized) return undefined

      // 4. Return the translated string back in the expected format
      return { message: localized }
    })
    .filter(Boolean) as ErrorLike[]
}

The Result

By isolating localization to the very edges of the UI:

Forms are decoupled: They don't know about i18n or Zod. They just pass errors down.
The Domain is clean: Zod schemas and Astro Actions use strict, type-safe literal codes.
The Bundle is tiny: We completely eliminated the need for zod-i18n-map and any client-side localization engines. The user downloads only the exact strings needed for the current screen.

This architecture scales perfectly. Whether you add toast notifications, global process errors, or new languages, the core domain logic remains untouched, and the client performance remains at an excellent 90+.

Process Errors and Global Toasts

So far, we have covered Field-level errors - issues like a typo in an email that should be displayed directly under the input field.

But what about Process-level events? If the database connection drops unexpectedly, or if the user successfully completes the subscription flow, we need to provide global feedback. In modern UI design, this is usually handled by a Toast notification library (like Sonner).

Because our entire architecture speaks in strict domain codes, integrating localized toasts is incredibly clean. We don't want our useSubscribeNewsletter hook to import translation libraries or know about UI components. Instead, we use the Inversion of Control principle and pass simple callbacks.

Let's update our orchestrator hook to accept success and error callbacks:

// src/hooks/useSubscribeNewsletter.ts (Updated)

import { useState } from 'react'
import { actions } from 'astro:actions'
import {
  COMMON_MESSAGE_CODES,
  ERROR_MESSAGE_CODES,
  isErrorMessageCode,
  type CommonMessageCode,
  type ServerErrorCode,
} from '@/domain/messages'

export function useSubscribeNewsletter(
  locale: string,
  options: {
    onSuccess: (code: CommonMessageCode) => void
    onServerError: (code: ServerErrorCode) => void
  }
) {
  // ... state initialization

  const subscribeAction = async (values: any) => {
    // ... validation logic

    try {
      // ... action call
    } catch {
      // Server / network / unexpected errors
      options.onServerError(ERROR_MESSAGE_CODES.INTERNAL_SERVER_ERROR)
    }
  }

  const segmentationAction = async (values: any) => {
    // ... validation logic
    try {
      const { data, error } = await actions.newsLetter.segment({
        /*...*/
      })

      // ... error handling

      if (data) {
        setActionError(null)
        setStep('done')
        // Trigger the success callback with a strict domain code
        options.onSuccess(COMMON_MESSAGE_CODES.SUBSCRIPTION_SUCCEED)
      }
    } catch (error) {
      options.onServerError(ERROR_MESSAGE_CODES.INTERNAL_SERVER_ERROR)
    }
  }

  return {
    /* ... */
  }
}

Now, back in our NewsletterFlow component (our Island wrapper), we provide those callbacks. Since the wrapper already received the lightweight JSON dictionary via props during SSR, it can instantly translate the domain code and fire the toast notification.

// src/components/islands/NewsletterFlow.tsx

import { toast } from 'sonner'
import { useSubscribeNewsletter } from '@/hooks/useSubscribeNewsletter'
import type { ServerErrorCode, CommonMessageCode } from '@/domain/messages'

export const NewsletterFlow = ({ t, locale }) => {
  const { messages } = t

  const {
    // ...
    subscribeAction,
    segmentationAction,
  } = useSubscribeNewsletter(locale, {
    // We receive the domain code and map it directly to our dictionary
    onSuccess: (code: CommonMessageCode) =>
      toast.success(messages.common[code]),

    onServerError: (code: ServerErrorCode) =>
      toast.error(messages.errors.server[code]),
  })

  // ... render logic
}

(Note: In a future deep-dive, we will explore how to optimize these interactive islands even further using custom client:interaction directives in Astro to delay loading the Toast library until it's actually needed. But for now, standard hydration works perfectly).

And there you have it. A complete, end-to-end interactive flow that handles complex Zod validation, server-side Astro Actions, lazy-loaded components, and global toast notifications - all fully localized, fully type-safe, and without shipping a single megabyte of translation engines to the client.

API Routes, Webhooks & Internal Microservices

Throughout this article, we've relied heavily on Astro Actions for frontend-to-backend communication. In my practice, Actions are the undisputed king for UI interactions because they provide end-to-end type safety out of the box.

I use standard Astro API Routes (src/pages/api/) almost exclusively for external integrations: payment webhooks (Stripe, Paddle, LemonSqueezy), 3rd-party callbacks, or Telegram bot endpoints.

But as your SaaS scales, you will likely offload heavy background tasks to separate, internal Cloudflare Workers via Service Bindings (which allow workers to communicate with zero network latency).

Whether your boundary is an Astro Action serving a React form, or an Astro API Route serving a Telegram bot webhook, the architectural rule remains identical: Localization at the Boundary.

Imagine you have a Telegram Bot API Route that processes a subscription via an internal Billing Worker. Should that internal worker know the user's language or import dictionaries?

Absolutely not.

Internal microservices and domain logic must remain strictly language-agnostic. They communicate exclusively via machine-readable domain codes ("INSUFFICIENT_FUNDS"). It is the responsibility of the API Route (the absolute boundary facing the external world) to intercept this code and translate it right before responding:

// src/pages/api/webhooks/telegram.ts

import type { APIRoute } from 'astro'
import { fetchTranslations } from '@/domain/i18n/fetcher'

export const POST: APIRoute = async (context) => {
  const payload = await context.request.json()

  // 1. Identify the external user's preferred language (e.g., 'es')
  const userLang = payload.message?.from?.language_code || 'en'

  // 2. Call internal language-agnostic service (e.g., via Cloudflare Service Binding)
  const result = await context.locals.runtime.env.BILLING_SERVICE.chargeUser(
    payload.user_id
  )

  if (result.error) {
    // result.error is a strict domain code like "INSUFFICIENT_FUNDS"

    // 3. Fetch the dictionary specifically for this external user
    const { messages } = await fetchTranslations(
      context.locals.runtime,
      userLang,
      ['messages']
    )

    // 4. Translate at the boundary
    const text =
      messages.errors.billing[result.error] ||
      messages.errors.server.INTERNAL_SERVER_ERROR

    // Send localized response back to Telegram API
    await sendTelegramReply(payload.chat.id, text)
    return new Response('OK')
  }

  return new Response('OK')
}

By pushing localization to the extreme edges of your architecture (React Islands for the UI, and API Routes for external consumers), your internal services remain lightweight, highly cacheable, and infinitely easier to test.

Cloudflare D1 & Drizzle ORM Localization (UGC)

The final boss of internationalization is dynamic data. Translating static UI strings like "Submit" is simple, but what about data created by your users? If you are building a multi-tenant SaaS, your users might create product categories or pricing tiers that need to be localized.

How do you store this in Cloudflare D1 using Drizzle ORM? Let's look at the trade-offs of the three standard approaches.

1. The Anti-Pattern: The "Wide Table"

The most common beginner mistake is adding language-specific columns to the main table:

// ❌ The Wide Table Anti-Pattern
export const products = sqliteTable('products', {
  id: integer('id').primaryKey(),
  title_en: text('title_en'),
  title_es: text('title_es'),
  title_de: text('title_de'),
})

This is an architectural dead end. Every time marketing asks to support a new language (e.g., French), you have to run a database migration (ALTER TABLE), update your Drizzle schema, and redeploy the backend.

2. The Enterprise Pattern: Translation Tables

The strict relational approach is to separate the core entity from its translations using a one-to-many relationship.

// ✅ The Relational Pattern
export const products = sqliteTable('products', {
  id: integer('id').primaryKey(),
  price: integer('price'), // Language-agnostic data
})

export const productTranslations = sqliteTable('product_translations', {
  id: integer('id').primaryKey(),
  productId: integer('product_id').references(() => products.id),
  locale: text('locale').notNull(), // 'en', 'es', 'de'
  title: text('title').notNull(),
})

Pros: Infinite scalability. Adding a new language is just inserting a new row, not modifying the schema.
Cons: It requires JOINs for every read query.

To implement Graceful Fallback (the "Split-Brain" logic we discussed in Part 1) in pure SQL, you would perform a double LEFT JOIN - once for the requested uiLocale, and once for the default fallback locale (e.g., 'en'). You then use COALESCE(es.title, en.title) to let the database automatically decide which string to return.

3. The Modern Edge Pattern: JSON Columns

Because Cloudflare D1 is built on SQLite, it has fantastic (and blazingly fast) support for JSON functions. For read-heavy Edge applications, we can leverage this to avoid JOINs entirely.

// 🚀 The Edge Pattern (NoSQL in SQL)
export const products = sqliteTable('products', {
  id: integer('id').primaryKey(),
  // Drizzle handles the JSON parsing automatically
  translations: text('translations', { mode: 'json' }).$type<
    Record<string, { title: string }>
  >(),
})

The stored JSON looks like this:

{
  "en": { "title": "Shoes" },
  "es": { "title": "Zapatos" }
}

Why this wins on the Edge: You retrieve the entire entity with a single, fast D1 read. There are no complex SQL joins. The Graceful Fallback logic is handled cleanly in your TypeScript DomainContext:

// Handled cleanly in the Domain Services layer
const localizedTitle =
  row.translations[uiLocale]?.title ?? row.translations['en'].title

For most SaaS use cases on Cloudflare Workers, this JSON-column approach hits the perfect sweet spot between developer experience, database performance, and schema flexibility.

Conclusion

Internationalization is rarely a feature you can just "bolt on" at the end of a project. When you treat translations as massive JavaScript bundles that must be downloaded, parsed, and executed by the client's browser, you are fundamentally crippling your application's performance.

By inverting the control - by treating errors as strict domain codes, resolving languages in Astro Middleware, and isolating translations to the absolute Edge of your architecture - you achieve something rare. You get a fully localized, type-safe, complex interactive React application that still ships with a Zero-JS localization payload and perfect Core Web Vitals.

This isn't just theory. This is exactly how we built EdgeKits.

Get the Code & Stay Updated

You don't have to build the foundation from scratch. While the advanced Zod mapping, state-machine orchestrators, and DomainContext patterns we discussed today are specific to our production application, the underlying Edge-native i18n architecture - including the Astro middleware, caching logic, and Split-Brain fallback - is available in our open-source starter kit.

👉 Star the Repo to support the project: Astro EdgeKits Core.

Stop Shipping Translations to the Client: Edge-Native i18n with Astro & Cloudflare (Part 1)

Gary Stupak — Wed, 25 Feb 2026 06:41:50 +0000

When I started building EdgeKits.dev, the stack felt like a cheat code for 2026.

Astro on the frontend. Cloudflare Workers on the backend. All-in on the Edge. It promised and delivered incredible TTFB, out-of-the-box SEO, and cheap scalability.

Then the magic broke.

I hit the wall of Astro Internationalization (i18n). It should have been trivial: take a set of JSON files (en.json, de.json) and show the user the right text. But when I surveyed the standard ecosystem - from established tools like astro-i18next to modern solutions like Paraglide JS - I realized they all carried architectural baggage that I couldn't justify shipping in an environment where every byte and every millisecond counts.

In this deep dive, we'll build a completely Zero-JS, Edge-Native i18n architecture. I will show you how to move your routing logic to Astro Middleware, store translation dictionaries in Cloudflare KV, and render localized React Islands without shipping a single byte of JSON to the client.

Why the "Perfect Stack" Cracked

In the SPA world, we accept a lazy pattern: the client loads, detects the browser language, fetches a 50KB translation file, and then the interface makes sense. But in the world of Astro and Island Architecture, this approach starts to feel like an architectural atavism.

I tried fitting standard solutions into the constraints of Cloudflare Workers and hit three fundamental walls.

1. The "Fat Worker" Problem (Bundle Bloat)

Most libraries want you to import JSON files directly into your code. Fine for a static site. May be critical for a Worker. On Cloudflare, every byte of text becomes part of your JavaScript bundle. With a strict 3MB limit on the free tier (and 10MB on paid), "baking" translations into the Worker means stealing space from business logic. It increases cold start times.

I didn't want adding a new language to slow down my entire API.

2. Hydration Hell

This is the classic Astro + React conflict. The Server (SSR) renders English because the URL says so. The Client (React Island) wakes up, checks localStorage, sees "German," and panic-renders.

The result: A flickering UI, a console screaming about hydration mismatches, and a "broken app" feel. Trying to sync state via third-party stores (like Nano Stores) worked, but required writing boilerplate for every single button.

3. CLS and the "Jump"

If we decide not to bundle JSON but fetch it client-side (the old SPA way), we kill our Web Vitals. Users see empty space or raw translation keys while the JSON flies over the wire. For a project obsessed with performance, this was unacceptable.

The Paradigm Shift: Translations are Data, Not Code

Take Paraglide JS, for example. Its compiler and tree-shaking are brilliant. It solves the client-side bloat perfectly. But as I mapped out the architecture for a growing SaaS, I realized it introduced a set of invisible taxes I wasn't willing to pay.

1. The "Fat Worker" Paradox
Tree-shaking is great for the browser, but it simply moves the weight to the Server. Paraglide compiles translations into code. To render SSR, the Worker must load all that code into memory. This is the trap.

On Cloudflare, you have a hard limit on script size (3MB Free / 10MB Paid). "Baking" encyclopedias of text into your executable binary is an anti-pattern. I didn't want my deployment to fail - or my cold starts to spike - just because I added a German translation.

2. The Dynamic Content Gap
Static tools only solve half the problem. Paraglide handles your "Save" button, but it ignores your database. My SaaS runs on Cloudflare D1. How do I translate user-generated content? How do I run SQL LIKE queries on compiled functions? I was staring at a future where I had to maintain two separate i18n stacks: one for the UI (compiled code) and one for the Data (DB).

3. High-Complexity Maintenance
Finally, it trades Latency for Fragility. By adopting a compiler-based approach, you marry your build pipeline to a specific tool. If the workerd runtime updates and the compiler lags, your build breaks. And despite the tooling, it doesn't actually prevent hydration mismatches - if you forget to pass a prop or initialize a store correctly on the client, the UI still flickers.

I needed something else. I wanted i18n to behave like a Content Delivery Service:

The Edge is the Source of Truth: It decides the language based on URL, cookies, and headers.
The Client is "Dumb": It receives ready-to-render data. No guessing.
Zero-JS Payload: Translations are injected into HTML or component props during SSR.

I needed a system that keeps translations close to the user (Cloudflare KV), caches them at the edge (Cache API), and feeds them to Astro components without bloating the Worker bundle. I couldn't find a solution that met these requirements while maintaining full Type-Safety.

That left me with only one option: build a bespoke architecture from scratch.

Edge-Native i18n Architecture: Inverting Control

In a traditional SPA, the client is the boss. It loads, checks navigator.language, and issues a network request for a translation file. This is a "Pull" architecture.

I flipped this model. In EdgeKits, the Client is dumb. It does not guess the language - and it certainly doesn't fetch it over the network. It receives the language as a constraint from the Server.

This is a "Push" architecture.

The Request Flow

Everything happens before the first byte of HTML is flushed to the browser. We moved the "Router" logic entirely into Cloudflare Workers via Astro Middleware.

Here is the lifecycle of a request:

Interception: The request hits the Cloudflare Worker.
Resolution: Our Middleware analyzes the request immediately - checking URL paths (/de/), cookies, and headers.
Data Fetch: The Worker checks the Edge Cache. If it's a miss, it fetches from KV and hydrates the cache.
Injection: Translations are injected directly into Astro props.
Rendering: Astro generates HTML with strings baked in.

By the time the React Island wakes up on the client, the text is already there. No useEffect. No loading spinners. The component hydrates over HTML that matches its props exactly.

The Core Logic: Decoupling Intent from Data

The critical architectural decision here was to split the concept of "Current Locale" into two distinct variables.

Most i18n frameworks tightly couple the URL to the Data. If a user visits /ja/ (Japanese) but you haven't deployed the translation files yet, standard adapters usually force a 302 Redirect back to English. This changes the URL and disrupts the user's intent.

Worse, if the server falls back to English but the client-side router initializes with locale='ja' (derived from the URL), you trigger a Hydration Mismatch. The server sends English HTML, but the client expects Japanese logic, causing the UI to flicker or reset.

I introduced a "Split Brain" model in the request context to prevent this:

uiLocale (The Intent): What the user wants to see. This controls the URL (/ja/about), the <html lang="ja"> tag, and SEO metadata.
translationLocale (The Data): What we can actually show. This controls the dictionary loaded from KV.

Why this matters:
If a user visits /ja/about but we haven't translated the marketing page into Japanese yet, the system doesn't redirect.

uiLocale remains "ja" (preserving the URL and user preference).
translationLocale gracefully falls back to "en".

The site never breaks with undefined is not a function. The user sees the interface in English, but the app structure remains stable. This is Graceful Degradation baked into the core.

Cloudflare KV Data Layer: Solving the "Fat Worker"

The standard advice for i18n is simple: "Just import your JSON files." For a static site, that works. For a Serverless application, it is an architectural trap.

On Cloudflare, your code and your assets compete for the same resources. The Worker script size limit is strict - 3MB on the Free plan and 10MB on Paid.

If you "bake" your translations into the JavaScript bundle, you are stealing space from your business logic. Every time you add a new language or a new blog post translation, your Worker gets fatter. Your cold starts get slower. And eventually, you hit the wall.

I refused to ship text as code.

The Solution: KV as the Source of Truth

I moved the translation dictionaries out of the _worker.js bundle and into Cloudflare KV. In this architecture, translations are treated strictly as external data. They are stored with keys like: edgekits:landing:en, edgekits:common:de.

This decouples the deployment of code from the deployment of content. You can fix a typo in the German pricing page without redeploying the entire application backend.

Edge Caching: The Cache API "Secret Sauce"

KV is fast, but it is not instant. It requires a sub-request. It also costs money - the Free tier caps you at 100,000 reads per day. For a high-traffic application, hitting KV on every single request is a non-starter.

To solve this, the architecture places the Cache API (caches.default) in front of KV.

When a request comes in:

The Worker checks the Edge Cache for edgekits:landing:en.
Hit: It serves instantly (sub-millisecond latency).
Miss: It fetches from KV, constructs the response, and puts it into the Cache with a stale-while-revalidate directive.

The Economic Logic: I accept the latency cost (and the KV bill) on the 1st request to buy 0ms latency and zero KV read costs for the next 10,000 requests. This allows the system to serve millions of users while staying comfortably within the limits of the Free tier.

The Trade-off: HTML Payload Size

There is no free lunch in engineering. By removing the translations from the JavaScript bundle (Zero-JS), I effectively moved that weight into the HTML document.

Since the Client is "dumb" and doesn't fetch JSON, the server must inject the translation data directly into the DOM (usually via props or a script tag) so the React components can hydrate.

The Risk: If you load a massive 50KB JSON file for a page that only displays "Hello World", your initial HTML download size bloats. This can hurt your Time to First Byte (TTFB).

Pro Tip: Namespace Splitting

To mitigate the payload risk, adoption of Namespace Splitting is mandatory. Do not dump every string into a single global common.json. That is a lazy pattern inherited from the SPA era.

Instead, break your translations into granular domains:

buttons.json (Global UI elements)
landing.json (Landing page only)
pricing.json (Pricing page only)
dashboard.json (App only)

In EdgeKits, the fetchTranslations function accepts an array of namespaces. On the Landing Page, I only load ['common', 'hero']. The heavy dashboard strings are never fetched from KV and never injected into the HTML. This keeps the initial document lightweight while ensuring the client has exactly - and only - what it needs to render.

Astro Middleware: The i18n Routing Controller

In a standard Astro app, you might be tempted to check the locale inside your .astro pages or layout files.
Don't.

If you calculate the locale in a Layout, you have already executed too much code. You need to know the language before you render a single component.

I moved this logic entirely into src/domain/i18n/middleware/i18n.ts. This file acts as the "Air Traffic Controller" for the application. It runs on the Edge, intercepts every request, and determines the uiLocale before Astro even boots up the page rendering process.

The Detection Hierarchy

Here, a hierarchy of authority for determining the user's language naturally presents itself, where the user's explicit intent always takes precedence over implicit signals.

URL (The King): If the path is /es/about, the user wants Spanish. Period. This is the primary source of truth.
Cookie (The Override): If the user is at the root / (where no language is specified) but has a locale cookie, I respect that preference.
Browser Header (Astro Native): If no URL prefix and no cookie exist, I leverage Astro's built-in context.preferredLocale to handle the standard Accept-Language negotiation automatically.
Geo-IP (The Safety Net): If all else fails, I use the Cloudflare request.cf.country property to make a best-guess based on location.

The Implementation

Here is the middleware that orchestrates this. It handles the “Soft 404” problem, keeps the Cookie in sync with the URL, and does all the heavy lifting required for seamless i18n routing:

// src/domain/i18n/middleware/i18n.ts

import type { MiddlewareHandler } from 'astro'
import { LocaleSchema, type Locale } from '@/domain/i18n/schema'
import { DEFAULT_LOCALE } from '@/domain/i18n/constants'
import { getCookieLang, setCookieLang } from '@/domain/i18n/cookie-storage'
import { mapCountryToLocale } from '@/domain/i18n/country-to-locale-map'
import { resolveLocaleForTranslations } from '@/domain/i18n/resolve-locale'

const PUBLIC_FILE_REGEX = /\.(ico|png|jpg|jpeg|svg|webp|gif|css|js|map|txt|xml|json|woff2?|avif)$/i
const IGNORED_PREFIXES = ['/api', '/assets', '/_astro', '/_image', '/_actions', '/favicon']

type I18nMiddlewareContext = Parameters<MiddlewareHandler>[0]

function shouldBypassI18n(pathname: string): boolean {
  if (PUBLIC_FILE_REGEX.test(pathname)) return true
  if (IGNORED_PREFIXES.some((p) => pathname.startsWith(p))) return true
  return false
}

function applySecurityHeaders(response: Response): Response {
  return response
}

function buildLocalizedPath(locale: Locale, rest: string[]): string {
  const suffix = rest.join('/')
  return suffix ? `/${locale}/${suffix}/` : `/${locale}/`
}

function resolveFallbackLocale(context: I18nMiddlewareContext): Locale {
  const cookieLocale = getCookieLang(context.cookies)
  if (cookieLocale) return cookieLocale

  const browserRaw = context.preferredLocale
  if (browserRaw) {
    let parsed = LocaleSchema.safeParse(browserRaw)
    if (parsed.success) return parsed.data

    const short = browserRaw.split('-')[0]
    parsed = LocaleSchema.safeParse(short)
    if (parsed.success) return parsed.data
  } else {
    const country = context.locals.runtime?.cf?.country
    const geoLocale = mapCountryToLocale(country)
    let parsed = LocaleSchema.safeParse(geoLocale)
    if (parsed.success) return parsed.data
  }

  return DEFAULT_LOCALE
}

export const i18nMiddleware: MiddlewareHandler = async (context, next) => {
  const url = new URL(context.request.url)
  const pathname = url.pathname

  const segments = pathname.split('/').filter(Boolean)
  const firstSegment = segments[0] ?? null

  let safeLocale = DEFAULT_LOCALE
  if (firstSegment) {
    const parsed = LocaleSchema.safeParse(firstSegment)
    if (parsed.success) {
      safeLocale = parsed.data
    }
  }

  context.locals.uiLocale = safeLocale
  context.locals.translationLocale = resolveLocaleForTranslations(safeLocale)

  if (shouldBypassI18n(pathname)) {
    const response = await next()
    const contentType = response.headers.get('content-type') || ''
    const isHtml = contentType.includes('text/html')
    const isRedirect = response.status >= 300 && response.status < 400

    if (isHtml && !isRedirect) {
      return new Response('Not found', {
        status: 404,
        headers: { 'Content-Type': 'text/plain; charset=utf-8' },
      })
    }
    return response
  }

  const fallbackLocale = resolveFallbackLocale(context)

  if (!firstSegment) {
    const target = buildLocalizedPath(fallbackLocale, [])
    if (pathname !== target) {
      return applySecurityHeaders(context.redirect(target, 302))
    }
    return applySecurityHeaders(await next())
  }

  const parsed = LocaleSchema.safeParse(firstSegment)
  const urlLocale: Locale | null = parsed.success ? parsed.data : null

  if (urlLocale) {
    setCookieLang(context.cookies, urlLocale)
    context.locals.uiLocale = urlLocale
    context.locals.translationLocale = resolveLocaleForTranslations(urlLocale)

    const normalized = buildLocalizedPath(urlLocale, segments.slice(1))
    if (pathname !== normalized) {
      return applySecurityHeaders(context.redirect(normalized, 302))
    }
    return applySecurityHeaders(await next())
  }

  const target = buildLocalizedPath(fallbackLocale, segments)
  if (pathname !== target) {
    return applySecurityHeaders(context.redirect(target, 302))
  }
  return applySecurityHeaders(await next())
}

This function resolves the actual locale we need to request from KV. It gracefully falls back to a default if a translation bundle for the current UI locale is missing:

// src/domain/i18n/resolve-locale.ts

export function resolveLocaleForTranslations(locale: Locale): Locale {
  return hasTranslations(locale) ? locale : DEFAULT_LOCALE
}

The Edge Capability: Geo-IP Fallback

You might notice the mapCountryToLocale helper in the fallback logic. This is where we leverage the Edge platform.

Cloudflare exposes the visitor's country code in every request. Here is a simple, O(1) lookup map to convert codes like DE (Germany) or BR (Brazil) into supported locales.

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

import type { Locale } from './schema.ts'

const GEO_MAP: Record<string, Locale> = {
  // --- ANGLOSPHERE ---
  US: 'en', 
  GB: 'en', 
  // --- DACH ---
  DE: 'de',
  // --- LATAM + SPAIN ---
  ES: 'es',
  // Asia
  JP: 'ja',
}

export function mapCountryToLocale(country: unknown): string | undefined {
  if (typeof country !== 'string') return undefined
  return GEO_MAP[country.toUpperCase()]
}

Why This Design?

This middleware establishes context.locals.uiLocale as the single source of truth.

The React components don't check localStorage. The Layout doesn't parse the URL. They simply read uiLocale from the context. By treating the URL as the strict authority for state, we eliminate the possibility of a "Split Brain" scenario where the URL says English but the Interface renders German.

The "Dumb" Client: Type-Safe i18n for Astro Islands

Astro is famous for shipping "Zero JS" by default. But in the real world, you eventually need interactivity: a Newsletter form, a Pricing toggle, or a User Dashboard. In Astro, these isolated bits of interactivity are called "Islands".

When a React Island wakes up (hydrates), it often realizes: "Wait, I need text!". The standard SPA reflex is to fire a hook like useTranslation, which triggers a network request for a JSON file, shows a loading spinner, and finally causes a Layout Shift (CLS).

The "Standard" React Way (Anti-Pattern for Edge):

// ❌ Bad: Triggers network fetch + Re-render
const { t, ready } = useTranslation()
if (!ready) return <Spinner />
return <div>{t('welcome_message')}</div>

In EdgeKits, we treat the Client as "dumb". It does not know how to fetch translations. It does not know which language is active. It simply receives data via props from the Astro Page Controller.

The Mechanism: Strict Prop Drilling

We moved the complexity from the Components to the Server. The page fetches the specific namespaces it needs from the Edge Cache and passes them down to the Island as a simple JSON object.

The EdgeKits Way:

// src/components/layout/Hero.tsx

interface HeroProps {
  // 1. Strict Type Safety: We know EXACTLY what 'hero' contains
  t: I18n.Schema['landing']['hero']
}

export function Hero({ t }: HeroProps) {
  // 2. No hooks. No generic strings. Just data.
  // 3. Renders instantly. Zero CLS.
  return <h1>{t.headline}</h1>
}

This results in Zero CLS. The HTML arrives at the browser with the text already inside the tags.

Type-Safety: "It compiles, therefore it works"

One of the biggest risks in i18n is "key drift"—when your code asks for t.description but the JSON file has t.desc. I refused to use any.

EdgeKits includes a generator script (npm run i18n:bundle) that scans your src/locales directory and generates a strict TypeScript definition file (I18n.Schema).

If you delete a key in en/common.json, the build fails.
If you mistype a prop name, the build fails.
You get autocomplete for every single string in your project.

This turns internationalization from a runtime guessing game into a compile-time guarantee.

Safe Interpolation: The `fmt()` Helper

Raw JSON is static, but UI is dynamic. We often need to inject variables like "Hello, {name}!".

Shipping a heavy interpolation engine like intl-messageformat to the client defeats the purpose of keeping the bundle small. Instead, I wrote a lightweight, runtime-agnostic helper called fmt().

locales/en/common.json:

{
  "welcome": "Welcome back, <strong>{name}</strong>!"
}

src/components/common/Welcome.tsx:

import { fmt } from '@/domain/i18n/format'

export function Welcome({ t, userName }) {
  // 'fmt' escapes 'userName' to prevent XSS,
  // but preserves the <strong> tag from the JSON.
  const html = fmt(t.welcome, { name: userName })

  return <span dangerouslySetInnerHTML={{ __html: html }} />
}

Localizing React Islands in Astro MDX (The "Final Boss")

Using React components inside Markdown (MDX) is easy. Using internationalized components inside Markdown is a nightmare because MDX doesn't have access to Astro.locals.

The Wrapper Pattern: SSR Prop Injection in Astro

We solve this by treating the Astro component as a "Data Controller" and the React component as a "Pure View".

Instead of making the React component fetch its own translations, we create a thin .astro wrapper that:

Runs on the server.
Accesses Astro.locals.translationLocale.
Fetches the specific translation namespace from KV (or Cache).
Passes the data as typed props to the React component.

1. The React Component (Pure & Dumb)

// src/components/blog/islands/LocalizedCounter.tsx

import { useState } from 'react'
import { pluralIcu } from '@/domain/i18n/format'

interface LocalizedCounterProps {
  t: I18n.Schema['counter']
  initial?: number
  locale: string
}

export const LocalizedCounter = ({ t, initial = 0, locale }: LocalizedCounterProps) => {
  const [count, setCount] = useState(initial)
  const formattedLabel = pluralIcu(count, locale, t.patterns)

  return (
    <div>
      <span>{count}</span>
      <span>{formattedLabel}</span>
      <button onClick={() => setCount(count + 1)}>{t.increment}</button>
    </div>
  )
}

2. The Astro Wrapper (The Bridge)

---
// src/components/blog/LocalizedCounterWrapper.astro

import { LocalizedCounter } from '@/components/blog/islands/LocalizedCounter'
import { fetchTranslations } from '@/domain/i18n/fetcher'

const { translationLocale, runtime } = Astro.locals
const { blog } = await fetchTranslations(runtime, translationLocale, ['blog'])
const t = blog.counter
---

<LocalizedCounter
  client:visible
  t={t}
  locale={translationLocale}
  labels={blog.counter}
/>

3. Usage in MDX

Now we simply inject our island component wrapper into the components prop in our dynamic route, and use <LocalizedCounter /> directly in our .mdx files. The specific strings needed for the counter are "baked" into the component props during the server render.

Resilience & Tooling: Production Grade

If Cloudflare KV is slow or returns an error, we cannot show a blank page.

The Safety Net: Compiled Fallbacks

We implemented a "Belt and Suspenders" approach.

The Belt (Cloudflare KV): Stores all translations. Dynamic.
The Suspenders (Compiled Fallbacks): We compile the Default Locale (e.g., English) directly into the Worker bundle as a JavaScript object.

How it works:
When the middleware requests translations, it performs a deepMerge operation:

// Logic inside fetchTranslations()
const kvResult = await fetchFromKV(namespace) // Might fail or be partial
const fallback = FALLBACK_DICTIONARIES[namespace] // Always exists in memory

// If KV fails, we still render the page in English.
const finalData = deepMerge(fallback, kvResult)

This guarantees 100% Uptime for your base language.

Solving Cache Invalidation (The "Hard" Problem)

Earlier, when discussing The Cache API "Secret Sauce", we placed the Edge Cache in front of our KV store to avoid excessive reads. But how do you invalidate that cache when you fix a typo? Waiting for a TTL (Time To Live) to expire is annoying during deployments.

We solved this with Content-Based Hashing.

Every time you run the build script (npm run i18n:bundle), we calculate a SHA-hash of your translation files. This hash is injected into the code as a constant: TRANSLATIONS_VERSION.

The Cache Key structure looks like this:
project_id:i18n:v<HASH>::<locale>:<namespace>

Scenario A (No changes): You redeploy the code, but didn't touch locales. The Hash stays the same. The Cache HIT rate remains 100%.
Scenario B (Typo fix): You change a string in common.json. The Hash changes. The Worker immediately starts using a new Cache Key.

The result? Instant updates for users, with zero manual cache purging required.

The Developer Experience (DX)

Working with Edge KV stores can be tedious. I didn't want to manually use wrangler kv:key put for every single JSON file.

We automated the entire workflow with three scripts:

npm run i18n:bundle: Scans src/locales, generates the TypeScript Schema, calculates the Version Hash, and prepares a single JSON payload.
npm run i18n:seed: Uploads this payload to your Local KV (Miniflare) so npm run dev works offline.
npm run i18n:migrate: Uploads the payload to your Production Cloudflare KV.

This makes the Edge feel just like Localhost. You change a JSON file, the types update instantly, and the data is one command away from global replication.

i18n URL Strategy: Why We Don't Translate Slugs

When building a multilingual site, the instinct is often to translate everything, including the URL path (/de/blog/architektur).

In EdgeKits, I deliberately chose not to do this. We use English Slugs across all locales (/de/blog/architecture).

Why this wins:

Stable Sharing: The URL is clean and short in any chat app, avoiding Percent-Encoding nightmares for non-Latin alphabets.
Simple Code: We don't need reverse-lookup maps. The file system is the source of truth.
Automated SEO: Generating hreflang tags becomes a simple string replacement operation.

Graceful Degradation & The "Honest UX"

By keeping the English slugs canonical, we solved the routing problem. But what happens at the file-system level?

If a user visits /es/blog/architecture, Astro will look for src/content/blog/es/architecture.mdx. If you haven't written the Spanish translation yet, the standard behavior is to throw a 404 Error. Some developers solve this by copying the English .mdx file into the /es/ folder just to prevent the crash. That is a maintenance nightmare.

Because we decoupled the user's intent (uiLocale) from the available data, we can handle this gracefully at the data-fetching layer. Inside our dynamic route ([...slug].astro), we implemented a dual-fetch fallback:

---
// pages/[lang]/blog/[...slug].astro

// ...

// 1. Try to fetch the requested translation
let post = await getEntry('blog', `${uiLocale}/${slug}`)

// 2. The Graceful Fallback: If missing, load the English original
if (!post) {
  post = await getEntry('blog', `${DEFAULT_LOCALE}/${slug}`)

  // Flag the missing content for the UI
  Astro.locals.isMissingContent = true
}

// 3. If it doesn't exist in English either, then it's a real 404
if (!post) {
  // Turns off the MissingTranslationBanner if it was triggered above
  Astro.locals.isMissingContent = false

  return Astro.rewrite(`/${uiLocale}/404/`)
}

// ...
---

The result is pure magic for the User Experience:
The article text renders in English, but the entire surrounding interface — the navigation menu, the footer, and the formatted Publish Date — remains perfectly localized in Spanish. No 404s. No duplicated files.

The Missing Translation Banner (Dual-Mode)

However, silently swapping content languages can confuse users. To solve this, I introduced the "Honest UX" pattern via a MissingTranslationBanner component.

Instead of a generic warning, the system differentiates between two distinct failure modes: Missing Content (Markdown) and Missing UI (JSON dictionaries).

Content is missing: If Astro.locals.isMissingContent was flagged by our router, the banner tells the user specifically about the text: "Sorry, this article is not yet available in your selected language."
UI is missing: What if the Markdown content exists, but a translator forgot to add blog.json to the Spanish directory? During the build phase (npm run i18n:bundle), our script statically analyzes the filesystem and generates an array of FULLY_TRANSLATED_LOCALES. If the current locale isn't in that list, the banner warns: "Sorry, this page is not yet fully available in your selected language."

Because this banner is isolated, it reads the context directly from Astro.locals and fetches its own localized strings from the messages namespace. I also added a final layer of armor: explicit hardcoded fallbacks right inside the component, just in case the messages.json dictionary itself is the one missing.

---
// src/domain/i18n/components/MissingTranslationBanner.astro

import { checkMissingTranslation } from '@/domain/i18n/resolve-locale'
import { fetchTranslations } from '@/domain/i18n/fetcher'

const missingType = checkMissingTranslation(
  Astro.locals.uiLocale,
  Astro.locals.isMissingContent,
)

let bannerText: string | null = null

if (missingType) {
  const { messages } = await fetchTranslations(
    Astro.locals.runtime,
    Astro.locals.translationLocale,
    ['messages'],
  )

  bannerText =
    missingType === 'content'
      ? messages.errors.ui.MISSING_TRANSLATED_CONTENT ||
        'Sorry, this article is not yet available in your selected language.'
      : messages.errors.ui.MISSING_TRANSLATED_UI ||
        'Sorry, this page is not yet fully available in your selected language.'
}
---

And the function that triggers the banner:

// src/domain/i18n/resolve-locale.ts

// ...

// Checking the completeness of translations
function isFullyTranslated(locale: Locale): boolean {
  return (FULLY_TRANSLATED_LOCALES as readonly string[]).includes(locale)
}

type MissingTranslationType = 'ui' | 'content' | null

export function checkMissingTranslation(
  uiLocale: Locale,
  isMissingContent: boolean | undefined,
): MissingTranslationType {
  if (!ENABLE_MISSING_TRANSLATION_BANNER) return null

  if (isFullyTranslated(uiLocale) && !isMissingContent) return null

  return isMissingContent ? 'content' : 'ui'
}

This is a robust, Zero-JS fallback mechanism that prioritizes transparency and stability above all else.

Conclusion: This Is Just the Beginning

We started this journey with a heavy, client-side approach and ended up with an architecture that is:

Fast: Zero client-side JS for translations. 0ms CLS.
Safe: Fully typed via generated TypeScript schemas.
Resilient: Protected by Edge Caching and compiled Fallbacks.
Clean: No "prop-drilling" hell, thanks to Middleware.

Part 2 is out! 🚀

We just published the continuation where we tackle the Interactive Layer: Zod lazy validation, React Hook Form, and Cloudflare D1 JSON columns.

Read Part 2: Stop Shipping Translations to the Client here.

Get the Code

You don't have to build this from scratch. The entire architecture discussed today is available as an open-source starter kit.

👉 Star the Repo & Start Building: https://github.com/EdgeKits/astro-edgekits-core