DEV Community: Gary Stupak

Astro i18n in 2026: The Complete Guide From ui.ts to Edge-Native KV

Gary Stupak — Fri, 01 May 2026 10:07:19 +0000

Every practical approach to multilingual Astro sites: native routing, Content Collections, ui.ts, Paraglide JS, forms with Zod 4, and the Edge-Native KV pattern. Real-world trade-offs.

I needed to ship EdgeKits.dev in four languages. The first 40% of the work was easy: configure i18n, sprinkle getRelativeLocaleUrl where needed, organize the folders by locale. The other 60% was a tour through the i18n ecosystem most tutorials politely skip.

I started with bundled ui.ts dictionaries - clean enough until they weren't. Then Paraglide, whose client-side tree-shaking is brilliant - until you run the server-side math forward and watch every additional locale and every new namespace pile more translation code into the bundle that was supposed to hold your business logic.

The deploy side wasn't quiet either: every hero-copy iteration was costing a full rebuild, and the lean deploy flow I'd promised myself was no longer lean.

Every layer of this problem has a fix - and every fix has a cost the docs forget to print.

This guide is the map I wish I had then.

We'll walk seven levels of i18n maturity in Astro, from "I just need a /en/ and /es/ folder" to "translations are runtime data, not build-time code." At each level we'll look at what you actually get, what it costs, and the specific symptoms that mean you've outgrown it.

We'll cover Astro 5–6's native i18n routing, the official ui.ts recipe, and Paraglide JS v2. We'll look at the state of astro-i18next and astro-i18n-aut in 2026 - one is archived, the other isn't, but probably should be.

And we'll work through the form-validation problem with Zod 4 and React Hook Form, the deployment treadmill that hits as soon as a CMS shows up, and the bundle limits that hit if a CMS doesn't.

By the end you should know exactly which level fits your project today - and which symptom will tell you when it's time to move up.

Astro i18n Is Two Problems, Not One

Astro i18n is talked about as one topic, but it's really two - and most resources you'll find treat them as one.

Organizing blog posts in src/content/blog/en/ and src/content/blog/es/ is one problem.

Defining a dictionary that maps nav.home to "Home" is a different problem.

Both get framed as "translation." Both are real. They share a feature in astro.config.mjs and almost nothing else.

Mixing them up is how you end up choosing a tool for the wrong layer and not understanding why it doesn't quite fit.

Content Localization vs UI Localization

The first layer is content: full pages and page-sized chunks. Blog posts, documentation, marketing landing copy, MDX articles. The translation unit is a whole document, typically in Markdown or MDX with frontmatter. Authors are content people. Edits happen at content cadence - once a week, once a month, once when somebody flags a typo.

The second layer is UI: small strings interleaved with code. Button labels, form placeholders, validation errors, toast messages, navigation items, footer microcopy. The translation unit is a key-value pair. Authors are developers. Edits ship every time you ship a feature.

Different translation units, different authors, different cadence, different storage, different runtime. Until you see the split clearly, every i18n tool feels half-right.

A Map of Tools to Layers

Astro Content Collections, the [locale] dynamic-route pattern, and headless CMS integrations all live on the content side. They're optimized for documents.

ui.ts dictionaries, Paraglide JS, astro-i18next, astro-i18n-aut, and the runtime KV pattern we'll get to in Level 7 all live on the UI side. They're optimized for strings.

Native Astro i18n routing - the i18n config in astro.config.mjs, getRelativeLocaleUrl, Astro.currentLocale - sits underneath both layers. It tells the framework which language a request is for. It does not localize anything.

Hold this two-layer model in your head for the rest of the guide. Every tool we discuss solves exactly one of these two problems - most of the confusion in the ecosystem comes from libraries that talk like they solve both.

Level 1 - Astro Native i18n Routing (What You Actually Get for Free)

Astro has had built-in i18n routing since version 4, with default-behavior tweaks in 5 and 6. The first thing to understand about it: it does not localize anything. It tells the framework which language a request is for. That's a foundational primitive - and it's also the entire scope of the feature.

What you get is URL routing with locale awareness, helpers to generate locale-aware links, and a fallback policy when content is missing in a given language. What you don't get is a translation system, a dictionary format, or any opinion on how Hello world becomes Hola mundo on the page.

Native routing is the foundation underneath every other level in this guide. Get it set up correctly and most of what follows builds cleanly on top. Skip it and you'll spend the next three levels reinventing things Astro already does.

The `i18n` Config in `astro.config.mjs`

The starting point is a single block in your Astro config:

// astro.config.mjs

import { defineConfig } from 'astro/config'

export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'de', 'ja'],
    routing: {
      prefixDefaultLocale: false,
      redirectToDefaultLocale: true,
    },
    fallback: {
      es: 'en',
      de: 'en',
      ja: 'en',
    },
  },
})

The five options that matter:

defaultLocale - the locale used when no other signal is available. Must be one of the entries in locales.
locales - every locale the site supports. Plain strings work for simple cases; you can also pass objects with path and codes if you want to group several BCP 47 codes (e.g., en-US and en-GB) under a single URL path.
routing.prefixDefaultLocale - whether the default locale appears in URLs as a prefix. Discussed in detail below.
routing.redirectToDefaultLocale - when the default locale has no prefix, whether requests like /en/about should redirect to /about. Also discussed below.
fallback - when a locale is missing a route, which other locale's version Astro should render in its place.

There's also i18n.domains, which maps locales to fully-qualified domains. That's its own pattern with its own trade-offs and gets its own section below.

Routing Strategies: Prefix Default vs Prefix Others Only

The two routing options interact with each other. Get them right and your URL structure is exactly what you want. Get them wrong and you can ship infinite-loop redirects to production.

Two combinations make sense in practice:

Default locale at root, others prefixed. prefixDefaultLocale: false with redirectToDefaultLocale: true. English lives at /about, Spanish at /es/about, German at /de/about. Cleanest for sites with a primary-language audience. The redirect setting means anyone hitting /en/about is bounced to /about - which keeps Google from indexing both URLs as duplicate content for the same page.

All locales prefixed. prefixDefaultLocale: true. English at /en/about, Spanish at /es/about. Cleaner for analytics (every URL is locale-tagged), better for sites where no language is "primary." redirectToDefaultLocale is a no-op in this mode.

A note on Astro 6: the default for redirectToDefaultLocale flipped from true to false to remove a footgun. With the old default, a prefixDefaultLocale: false setup combined with certain custom redirect chains could produce infinite-loop redirects in production.

If you're upgrading from Astro 5 and your routing suddenly behaves differently, this is the first thing to check. Setting both flags explicitly - as in the snippet above - makes the config behave the same across both versions.

Subdirectories vs Subdomains: A Short Decision Note

There's an old SEO debate about whether multilingual sites should use subdirectories (/es/about) or subdomains (es.example.com). For most projects, subdirectories win. They share link equity, they simplify deployment, and Astro's default routing handles them out of the box.

Subdomains make sense when each language is functionally a separate site: different content team, different deployment cadence, different stack underneath. For that case, Astro has i18n.domains (covered below), which lets you map locales to fully-qualified domains while keeping a single codebase.

The third option - country-code TLDs (example.de, example.es) - is a much bigger commitment. It signals to Google that you're targeting a specific country, not just a language. Use it when you're a multinational brand with country-specific operations, not when you're a SaaS that happens to support German.

The `astro:i18n` Helpers You'll Actually Use

The astro:i18n module exports a small set of utilities for working with locale-aware URLs. Most of them you'll touch exactly once - in your language switcher and your <head> - and never think about again.

The ones worth knowing:

getRelativeLocaleUrl(locale, path) - builds an internal link for a specific locale: /es/about. Use it for nav menus, in-content links, and the language switcher.
getAbsoluteLocaleUrl(locale, path) - same thing but fully qualified: https://example.com/es/about. Use it for canonical URLs, hreflang tags, and anywhere a string URL leaves your site.
getRelativeLocaleUrlList(path) - returns the same path mapped across every configured locale. Built for language switchers.
getAbsoluteLocaleUrlList(path) - same, fully qualified. Built for hreflang generation.
getPathByLocale(locale) and getLocaleByPath(path) - convert between locales and their URL paths. Useful when you've configured locales with custom path values.

On the request side, Astro exposes two locale values automatically:

Astro.currentLocale - the locale resolved from the current URL, based on your i18n config.
Astro.preferredLocale - the visitor's preferred locale, derived from the Accept-Language header and matched against your configured locales.

A minimal language switcher built on these primitives:

---
// src/components/LanguageSwitcher.astro

import { getRelativeLocaleUrlList } from 'astro:i18n'

const currentLocale = Astro.currentLocale ?? 'en'
const localeUrls = getRelativeLocaleUrlList(Astro.url.pathname)

const labels: Record<string, string> = {
  en: 'English',
  es: 'Español',
  de: 'Deutsch',
  ja: '日本語',
}
---

<nav aria-label="Language">
  <ul>
    {
      localeUrls.map((url) => {
        const locale = url.split('/').filter(Boolean)[0] ?? 'en'
        return (
          <li>
            <a
              href={url}
              aria-current={locale === currentLocale ? 'page' : undefined}
            >
              {labels[locale] ?? locale}
            </a>
          </li>
        )
      })
    }
  </ul>
</nav>

Notice what isn't in this list: there's no t(), no formatter, no plural rules, no message catalog. The astro:i18n module is a routing utility, not an i18n library. Once you accept that, the rest of the maturity ladder makes sense.

Browser Language Detection (and Why Not to Over-Redirect)

Astro.preferredLocale is the easiest way to detect what language the visitor's browser is asking for. It's a server-side value, derived from Accept-Language, matched against your locales. Free signal, no client-side JavaScript.

The temptation is to wire it directly to a redirect: visitor lands on /about, browser sends de, ship them to /de/about. Don't do this - at least not by default.

The visitor has not asked for German. They've followed a link. Maybe a colleague sent them a URL. Maybe they're verifying a translation. Maybe they're an English-speaking developer living in Berlin who has their browser set to German for system reasons.

Forcibly redirecting based on browser preference creates a class of UX bugs that are hard to reproduce and harder to debug - the URL the user typed is not the URL they end up on, and the reason lives inside their browser's locale settings.

The pattern that survives contact with real users: respect URL > cookie > Accept-Language, in that order. If the URL specifies a locale, that wins. If the URL is locale-neutral but the user has a saved cookie from a previous visit, that wins. Only when both are absent does the browser preference get a vote.

And even then, consider showing a banner - "We have this page in German - switch?" - instead of silently redirecting. Users are better at managing their own language preferences than your Accept-Language parser is at guessing them.

Multi-Domain SEO with `i18n.domains`

For most projects, the subdirectory model - example.com/es/about - is the right answer. But there's a specific case where you actually want each locale to live on its own fully-qualified domain: when each locale is functionally a separate site. Different country team, different content priorities, different deployment cadence.

For that case, Astro exposes i18n.domains:

// astro.config.mjs

export default defineConfig({
  site: 'https://example.com',
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'de'],
    routing: {
      prefixDefaultLocale: false,
    },
    domains: {
      es: 'https://example.es',
      de: 'https://example.de',
    },
  },
})

After this, getAbsoluteLocaleUrl('es', '/about') returns https://example.es/about instead of https://example.com/es/about. Hreflang generators, sitemaps, and canonical link tags all pick up the correct domain automatically.

Two things to know before you reach for this:

It requires a server-rendered adapter. @astrojs/node and @astrojs/vercel support domains. Static-only output doesn't, because the cross-domain URL rewriting happens at request time.
You lose subdirectory link equity. Authority and backlinks no longer pool across locales - example.es is its own SEO entity. For most multilingual sites, that's a net loss. For brands where each country site really is a different operation, it's the right structural signal.

Country-code TLDs are a step beyond i18n.domains (covered in the previous subsection on subdirectories vs subdomains) - different country team, different SEO strategy, different infrastructure. They're out of scope here.

Localized Slugs vs Canonical English Slugs

There's a recurring debate when designing multilingual URL structures: should the slug - the human-readable part of the URL after the locale prefix - be translated?

/en/blog/apple-crumble
/es/blog/apple-crumble (canonical English slug)
/es/blog/manzana-crumble (localized slug)

The case for localized slugs is mostly an SEO argument: a Spanish reader searching for "manzana crumble receta" will see /es/blog/manzana-crumble as a more relevant URL than /es/blog/apple-crumble. For long-form content where the slug literally is a search query, that effect is real.

The case against is more practical, and it adds up fast:

Percent-encoding turns clean URLs into garbage. A Cyrillic slug like българска-кухня becomes %D0%B1%D1%8A%D0%BB%D0%B3%D0%B0%D1%80%D1%81%D0%BA%D0%B0-%D0%BA%D1%83%D1%85%D0%BD%D1%8F the moment someone copies the link into a chat client. Looks suspicious to anyone reading the URL, breaks the clean aesthetic, and obscures whatever meaningful identifier was supposed to be in the path.
Cross-platform filesystem fragility. Different operating systems normalize Unicode differently (macOS NFD vs Linux/Windows NFC). Filenames like bulgarska-kuhnya.md are fine. Filenames like българска-кухня.md produce "file not found" errors in CI pipelines on platforms that disagree with your dev machine.
Architectural overhead. Translated slugs need a lookup table - българска-кухня → bulgarian-cuisine - to resolve language-switcher links. That's a route map that has to be loaded on every request, and it grows linearly with your content volume.

For EdgeKits.dev I went with canonical English slugs for everything: /en/blog/edge-native-i18n-astro-cloudflare-part-1, /de/blog/edge-native-i18n-astro-cloudflare-part-1, /ja/blog/edge-native-i18n-astro-cloudflare-part-1.

The locale prefix changes; the slug doesn't. Hreflang generation reduces to a string-replacement operation, language switchers don't need a lookup, and URLs stay copy-pasteable in any chat client.

The counterargument: for a Spanish-language recipe blog targeting a Spanish-speaking audience, localized slugs probably are worth the operational cost. For an English-first technical blog with translated coverage, they aren't.

Pick based on whether your slugs are content (where translation helps SEO) or identifiers (where stability helps everything else).

RTL Languages: A Short Note on `dir` and Logical Properties

Astro's i18n config is locale-aware but writing-direction-agnostic. If you support Arabic, Hebrew, Farsi, or Urdu, you'll need to handle the right-to-left direction yourself - and the work is mostly two lines of code plus a CSS habit.

The HTML side: set dir on <html> based on the current locale.

---
// src/layouts/BaseLayout.astro

const currentLocale = Astro.currentLocale ?? 'en'

const RTL_LOCALES = new Set(['ar', 'he', 'fa', 'ur'])
const dir = RTL_LOCALES.has(currentLocale) ? 'rtl' : 'ltr'
---

<html lang={currentLocale} dir={dir}>
  <!-- ... -->
</html>

The CSS side: use logical properties instead of physical ones. padding-inline-start instead of padding-left. margin-inline-end instead of margin-right. text-align: start instead of text-align: left. The browser flips them automatically based on dir.

.card {
  padding-inline-start: 1.5rem; /* "left" in LTR, "right" in RTL */
  border-inline-start: 2px solid var(--accent);
}

Adopt logical properties from day one and RTL support is mostly automatic. Retrofitting them onto a years-old physical-property codebase is the painful version of this work - the only reliable way through it is grinding the codebase one component at a time.

Where Native Routing Stops Helping You

We've now covered everything Astro's native i18n routing actually does: it routes URLs by locale, exposes helpers for generating those URLs, gracefully falls back when a translation is missing, optionally maps locales to separate domains, and tells you what language the current request is for.

What it doesn't do - and what every remaining level of this guide exists to handle:

It doesn't translate any text. Astro.currentLocale returns 'es'; it doesn't tell you that the Spanish word for "Subscribe" is "Suscribirse."
It doesn't manage your translated content. You still need a folder structure (Level 2), a dictionary (Level 3), or a library (Level 4) to actually map keys or files to localized output.
It has no opinion on interactivity. React Hook Form validation errors, toast messages, anything that happens after hydration - the routing layer is silent on all of it.

Native routing is necessary and rarely sufficient. Before we climb to Level 2, there's one transversal concern that affects everything we've built so far and everything we're about to build: i18n SEO - the obligations that come with making a multilingual Astro site indexable correctly.

Multilingual SEO Essentials: hreflang, Sitemap, RSS, and llms.txt

Why i18n SEO Is Its Own Discipline

Astro's i18n config gets you locale-aware URLs. Native helpers get you locale-aware links. None of that, by itself, tells search engines that /de/about is the German version of /about, that /ja/blog/post-1 should only be served when there actually is a Japanese version of post-1, or that AI agents indexing your site should treat your llms.txt one specific way regardless of how many locales you support.

What's commonly called i18n SEO sits on top of all of this. It's the part of multilingual implementation where small mistakes compound silently for months before surfacing in a Search Console report. The next subsections cover the obligations that actually matter.

`hreflang` Tags: The Non-Negotiable

The single most important multilingual SEO signal. hreflang tells Google which URLs are translations of each other and which language each one is in. Without it, you're shipping near-duplicate content to the index and asking Google to figure out the relationships on its own - which it does, badly.

The minimum viable implementation, in a layout file:

---
// src/layouts/BaseLayout.astro

import { getAbsoluteLocaleUrl } from 'astro:i18n'

const SUPPORTED_LOCALES = ['en', 'es', 'de', 'ja'] as const
const DEFAULT_LOCALE = 'en'

// Strip the locale prefix to get the underlying path
const localePattern = new RegExp(`^/(${SUPPORTED_LOCALES.join('|')})`)
const cleanPath = Astro.url.pathname.replace(localePattern, '') || '/'
---

<head>
  {
    SUPPORTED_LOCALES.map((locale) => (
      <link
        rel="alternate"
        hreflang={locale}
        href={getAbsoluteLocaleUrl(locale, cleanPath)}
      />
    ))
  }
  <link
    rel="alternate"
    hreflang="x-default"
    href={getAbsoluteLocaleUrl(DEFAULT_LOCALE, cleanPath)}
  />
</head>

Two things this snippet gets right out of the box: it includes an x-default tag (the locale Google should serve when the user's language is something you don't support), and it generates one alternate per configured locale. The pattern works for sites where every page exists in every locale.

It breaks as soon as your site has partial translations.

Don't Lie About Translations That Don't Exist

If your site translates UI strings into German but your blog posts are English-only, the naive hreflang implementation tells Google that /de/blog/post-1 is the German version of post-1.

Google crawls that URL, gets back a page that's mostly in English (with German nav and footer), and starts asking awkward questions in your indexing reports.

The pattern that actually works: emit hreflang tags only for locales that have translated content for the current page, and mark fallback pages as noindex.

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

import { getCollection } from 'astro:content'
import BaseLayout from '@/layouts/BaseLayout.astro'

const { lang, slug } = Astro.params

// Find which locales actually have a translation for this slug
const allPosts = await getCollection('blog')
const translations = allPosts.filter((p) => {
  const [, ...rest] = p.id.split('/')
  return rest.join('/') === slug
})
const translatedLocales = translations.map((p) => p.id.split('/')[0])

// Are we rendering a fallback (this locale has no translation)?
const isFallback = !translatedLocales.includes(lang!)

// `post` is fetched separately with the fallback chain shown in Level 2.
---

<BaseLayout
  title={post.data.title}
  altLocales={translatedLocales}
  noindex={isFallback}
>
  <!-- ... -->
</BaseLayout>

BaseLayout then uses altLocales to emit hreflang only for the translations that exist, and noindex to keep fallback pages out of the index. Google sees a coherent map of what's actually translated, and stops indexing pages that lie about their language.

Canonical URLs Per Locale

hreflang tags tell search engines about translations. canonical tells them which URL is the source of truth for the current page. Every locale needs its own canonical pointing at itself:

<link rel="canonical" href={new URL(Astro.url.pathname, Astro.site)} />

That's the entire pattern. The Spanish version of a page should canonical to itself, not to the English version. Pointing every locale's canonical to English is one of the more common multilingual-Astro mistakes I've seen in the wild - it quietly deindexes every translation you've shipped.

Use 301 (Not 302) for Every Locale Redirect

Native i18n routing - and any custom middleware doing locale fallback - generates redirects on a few predictable paths: a request without a locale prefix gets bounced to /en/, an unsupported locale gets normalized to the default, an old URL shape gets normalized to the canonical one. Every one of these has to be a 301 (permanent), never a 302 (temporary).

Two failure modes follow from getting this wrong:

Search Console treats 302 as "the original URL is canonical." A 302 from /about to /en/about tells Google /about is the real page and /en/about is a temporary alias. Your canonical tags point one way, your redirects point the other, and the index fragments. 301 is the only status code that consolidates the signal.
Catch-all handlers responding 200 instead of 301-or-404 produce soft 404s and indexable URL spam. If /asdfsdf (a path nothing maps to) returns 200 OK with a rendered fallback page rather than 301 to a real page or 404 to nowhere, Google indexes a flood of nonsense URLs. This is the most common form of indexable URL noise on multilingual sites - usually caused by overly permissive locale-prefix handling that tries to "be helpful" instead of returning a hard signal.

If you're writing locale-prefix middleware, make every redirect() call pass 301 explicitly. Don't rely on framework defaults. The middleware in EdgeKits Core uses 301 on every fallback path; the pattern looks like:

// Always 301 - never let the default leak through
return context.redirect(buildLocalizedPath(fallbackLocale, []), 301)

For paths that don't exist at all, return a real 404 rather than redirecting to a fallback locale's homepage. Soft 404s look like 200s to Google, and Google believes them.

The Trailing-Slash Trap

Here's a footgun I personally walked into. Three months in, I'm still negotiating with Google in Search Console about which URL is canonical on a handful of my secondary pages. The trap applies to any Astro site; multilingual ones take the worst of it. Worth covering before we touch sitemaps and RSS.

I had trailingSlash: 'ignore' in my Astro config - deliberately, because my middleware already canonicalizes URLs in a single redirect (locale prefix, trailing slash, normalized structure all in one hop), and trailingSlash: 'always' would have added a redundant second redirect on top.

That part of the setup was correct. The mistake lived elsewhere: I let individual components compose URLs by hand instead of routing every internal link through a single helper. Different components ended up emitting different conventions - some with trailing slashes (/ja/legal/), some without (/ja/legal). Both versions resolved correctly at runtime, so nothing visibly broke during development.

What did break was Google. Both versions got indexed. Then Google started disagreeing with me about which one was canonical, on a per-page basis, in ways I couldn't predict. Some pages settled on the slash version, some on the no-slash version, some kept flipping. Three months of "URL is not canonical" warnings in Search Console for what was supposed to be a clean multilingual site.

The lesson, applicable to any Astro site:

One source of truth for URL canonicalization - and don't let it fight your middleware. Astro's trailingSlash: 'always' (or 'never') handles canonicalization for you, at the cost of an extra redirect hop. If your middleware is already doing locale-aware redirects (cookie sync, locale resolution, soft-404 handling), 'ignore' plus a normalization step in middleware is often the cleaner pick - one redirect, one canonical form. What does not work is any trailingSlash setting combined with components that compose URLs by hand without going through a shared helper.
Build every URL through a single helper. Whether that's astro:i18n's getRelativeLocaleUrl, a thin wrapper around it, or your own utility, a single chokepoint guarantees one canonical form for every link. This is the discipline that saves you, regardless of which trailingSlash mode you picked.
Force the slash in your canonical helper. Even if a path comes in without one, append it before emitting the canonical link. Otherwise you re-export the inconsistency at the SEO layer.

A minimal canonical helper that survives this class of bug:

// src/lib/seo.ts

export function buildCanonicalUrl(path: string, siteOrigin: string): string {
  // Strip query parameters
  let cleanPath = path.split('?')[0] ?? ''
  // Force trailing slash
  if (!cleanPath.endsWith('/')) cleanPath += '/'
  // Avoid double slashes if origin has a trailing one
  return `${siteOrigin.replace(/\/$/, '')}${cleanPath}`
}

Three lines of discipline that would have saved me a quarter.

The Multilingual Sitemap

A sitemap tells search engines which URLs exist and how to reach them. For a multilingual site, that means listing every URL in every supported locale - not just the default one - and ideally cross-linking translations via <xhtml:link rel="alternate"> entries.

The minimum-effort option is @astrojs/sitemap with the i18n config:

// astro.config.mjs

import { defineConfig } from 'astro/config'
import sitemap from '@astrojs/sitemap'

export default defineConfig({
  site: 'https://example.com',
  integrations: [
    sitemap({
      i18n: {
        defaultLocale: 'en',
        locales: {
          en: 'en-US',
          es: 'es-ES',
          de: 'de-DE',
          ja: 'ja-JP',
        },
      },
    }),
  ],
})

This generates a sitemap with locale-tagged entries and alternate links between translations. It works well when every page exists in every locale.

For sites where translations are partial - some posts in English only, some translated, some content-fallback - the integration starts producing noisy or incorrect output: alternate links to non-existent pages, sitemap entries for URLs that fall back to a different locale's content.

At that point the cleanest fix is a custom sitemap endpoint that walks your collections and emits only the URLs that actually exist.

Multilingual RSS: A Briefly Overlooked Detail

RSS gets less attention in 2026 than it deserves - it's how AI summarizers, podcast players, content aggregators, and a meaningful slice of your power readers actually consume your blog.

The choice for multilingual sites is one feed per locale (/en/rss.xml, /de/rss.xml) versus a single feed with xml:lang tagged on each item. One-feed-per-locale is the more compatible option: every RSS reader handles it cleanly, and subscribers self-select their language by which URL they subscribe to.

A minimal locale-scoped RSS endpoint with @astrojs/rss:

// src/pages/[lang]/rss.xml.ts

import rss from '@astrojs/rss'
import { getCollection } from 'astro:content'
import type { APIContext } from 'astro'

export async function GET(context: APIContext) {
  const lang = context.params.lang!
  const posts = await getCollection('blog', (post) =>
    post.id.startsWith(`${lang}/`)
  )

  return rss({
    title: `My Blog (${lang.toUpperCase()})`,
    description: 'Latest articles in this language',
    site: context.site!,
    items: posts.map((post) => {
      const cleanSlug = post.id.split('/').slice(1).join('/')
      return {
        title: post.data.title,
        pubDate: post.data.pubDate,
        description: post.data.description,
        link: `/${lang}/blog/${cleanSlug}/`,
      }
    }),
  })
}

Then reference each locale's feed with a <link rel="alternate" type="application/rss+xml"> tag in your layout, scoped to the current locale. Subscribers stay in their language; aggregators get a clean per-locale stream.

`llms.txt`: The One File Where i18n Doesn't Belong

To provide LLMs with a concise summary of your site, the llms.txt proposal suggests using a standard /llms.txt path. AI agents fetch it to get a high-level map of what your site is and
where the important content lives.

The interesting question for a multilingual site: do you serve llms.txt per locale (/en/llms.txt, /de/llms.txt), or one file at the root?

The clean answer is one file, English, at the root. There's no reason to localize llms.txt, and several reasons not to.

AI agents already translate. A German-language query against an English llms.txt costs the agent nothing - modern LLMs handle cross-language summarization natively. There's no comprehension gap to bridge.
The agent doesn't follow Accept-Language the way browsers do. llms.txt is a meta-document, not user-facing content. The locale-detection pipeline doesn't apply to it.
Maintenance cost multiplies for negligible gain. Every product description, every blog post summary, every section header now needs to stay in sync across N locales. The first time a translation lags, the agent's mental map of your site fragments.
Your real content is still localized. llms.txt points to your real pages, which can be in whatever locale the agent (or its user) needs. Locale-routing happens at the destination, not at the index.

A minimal llms.txt endpoint generates from your default-locale blog collection plus your project metadata:

// src/pages/llms.txt.ts

import { getCollection } from 'astro:content'
import type { APIContext } from 'astro'

const SITE_NAME = 'My Project'
const SITE_DESCRIPTION = 'Edge-native developer tools'
const DEFAULT_LOCALE = 'en'

export async function GET(context: APIContext) {
  const posts = await getCollection('blog')
  const recent = posts
    .filter((p) => p.id.startsWith(`${DEFAULT_LOCALE}/`))
    .sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf())
    .slice(0, 10)

  let body = `# ${SITE_NAME}\n\n> ${SITE_DESCRIPTION}\n\n## Recent Articles\n\n`
  for (const post of recent) {
    const cleanSlug = post.id.split('/').slice(1).join('/')
    body += `- [${post.data.title}](${context.site}${DEFAULT_LOCALE}/blog/${cleanSlug}/)\n`
    body += `  ${post.data.description}\n`
  }

  return new Response(body, {
    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
  })
}

One file, one language, zero locale-detection logic. The simplest part of your SEO surface in a multilingual setup.

When Standard Plugins Stop Working

Most of what we've covered so far works with @astrojs/sitemap, @astrojs/rss, and a layout that emits hreflang for every configured locale. That's enough for sites where every page exists in every locale and your URL structure is uniform.

As soon as any of those assumptions stops holding - partial translations, content-fallback rendering (the user's UI is in Spanish, but this specific blog post is only available in English), distinct UI and content locales - the standard integrations start producing wrong output.

They emit alternate URLs for non-existent translations. They list sitemap entries for pages that fall back. They put fallback content into the wrong-language RSS feed.

For EdgeKits.dev I ended up writing custom sitemap, RSS, and llms.txt endpoints that walk the actual content collections, check whether each translation exists, and only emit entries for pages that actually exist in the requested locale.

They sit alongside an altLocales-aware SeoHreflangs component and a NoIndex companion that fires whenever a content fallback kicks in.

The full implementations are open-source in the EdgeKits Core repo, and the architectural reasoning behind the UI/content locale split that necessitates them is covered in Part 1 of the Edge-Native i18n series (linked in the Where the Full Implementation Lives chapter below).

The principle generalizes even if my specific implementation is opinionated: as soon as your multilingual setup stops being uniform, your SEO components have to reason about your actual content shape, not about your config file.

Level 2 - Localizing Content with Astro Content Collections

For full-page content - blog posts, documentation, MDX articles, long-form marketing copy - the right answer is Astro Content Collections. They're the type-safe, build-aware Astro primitive for managing collections of documents, and they have native conventions for handling locale variants.

If You're Building Documentation, Use Starlight

If your content is documentation, stop reading this section and use Starlight. It's Astro's documentation theme, ships with i18n built-in (locale-prefixed routing, sidebar translation, language switcher, fallback handling), and configuration is essentially pasting your locale codes into a config object.

For most projects, there's no payoff in hand-rolling docs i18n on Content Collections compared to using Starlight directly.

For everything else - blogs, marketing pages, MDX articles outside a docs site - keep going.

Folder Layout

Two conventions, both supported:

Per-locale subdirectories. One folder per locale inside the collection. Easiest to track which posts have which translations at a glance:

src/content/blog/
├── en/
│   ├── post-1.mdx
│   └── post-2.mdx
├── es/
│   └── post-1.mdx
└── de/
    └── post-1.mdx

Flat with a lang field. All posts in one folder, locale lives in the filename or in frontmatter:

src/content/blog/
├── post-1.en.mdx
├── post-1.es.mdx
├── post-1.de.mdx
└── post-2.en.mdx

The subdirectory convention is the default I'd recommend - visually obvious which posts have a German translation and which don't. The flat convention works for tightly translated sites where every post exists in every locale.

Schema with Zod and the Content Layer

Define the collection in src/content.config.ts. The Content Layer API (Astro 5+) uses a loader plus a Zod schema:

// src/content.config.ts

import { defineCollection, z } from 'astro:content'
import { glob } from 'astro/loaders'

const blog = defineCollection({
  loader: glob({ pattern: '**/*.{md,mdx}', base: './src/content/blog' }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    tags: z.array(z.string()).default([]),
    heroImage: z.string().optional(),
  }),
})

export const collections = { blog }

A typo in pubDate fails the build with a precise error pointing at the file. Type-safety is one of those Astro features that doesn't sound exciting until you've debugged a multilingual content tree without it.

Dynamic Routing with `getStaticPaths`

A single dynamic route handles every (locale, slug) combination:

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

import { getCollection, render } from 'astro:content'

export async function getStaticPaths() {
  const allPosts = await getCollection('blog')

  return allPosts.map((post) => {
    const [lang, ...slugParts] = post.id.split('/')
    return {
      params: { lang, slug: slugParts.join('/') || undefined },
      props: { post },
    }
  })
}

const { post } = Astro.props
const { Content } = await render(post)
---

<html lang={post.id.split('/')[0]}>
  <h1>{post.data.title}</h1>
  <Content />
</html>

For server-rendered (`output: 'server'`) projects, the equivalent is fetching directly via `getEntry('blog', `${lang}/${slug}`)` inside the page handler.

When a reader hits /es/blog/post-3 and no Spanish version exists, the right pattern is graceful fallback - try the requested locale, fall back to the default, mark the rendered fallback page noindex (covered in the SEO section above). The wrong pattern is silently 404-ing.

Plugging Content Collections into a Headless CMS

Content Collections aren't married to local Markdown files. The Content Layer API supports custom loaders that fetch from Sanity, Contentful, Strapi, or any external CMS:

import { defineCollection, z } from 'astro:content'

const blog = defineCollection({
  loader: async () => {
    const res = await fetch('https://your-cms.example/api/posts')
    const posts = await res.json()
    return posts.map((post: any) => ({
      id: `${post.locale}/${post.slug}`,
      ...post,
    }))
  },
  schema: z.object({
    /* ... */
  }),
})

Your content team edits in a polished CMS UI, your Astro build pulls translations on the fly, and the workflow looks clean from every angle.

There's a footnote.

The "No-Deploy Updates" Half-Truth

Most CMS-integration tutorials present this setup as "translators can update content without a developer running a deploy." That's true for the translator's experience - they click Save and walk away. It's not true for your infrastructure.

Content Collections are a build-time primitive. Data is collected, validated, and frozen during astro build. For new content to appear on the live site, the build has to run again. Your CMS integration handles this by firing a webhook on every save, which triggers your CI pipeline to redeploy the entire site.

This works fine when content edits are infrequent. It works less fine when a content team starts iterating: 30 typo fixes during a launch, 50 small copy tweaks for a campaign, every save triggering a 90-second build, builds queueing up, the next deploy landing 8 minutes after the edit. The "no-deploy updates" pitch hides what is in fact a deploy treadmill.

We come back to this in Level 6 - it's one of the architectural walls that pushes serious multilingual sites toward runtime translation storage.

Level 3 - Localizing the UI: The Official `ui.ts` Recipe

Astro has an officially-recommended pattern for UI strings - button labels, error messages, navigation copy, microcopy - and it isn't an npm package. It's a hand-written TypeScript module: a dictionary plus two utility functions. Most projects can ship a multilingual UI on this pattern and never need anything else.

Why It's Not From a Library

A recurring confusion when reading Astro i18n tutorials is that examples freely reference useTranslations as if it were imported from somewhere. It isn't. The official Astro i18n recipe has you write useTranslations yourself, in about ten lines of TypeScript. There's no @astro/i18n package to install. That's the whole point - Astro's position is that for UI strings, you don't need a runtime library; you need a typed object and a key lookup.

If you've been searching npm for useTranslations and finding nothing, this is why.

`ui.ts` - A Type-Safe Dictionary as a Module

Create the dictionary as a const object. The as const assertion is what gives you autocomplete on translation keys:

// src/i18n/ui.ts

export const defaultLang = 'en'

export const languages = {
  en: 'English',
  es: 'Español',
  de: 'Deutsch',
  ja: '日本語',
} as const

export const ui = {
  en: {
    'nav.home': 'Home',
    'nav.about': 'About',
    'cta.subscribe': 'Subscribe',
    'error.invalid_email': 'Invalid email',
  },
  es: {
    'nav.home': 'Inicio',
    'nav.about': 'Acerca de',
    'cta.subscribe': 'Suscribirse',
    'error.invalid_email': 'Email no válido',
  },
  de: {
    'nav.home': 'Startseite',
    'nav.about': 'Über',
    'cta.subscribe': 'Abonnieren',
    // 'error.invalid_email' intentionally missing - falls back to English at runtime
  },
} as const

The dot-notation key style (nav.home rather than nested objects) is a flat-key convention that simplifies type derivation; deeply nested objects work too if you prefer. The de locale is intentionally missing one key here to demonstrate fallback - the helper below handles it.

`useTranslations(lang)` and `getLangFromUrl(url)`

Two helpers, in src/i18n/utils.ts:

// src/i18n/utils.ts

import { ui, defaultLang } from './ui'

export function getLangFromUrl(url: URL): keyof typeof ui {
  const [, lang] = url.pathname.split('/')
  return lang && lang in ui ? (lang as keyof typeof ui) : defaultLang
}

export function useTranslations(lang: keyof typeof ui) {
  return function t(key: keyof (typeof ui)[typeof defaultLang]): string {
    return (ui[lang] as Record<string, string>)[key] ?? ui[defaultLang][key]
  }
}

getLangFromUrl parses the locale from the URL path. useTranslations returns a t() function that looks up a key in the requested locale and falls back to the default if missing. That's the entire library.

Using It in `.astro` Pages and Layouts

In any .astro file:

---
import { getLangFromUrl, useTranslations } from '@/i18n/utils'

const lang = getLangFromUrl(Astro.url)
const t = useTranslations(lang)
---

<nav>
  <a href={`/${lang}/`}>{t('nav.home')}</a>
  <a href={`/${lang}/about/`}>{t('nav.about')}</a>
</nav>

<button>{t('cta.subscribe')}</button>

That's it. SSR-rendered, no client JavaScript, full type safety on the key. Mistype t('nav.hom') and the build fails. Delete nav.home from the dictionary and every callsite turns red in your editor.

You can swap getLangFromUrl for Astro.currentLocale, since the native i18n routing already exposes the resolved locale - they're equivalent for any URL the routing layer knows about.

Where the Recipe Stops Scaling

The pattern is excellent up to a point. The point looks something like this:

Interpolation. You want Welcome back, {name}! with safe variable substitution. Doable as a fmt() helper - but it's more code you write.
Plurals. 1 item vs 5 items, with rules that differ per language. Intl.PluralRules solves it, with more infrastructure.
Namespaces. A dictionary that started at 50 keys becomes 500. Splitting it into common.json, landing.json, dashboard.json with per-page loading is doable but means writing a loader.
React Islands. An interactive form needs translations on the client. You either prop-drill the dictionary in (heavy) or refactor toward selective string passing (lighter, more boilerplate).
Editing without a deploy. The dictionary lives in src/, so every typo fix is a deploy.

Each of these is solvable with bespoke code. At some volume of solving, you've effectively rebuilt a small i18n library - and that's the moment to look at what already exists.

The next level surveys what already exists.

Level 4 - The Library Landscape: Candid Tour

When the recipe pattern from Level 3 stops covering your needs, you reach for a library. The Astro i18n library ecosystem in 2026 has roughly five names worth knowing - three of them are alive (with varying maintenance pulses), two have effectively gone quiet, and only one is actively the right answer for most new projects.

How to Read This Section

Each library here answers a version of the same question - "what if ui.ts isn't enough?" - but the answers vary on dimensions that matter:

Where the translations end up. In your client bundle? In your server bundle? Loaded dynamically at runtime?
Whether tree-shaking actually removes unused strings. Some libraries claim it; some deliver it.
How updates ship. Compiled into code (deploy required) vs loaded as data (no deploy).
Maintenance pulse. Recent releases, active issues, alignment with current Astro versions.

Each block below covers one library against those dimensions, ends with a short verdict, and a side-by-side table closes the section.

Paraglide JS (Inlang)

Paraglide JS is the i18n library most worth knowing in 2026. It's compiler-based: at build time, your translation JSON files compile into individual TypeScript message functions, one per key.

Your bundler (Vite, in Astro's case) then tree-shakes the ones you don't use out of the client output.

The result is a client bundle that contains exactly the strings the page renders - usually a few KB instead of tens of KB.

Setup on Paraglide v2 (no Astro adapter package required - v2 ships everything in @inlang/paraglide-js):

// astro.config.mjs

import { defineConfig } from 'astro/config'
import { paraglideVitePlugin } from '@inlang/paraglide-js'

export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'de'],
  },
  vite: {
    plugins: [
      paraglideVitePlugin({
        project: './project.inlang',
        outdir: './src/paraglide',
      }),
    ],
  },
})

Translations live as JSON in the inlang project directory:

// messages/en.json

{
  "greeting": "Hello, {name}!",
  "subscribe_button": "Subscribe"
}

Usage in components:

---
import * as m from '@/paraglide/messages'
---

<h1>{m.greeting({ name: 'Gary' })}</h1>
<button>{m.subscribe_button()}</button>

Each message is a typed function. Mistype m.greting and the build fails. Forget the name parameter and the build fails. Update en.json and the type for m.greeting's parameter regenerates automatically.

The good. Strongest client tree-shaking of any current Astro i18n library. Type-safe message functions across the whole stack. Native interpolation, native plurals via the JSON message format, namespaces via JSON file organization. Active development, frequent releases, single-package install in v2.

The footnote. Tree-shaking saves the client bundle, not the server bundle. On the server (or the Worker), the compiled code still has to be loaded into memory for SSR to call any message function. With many locales and many namespaces, that cost adds up - your server bundle grows even as your client bundle stays lean. We come back to this in Level 6.

Verdict. If you've outgrown the ui.ts recipe, Paraglide is the default answer. It's the closest thing in 2026 to a "use this and don't think about i18n again" choice for the UI layer.

`astro-i18next` (yassinedoghri)

astro-i18next was the most popular Astro i18n library through 2023. It's a thin Astro wrapper around the i18next ecosystem - runtime-loaded JSON dictionaries, full i18next plugin compatibility, generated translated routes.

Verdict in 2026: archived in practice. The last published version is 1.0.0-beta.21, released in March 2023 - over three years ago at the time of this writing. The repository has accumulated open issues against newer Astro versions without responses.

Don't start a new project on it. If you're maintaining a project that already uses it, the migration paths are either Paraglide (smaller client bundle, fewer dependencies) or hand-rolling the recipe pattern from Level 3 (zero dependencies, full control).

astro-i18next still ranks highly for "Astro i18n" searches, which is part of why it's worth covering - readers who land on it from old tutorials should know it's no longer the right answer.

`astro-i18n-aut` (jlarmstrongiv)

astro-i18n-aut takes a different approach: it auto-generates locale-prefixed routes for static sites without using middleware. You configure your locales and the integration creates /es/about, /de/about, etc. as build artifacts, no [locale] dynamic routes required.

The library is alive but quiet - current version 0.7.3, last released at the start of 2025. Maintained, but not under active feature development.

Use case. Strictly static (SSG-only) sites where you can't or don't want to use middleware, and where you want a simpler routing model than Astro's native dynamic-route pattern.

For sites that already use middleware (locale detection, custom redirects, server-rendered pages), there's no reason to reach for this - native i18n routing covers what astro-i18n-aut does with more flexibility.

`astro-i18n` (Alexandre-Fernandez)

A separate, less-known TypeScript-first runtime library by Alexandre Fernandez - astro-i18n, not to be confused with yassinedoghri's astro-i18next.

Current version 2.2.4, last released in January 2024 - over two years ago at the time of writing. Provides namespaced translations, interpolation, plurals via runtime API, and dedicated CLI tooling.

Verdict. Two-plus years without a release puts this in the same "use at your own risk" bucket as astro-i18next - the API ergonomics are different (TypeScript-first, more elegant runtime), but the maintenance pulse is similarly thin. If you're already running it on a stable Astro version, fine. For new projects, Paraglide is the cleaner pick.

`@astrolicious/i18n`

@astrolicious/i18n is a third-party integration that bundles its own routing layer, translated paths (different slugs per locale), and translation utilities. Worth mentioning because it surfaces in some search results.

Caveat. It's incompatible with Astro's native i18n routing - you pick one or the other, and most of this article's foundation work assumes you're on the native one. Useful in projects where translated slugs are non-negotiable; otherwise not the right starting point in 2026.

Side-by-Side: How They Compare

Library	Client bundle	Server bundle	Type-safe keys	Interpolation / plurals	Namespaces	Runtime updates	Maintained (2026)
Paraglide JS	Tree-shaken (lean)	Compiled in (grows)	✅ Generated functions	✅ Native JSON format	✅ JSON files	❌ Build required	✅ Active
`astro-i18next`	Runtime JSON	Runtime JSON	⚠️ Loose (string keys)	✅ via i18next	✅ via i18next	⚠️ Limited	❌ Archived (2023)
`astro-i18n-aut`	Compiled into pages	n/a (SSG)	⚠️ Loose	⚠️ Basic	⚠️ File-based	❌ Build required	⚪ Quiet
`astro-i18n` (Fernandez)	Runtime JSON	Runtime JSON	✅ Generated types	✅ Built-in	✅ Native	⚠️ Limited	❌ Inactive (2024)
`@astrolicious/i18n`	Runtime + routing	Runtime + routing	✅ Generated types	✅ Built-in	✅ Native	⚠️ Limited	⚪ Maintained
Hand-rolled `ui.ts`	Compiled in (grows)	Compiled in (grows)	✅ via `as const`	❌ Roll your own	⚠️ Roll your own	❌ Build required	n/a

The pattern across the table: every library here is fundamentally a build-time solution. Translations end up baked into either the client bundle, the server bundle, or both. None of them solves the "translators edit, no deploy fires" problem - for that you need a different architecture entirely.

That's the bridge to Level 5 (where forms expose another set of bundle-bloat tradeoffs) and Level 6 (where every library on this table hits the same architectural ceiling).

Level 5 - The Form Problem: Zod, RHF, and Why You're Shipping Your Dictionary

Forms are where every i18n library quietly fails. The moment you wire up Zod + React Hook Form for client-side validation, the temptation is to put translated error messages directly in the schema. That one decision drags your entire dictionary into the client bundle - regardless of which library from Level 4 you picked.

There's a pattern that survives this, and it works on top of any of the L3/L4 stacks.

The Anti-Pattern

The natural-looking version is the one most tutorials show:

// validation.ts - anti-pattern
import { z } from 'zod'
import { t } from '@/i18n/utils'

export const newsletterSchema = z.object({
  email: z.email({ error: t('error.invalid_email') }),
  name: z.string().min(2, { error: t('error.name_too_short') }),
})

Looks clean. The schema works on the server and on the client; translations are in the right place. The problem is timing: t('error.invalid_email') resolves when the schema is constructed, and for live client-side validation the schema has to be constructed in the browser.

So the entire error portion of your dictionary ships to the client too. Tree-shaking can't help - every error string is reachable from the validation entry point.

Domain Error Codes - Validation Returns Contracts, Not Prose

The pattern that keeps the dictionary out of the client: have Zod return codes, not prose. The schema speaks in domain terms (INVALID_EMAIL, NAME_TOO_SHORT), and translation happens later, at the rendering boundary.

// src/lib/validation.ts (Zod 4 syntax)

import { z } from 'zod'

export const newsletterSchema = z.object({
  email: z.email({ error: 'INVALID_EMAIL' }),
  name: z
    .string()
    .min(2, { error: 'NAME_TOO_SHORT' })
    .max(50, { error: 'NAME_TOO_LONG' }),
})

export type NewsletterInput = z.infer<typeof newsletterSchema>

This schema imports nothing from the i18n layer. It's reusable on the server, on the client, and in any test runner - and it ships zero translation code to the browser.

Translate at the Render Boundary

The translation happens at the render boundary. The component that displays the error converts the code to a localized string using a small translation map specific to that form's vocabulary, passed in as a prop.

The form's render layer is the only place in the entire stack that needs to know what INVALID_EMAIL says in Spanish. (The dedicated Edge-Native i18n series on edgekits.dev - linked in Resources & Further Reading below - calls this same idea Final Mile Localization, and goes deeper into the React Hook Form integration in Part 2.)

Astro Action + React Hook Form

The React island that renders the form:

// src/components/islands/NewsletterForm.tsx

import { useForm } from 'react-hook-form'
import { zodResolver } from '@hookform/resolvers/zod'
import { actions } from 'astro:actions'

import { newsletterSchema, type NewsletterInput } from '@/lib/validation'

interface FormStrings {
  email_label: string
  name_label: string
  submit: string
  errors: Record<string, string> // localized map, keyed by code
}

export function NewsletterForm({ t }: { t: FormStrings }) {
  const {
    register,
    handleSubmit,
    setError,
    formState: { errors },
  } = useForm<NewsletterInput>({
    resolver: zodResolver(newsletterSchema),
    mode: 'onBlur',
  })

  const localize = (code?: string) => (code ? (t.errors[code] ?? code) : '')

  const onSubmit = async (data: NewsletterInput) => {
    const { error } = await actions.newsletter(data)
    if (!error) return

    // Domain errors thrown as ActionError carry the code in error.message.
    // (Zod input-validation errors arrive on `error.fields` - usually
    //  caught client-side by zodResolver before reaching the network.)
    if (error.code === 'BAD_REQUEST') {
      setError('email', { message: error.message })
    }
  }

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <label>
        {t.email_label}
        <input {...register('email')} />
        {errors.email && <p>{localize(errors.email.message)}</p>}
      </label>

      <label>
        {t.name_label}
        <input {...register('name')} />
        {errors.name && <p>{localize(errors.name.message)}</p>}
      </label>

      <button type='submit'>{t.submit}</button>
    </form>
  )
}

The wrapping .astro component builds t on the server and injects it as a prop:

---
// src/components/forms/NewsletterFormWrapper.astro

import { getLangFromUrl, useTranslations } from '@/i18n/utils'
import { NewsletterForm } from './islands/NewsletterForm'

const lang = getLangFromUrl(Astro.url)
const tr = useTranslations(lang)

const formStrings = {
  email_label: tr('form.email_label'),
  name_label: tr('form.name_label'),
  submit: tr('form.submit'),
  errors: {
    INVALID_EMAIL: tr('error.invalid_email'),
    NAME_TOO_SHORT: tr('error.name_too_short'),
    NAME_TOO_LONG: tr('error.name_too_long'),
    EMAIL_ALREADY_REGISTERED: tr('error.email_already_registered'),
  },
}
---

<NewsletterForm client:load t={formStrings} />

The Astro Action on the server validates with the same schema and returns codes, never prose:

// src/actions/index.ts

import { defineAction, ActionError } from 'astro:actions'
import { newsletterSchema } from '@/lib/validation'

export const server = {
  newsletter: defineAction({
    accept: 'form',
    input: newsletterSchema,
    handler: async ({ email, name }) => {
      if (await emailExists(email)) {
        // Throw, don't return - Astro Actions only routes thrown
        // ActionErrors to `error` on the client; returned values go to `data`.
        throw new ActionError({
          code: 'BAD_REQUEST',
          message: 'EMAIL_ALREADY_REGISTERED',
        })
      }
      // ... persist, send confirmation, etc.
      return { ok: true }
    },
  }),
}

Server errors travel back as codes; the client's localize() map handles them identically to Zod's local validation errors. One vocabulary, one translation point, no dictionary in the bundle.

Why This Pattern Is Stack-Agnostic

Nothing in this pattern depends on which translation system you use. The Astro wrapper here builds formStrings from useTranslations (ui.ts), but m.error_invalid_email() from Paraglide, or await fetchTranslations(...) from a KV runtime (Level 7), would slot into the same place identically.

The schema speaks codes, the wrapper converts codes to strings, the island renders them. Whatever sits behind the wrapper is invisible to the form.

Form i18n is a boundary problem. Once you solve it as a boundary problem, the choice of underlying library stops mattering.

Level 6 - The Glass Ceiling: Where Bundled Approaches Eventually Break

We've spent five levels treating translations as code. That choice has a ceiling. Every library on the table in Level 4 hits the same ceiling at scale; the only differences are which side of the ceiling you hit first, and how loudly.

Four walls separate "this scales" from "this doesn't." If your project is going to hit any of them within the next 12 months, the rest of this guide is the exit.

Wall 1 - Build-Time Updates as a Deployment Treadmill

We touched this in Level 2's CMS half-truth. The full picture: every translation update - typo fix, A/B copy test, marketing tweak - fires a webhook, queues a CI build, runs the full pipeline, and ships a deploy.

A 90-second build per save sounds fine until a content team starts iterating, at which point you're blocking real-feature deploys behind the next round of "could you add a comma?" rebuilds.

The pleasant "translators ship without developers" pitch is, in infrastructure terms, a rebuild treadmill.

Wall 2 - The Server Bundle Trap

Every library in Level 4 - including Paraglide with its compiler tree-shaking - bakes the full translation set into the server bundle.

Tree-shaking saves the client; the server still has to load every message function for SSR.

Every serverless platform sets a hard ceiling on the size of the deployed function - typically a few megabytes after compression - and translations end up competing with your business logic for that budget.

Eight locales × three namespaces × 60 KB of translations is roughly 1.4 MB of pure text inside your function.

As the locale count grows, the cost shows up first as longer cold starts, then as deploy failures when the platform ceiling is reached.

Wall 3 - The Dynamic Content Gap

Static-time tools localize what's in your repository. They don't localize what's in your database. User-generated content, dynamic product descriptions, customer-submitted reviews - none of it goes through the i18n compiler.

If you build a SaaS that has both a marketing site and a UGC layer, you end up maintaining two i18n systems: one for the UI (compiled code) and one for the data (database columns or a translation service). The two share nothing and drift over time.

Wall 4 - The HTML Payload Trade-Off

Flagging this in advance because it's the cost of the architecture we're about to recommend, not the one we're leaving.

If you move translations off the JavaScript bundle and inject them into the HTML at SSR time (which is what Level 7 does), the HTML response grows to hold what the JS used to hold.

That's a real trade-off - mitigated by namespace splitting (load only what each page needs), not eliminated. We're explicit about it when we get there.

Self-Diagnosis Checklist

Pick the level that fits your current shape. Climb only when one of these symptoms applies:

Translation edits cost you a deploy more often than once a week
Your server bundle is over 1 MB and a non-trivial fraction is translation text
Adding a locale measurably slows your cold start
You support more than ~5 locales and namespace count is still growing
User-generated content needs to be localized as well

Zero symptoms: stay where you are. One or two: start watching the metric. Three or more: the next level is the right level.

Level 7 - Edge-Native i18n: Translations as Runtime Data

The exit from the four walls is to stop treating translations as something you ship inside your code. Translations are data: edited like data, stored like data, served like data, on a release cadence that has nothing to do with code deployments.

The umbrella term I use for this pattern is edge-native i18n - translations stored at the edge, fetched at request time, injected into the rendered HTML.

One disclosure before we go deeper. The implementation below is built on Cloudflare specifically (Workers + KV + Cache API), because that's my production stack and the platform I've shipped this on.

Equivalent primitives exist on Vercel (Edge Config, KV), Deno (Deno KV), Netlify (Blobs), and elsewhere - the architectural pattern translates, the specific bindings don't. If you're not on Cloudflare, read the rest of this section as the shape of the solution rather than a copy-paste blueprint.

The full code - middleware, KV fetcher, build-time scripts, the React Islands handoff - and the architectural reasoning behind every choice are documented in a separate three-part Edge-Native i18n series on edgekits.dev.

All links live in the Where the Full Implementation Lives block at the bottom of this article. The summary that follows is enough to decide whether to read further.

Where Translations Actually Live

Translations live in Cloudflare KV (or any equivalent edge KV store), not in your repository. Astro middleware fetches the namespaces a page needs at request time, with the Cloudflare Cache API in front of KV to keep latency near zero.

Translations are injected into Astro props during SSR - the client receives plain HTML with strings already rendered. No client-side i18n library, no JSON download, no hydration mismatch.

High-Level Architecture

Request → Worker → Middleware → Cache API check
                                  │
                                  ├── Hit  → cached translations (sub-1ms)
                                  └── Miss → fetch from KV (1–5ms) → fill cache
                                                                       │
                                  Inject translations into Astro props ┘
                                                                       │
                                  Render HTML with strings baked in    ┘
                                                                       │
                                  Respond                              ┘

No JSON ships to the browser. No client-side t() lookup. No hydration mismatch.

What It Buys You

Zero-deploy translation updates. A translator edits, KV updates, the next request sees the new text. No webhooks, no build queue, no CI minutes.
Lifted server-bundle limits. Translations don't live in the Worker. Locale count stops affecting cold-start time.
Render-boundary translation, built in. The Level 5 pattern (codes-not-prose) snaps in cleanly - translations arrive at the right boundary already.
Resilient fallbacks. A small DEFAULT_LOCALE dictionary compiled into the Worker keeps the site rendering even if KV goes offline.
Granular cache invalidation. Only the namespaces whose JSON content changed get purged from the edge cache (covered in Part 3 of the series).

Latency Numbers

Cache hit (95–99% of requests): sub-1 ms added per request.
Cache miss, hot KV: 1–5 ms. First request in a region after a deploy.
Cache miss, cold region: up to 10–15 ms, rare. Region warms after the first hit.

For most requests the i18n round-trip is statistically indistinguishable from bundled translations. The remaining few pay a few milliseconds for dynamic-update capability - a trade you make explicitly, not one a library makes for you.

What It Costs

Cloudflare alignment. The pattern as shipped is Cloudflare-specific (Workers + KV + Cache API). Equivalents exist on other platforms (Vercel KV, Deno KV, Upstash) but require porting.
Tooling overhead. Scripts to bundle, seed, and migrate translations. EdgeKits Core ships these out of the box; rolling your own is real work.
HTML payload growth. Wall 4 from Level 6 - weight that left the JS now lives in the HTML. Mitigated by namespace splitting, not eliminated.

Where the Full Implementation Lives

The complete code - middleware, KV fetcher, type-generation pipeline, fallback dictionaries, migration scripts - is open-source as Astro EdgeKits Core (MIT, drop-in for any Astro project on Cloudflare).

The architectural reasoning behind it is split across the three-part Edge-Native i18n series mentioned above:

Part 1 covers the middleware, the KV fetch + cache layer, and the uiLocale / translationLocale split.
Part 2 covers Zod + React Hook Form + Astro Actions in this pattern, plus D1 for translating user-generated content.
Part 3 covers content-hash cache invalidation and granular purging via the Cloudflare Purge API.

If you've read this far and one of the walls from Level 6 applies, that's where the implementation lives.

The Decision Matrix: Pick the Lowest Level That Doesn't Break

Seven levels, four shapes of project. The matrix below is opinionated - these are the picks I'd make for each archetype, not an exhaustive map of valid options.

The Closing Principle

Pick the lowest level that doesn't break under your specific load. Resist the temptation to over-engineer for problems you don't have yet - the ui.ts recipe is a perfectly good answer for plenty of production sites.

Resist the temptation to under-engineer once you're hitting one of the walls in Level 6 - patches accumulate, the pipeline grows, and one of those walls eventually tips over.

The right answer isn't the most architecturally interesting one. It's the one that matches the problem you actually have today, with a clear migration path to the next level when you outgrow it.

Stop Redeploying to Update Translations: Granular Edge Cache Invalidation with Cloudflare Purge API

Gary Stupak — Mon, 27 Apr 2026 14:41:24 +0000

Edge-Native i18n with Astro & Cloudflare Workers - Part 3

In Part 1, I made a bold promise. Translations, I argued, are not code - they are data. Your Worker shouldn't care whether you support two languages or fifty. Adding a typo fix to a German translation shouldn't feel like shipping a software release.

I genuinely believed I had delivered on that promise. The architecture stored translations in Cloudflare KV, cached them at the edge, and invalidated stale entries via content-based hashing. TRANSLATIONS_VERSION - a SHA hash of the translation bundle - was baked into the Worker as a build-time constant and embedded into every cache key. Change a string, regenerate the hash, and all old cache entries became invisible. Clean, deterministic, content-driven.

Then I deployed the EdgeKits website to production and noticed something uncomfortable.

I wanted to tweak the hero heading on the Spanish landing page. But the only way to push that change was to run npm run i18n:migrate and redeploy the Worker. Because the hash constant lived inside the Worker bundle, updating the hash meant rebuilding the entire application - every time, for every translation change.

The architecture shipped translations as data. But it invalidated them as code.

This is the kind of coupling you only notice after you start living with a system. It's subtle. It works. It even works well. But it quietly contradicts the very philosophy the architecture was designed to embody.

Untangling Translations from Deployments: What We'll Build

In this article, I'll walk through how I untangled that coupling. We'll visit three intermediate architectures, each of which solved one problem while revealing the next.

We'll talk about why wrangler deploy --var isn't actually separate from a deployment. Why storing the version in KV creates a mandatory read on every request. Why caching that version with a short TTL scales poorly across Cloudflare's global edge.

And finally, why the right answer was to stop trying to be clever about cache keys - and start being explicit about cache invalidation.

By the end of this piece, we'll have an architecture where:

Updating a translation requires exactly one command: npm run i18n:migrate.
No Worker redeployment is triggered, ever.
The edge cache is invalidated surgically - only the namespaces that actually changed are purged, while the rest stay warm.
The hot path performs zero KV reads and a single cache lookup.

We'll get there by using a part of the Cloudflare platform that most developers associate with static assets, not with i18n: the Cache Purge API.

A note on the original architecture before we proceed. Part 1 and Part 2 describe a real, working system. If you've already built on it, you haven't built on a broken foundation - you've built on a simpler one with a narrower valid use case.

I kept the original implementation available as a separate branch (v1-version-based-cache) because it's still the right choice for certain projects: sites deployed on *.workers.dev subdomains (where Purge API isn't available), projects that don't want to manage API tokens, or solo builds where translation changes are rare. We'll revisit this trade-off explicitly at the end.

But for anything that ships to a custom domain through Cloudflare - and especially for any project where translations will be updated independently from code - the architecture in this article is what you actually want.

Let's start by looking at exactly where the original approach quietly breaks its own promise.

Anatomy of Translation-Deploy Coupling

Before we fix something, we need to look at it closely enough to see why it's broken. And the tricky part about the original TRANSLATIONS_VERSION approach is that on the surface, it looks like it solves exactly the problem we wanted to solve.

Let me walk through what the architecture actually does, step by step.

When you run npm run i18n:bundle, the build script reads every JSON file under ./locales/, computes a SHA hash of the entire collected payload, and writes that hash into a generated TypeScript file:

// src/domain/i18n/runtime-constants.ts

export const TRANSLATIONS_VERSION = '01b7fd54fe04'

The fetchTranslations function then imports this constant at build time and embeds it into every cache key:

const cacheId = `${PROJECT.id}:i18n:v${TRANSLATIONS_VERSION}:${lang}:${namespaces.join(',')}`

So a cached entry might look like edgekits.dev:i18n:v01b7fd54fe04:en:common,landing. The theory is clean: change a translation, regenerate the hash, and all old cache entries become addressed by a stale key that nothing will ever ask for again. Orphaned, sure - but invisible. Cloudflare's LRU (Least Recently Used - a cache management algorithm) eviction will clean them up eventually.

How TRANSLATIONS_VERSION Behaves in Production

TRANSLATIONS_VERSION is a constant compiled into the Worker bundle. It lives in JavaScript that gets shipped during wrangler deploy. Which means: the only way to change its value at runtime is to rebuild the Worker and deploy it again.

So the promised workflow of "edit JSON → push to KV → users see the update" doesn't actually work. What actually happens is this:

You edit en/landing.json.
You run npm run i18n:migrate.
The script pushes new translations to KV.
The script regenerates runtime-constants.ts with a new hash.
... but the deployed Worker is still running with the old hash in memory.
So all edge requests continue building cache keys with v01b7fd54fe04.
And all existing cache entries continue being served - with the old content.

Until you redeploy the Worker, the hash in production doesn't change. Period.

The translation update and the cache invalidation are two physically separate events. One is a KV write. The other is a code deployment. And the architecture, despite its elegance, silently requires both.

The Mental Model Mismatch

This is the gap between what the architecture looks like it does and what it actually does.

It looks like this:

edit JSON  →  i18n:migrate  →  users see update

In reality, it's this:

edit JSON  →  i18n:migrate  →  npm run deploy  →  users see update
                                       ↑
                            this step is not optional

For solo projects where a developer is the only person touching both code and translations, that second step is easy to forget about. It happens naturally during the normal development loop.

But the moment translations become something a non-developer should be able to update - a content editor, a marketing teammate, a translator working in another timezone - the coupling becomes a real problem. You can't hand someone a command that requires a full application redeploy and call it a content workflow.

And this isn't a matter of "just automate the deploy step." Even if we automated it, we'd still be redeploying the entire Worker every time someone fixes a German typo. That's not decoupling translations from code. That's just hiding the coupling behind automation.

What Decoupling Translations Actually Requires

What we actually want is a system where:

Translation updates are a pure data operation - never a code operation.
The mechanism that tells the Worker "this content is stale" lives outside the Worker bundle.
That mechanism can be triggered from a local script or a CI job with no Wrangler involvement beyond authenticated API calls.

The rest of this article is a walk through the architectural dead-ends I hit while trying to satisfy these three requirements, and the eventual solution that made all three possible at once. Each dead-end taught me something specific about the Cloudflare platform - and, honestly, about my own assumptions about where state should live on the edge.

Let's start with the most obvious fix.

First Attempt - Version Variable via `wrangler deploy --var`

The obvious first move was to get TRANSLATIONS_VERSION out of the compiled bundle and into something the Worker reads dynamically. Cloudflare has a feature that looks like exactly that: environment variables configurable per deployment. And Wrangler has a CLI flag for it:

wrangler deploy --var TRANSLATIONS_VERSION:01b7fd54fe04

The idea writes itself. The Worker reads the version from env.TRANSLATIONS_VERSION instead of importing a constant. The i18n:migrate script computes the new hash, pushes translations to KV, and then invokes wrangler deploy --var to update just the variable. No code changes, no bundle rebuild - just a configuration update.

Clean. Minimal. Lets me keep nearly all of the existing cache key logic. Let's try it.

Why wrangler deploy --var Isn't a Real Decoupling

First red flag came before I even ran the command. wrangler deploy --var is still called deploy. And it's not a marketing choice - it genuinely creates a new entry in your Worker's Deployments history. Every time you run it, Cloudflare logs a new deployment record, complete with a version ID and a timestamp.

So even though no JavaScript has changed, the platform thinks you've just shipped new code. Open your Workers dashboard a few days after a handful of translation updates and you'll see something like this in the Deployments list:

Version 47   Deployed 2 minutes ago    TRANSLATIONS_VERSION updated
Version 46   Deployed 10 minutes ago   TRANSLATIONS_VERSION updated
Version 45   Deployed 1 hour ago       TRANSLATIONS_VERSION updated
Version 44   Deployed 3 hours ago      TRANSLATIONS_VERSION updated

This is not decoupling translations from deployments. This is renaming a deployment as a translation update and hoping nobody notices.

And there's a practical problem underneath the conceptual one: your actual code deployments - the real ones, with bug fixes and features - are now buried in a sea of translation-update deployments. If something breaks in production and you need to roll back, your rollback history is polluted with entries that have nothing to do with code changes.

How wrangler.jsonc Overwrites CLI Variables

Even setting aside the dashboard noise, there's a more serious issue waiting.

Variables set via wrangler deploy --var are transient with respect to your repository. On the next regular deployment - the one where you're actually shipping code - Wrangler reads wrangler.jsonc, sees the vars block that defines your environment variables, and overwrites whatever was set by the CLI flag.

So the flow becomes:

You run npm run i18n:migrate → wrangler deploy --var TRANSLATIONS_VERSION:abc123. Hash is now abc123 in production.
Later that day, you fix a bug and run npm run deploy.
Wrangler reads wrangler.jsonc, which still has the old hash in its vars block.
Your bug fix ships. And your translation version silently reverts to the old hash.
Edge caches that had the new content addressed under abc123 become unreachable. The old version starts serving again.

You could, in theory, keep wrangler.jsonc in sync by rewriting it from the i18n:migrate script. But now you have a build script that modifies a committed config file, which means every translation update produces a git diff that your developers have to either commit or discard. Congratulations, translations are now polluting your version control too.

Why This Approach Can't Work

The root issue is this: Cloudflare environment variables are bound to the lifecycle of the Worker, not to the lifecycle of the translations. wrangler.jsonc is the source of truth for Worker configuration. Anything you push via --var is a temporary override that gets washed away on the next real deploy.

This makes complete sense from a platform design perspective. Environment variables are meant to describe how the Worker is configured, not what data the Worker is currently serving. Stuffing content versioning into that slot is fighting the abstraction.

What I actually wanted was the opposite: a piece of state that belongs to the translations, not to the Worker. State that survives code deployments, gets updated by the i18n:migrate script, and is readable at the edge without requiring a Wrangler command to modify it.

Which brings us to the next obvious question. Cloudflare already has a perfect place to store translation-adjacent state. It's called KV. It's where the translations themselves already live. Why not just put the version there?

Translations as First-Class KV Citizens

If the problem with wrangler deploy --var is that Cloudflare environment variables are tied to the Worker's lifecycle rather than the translations' lifecycle, the fix seems obvious: stop using environment variables. Use KV instead.

KV is where the translations already live. Adding one more key to hold the version - something like <project>:meta:version - keeps everything in the same storage layer, updatable by the same script, readable by the same runtime. No Wrangler involvement. No dashboard noise. No wrangler.jsonc to keep in sync.

The flow becomes:

i18n:migrate pushes translations to KV.
In the same batch write, it updates <project>:meta:version with the new hash.
The Worker reads the version from KV at request time and uses it to construct cache keys.

Let me actually try this and see where it breaks.

The First Implementation

Here's the simplest version. The fetcher reads the version as its first KV operation:

const versionKey = `${PROJECT.id}:meta:version`
const version = await env.TRANSLATIONS.get(versionKey)
const cacheId = `${PROJECT.id}:i18n:v${version}:${lang}:${namespaces.join(',')}`

const cached = await cache.match(cacheRequest)
if (cached) return cached

const kvResults = await env.TRANSLATIONS.get(namespaceKeys, { type: 'json' })
// ...

Compile it, deploy it, run i18n:migrate to push a change. Open the site. Updates appear immediately, exactly as promised before. No redeployment needed. The content lives its own life.

Job done?

The Hot Path Regression

Look at what we just did to the hot path.

Previously - with TRANSLATIONS_VERSION compiled into the bundle - a cached request looked like this:

cache.match(request)  →  HIT  →  return

One cache lookup. Zero KV reads. This was the whole point of caching in the first place.

Now it looks like this:

KV.get('meta:version')    →  version       // KV read #1
cache.match(request)      →  HIT           // cache lookup
return

Every single request - even ones that would have been served entirely from the edge cache - now performs a mandatory KV read just to discover what version number to put in the cache key. We traded "no cache invalidation without redeploying" for "every request costs a KV read."

For a site with real traffic, this is not a minor regression. KV reads are billable. And more importantly, they add latency. An edge cache hit on Cloudflare is sub-millisecond. A KV read, even when it's fast, is a round-trip to the nearest replica. We just inserted that round-trip into every page load, for no user-facing benefit - the user would have gotten the cached response anyway.

So the naive KV approach traded one problem (coupling to code deploys) for another (coupling cache lookup to a mandatory KV read).

Attempting to Cache the Version Too

The obvious next move: if the problem is reading the version from KV on every request, cache the version. Store it in the Cache API with a short TTL, and only fall back to KV when the cache expires:

const versionCacheRequest = new Request(`https://${PROJECT.id}/meta:version`)
let versionResponse = await cache.match(versionCacheRequest)
let version: string

if (versionResponse) {
  version = await versionResponse.text()
} else {
  version = await env.TRANSLATIONS.get(versionKey)
  const response = new Response(version, {
    headers: { 'Cache-Control': 'public, s-maxage=60' },
  })
  await cache.put(versionCacheRequest, response)
}

Short TTL so that translation updates propagate within about a minute. Cache API handles the edge distribution. KV reads happen at most once per minute per edge node. This seems to solve it - the hot path is back to a single cache lookup for the version, plus the existing cache lookup for the translations.

But pause and think about what "once per minute per edge node" actually means at global scale.

The Free Tier Math

Cloudflare operates a global network of data centers. Each one maintains its own cache. With a 60-second TTL, each data center will perform one KV read per minute, per cache key, for as long as there's traffic hitting it.

A back-of-the-envelope calculation: 60 seconds in a minute × 60 minutes in an hour × 24 hours = 86,400 seconds in a day. At a 60-second TTL, that's 1,440 revalidations per edge node per day. Multiply that by the number of edge nodes that actually see traffic for your site, which for a moderately popular site could be dozens or more.

Free tier on Workers KV allows 100,000 reads per day. You can blow through that surprisingly quickly with only the version key - and that's before you've counted the actual translation reads. For a content-heavy site with traffic spread across many regions, even a paid plan starts to look expensive when every namespace load requires a mandatory version-check KV read.

You could lengthen the TTL - five minutes, ten minutes - but now translation updates propagate slowly and unpredictably. You could shorten it - five seconds - and now you're hammering KV constantly. There's no sweet spot that's actually good. You're just picking which trade-off hurts less.

The Double Cache Lookup Problem

There's also a subtler issue that's less about cost and more about architectural smell.

Every request now does two cache lookups in sequence:

cache.match(version)         →  HIT       // lookup #1
cache.match(translations)    →  HIT       // lookup #2
return

These can't be parallelized. The second lookup depends on the result of the first, because the version is used to construct the cache key for the translations. And while a cache lookup is fast, two sequential cache lookups is twice as slow as one - and we just doubled the hot-path latency for the explicit purpose of enabling cache invalidation.

At this point, it started to feel like I was fighting the platform. Each layer of caching I added to work around the previous layer's limitations introduced its own limitations, each requiring another layer. The system was getting more complex, not less.

That's usually a sign I'm approaching the problem wrong.

Stepping Back

Let me restate the original problem from scratch.

I want translation updates to propagate immediately, without redeploying code. I want the hot path to have zero KV reads. I want the cache key to be stable - so I don't pollute the cache with orphaned entries every time content changes.

The approaches we've tried all operate on the same assumption: the cache key encodes information about content versions. Embed the hash, and invalidation happens automatically when the hash changes. But automatic invalidation via key rotation has a cost, and that cost is either a redeploy, a mandatory KV read, or a double cache lookup.

What if I flip the assumption? What if the cache key doesn't encode version at all? What if cache entries are never orphaned by content changes - because the key is static - and I invalidate them some other way?

That's when I started reading the Cloudflare Cache docs for something I'd been ignoring the whole time: not how to build cache keys, but how to destroy cache entries.

The Breakthrough - Static Keys + Explicit Invalidation

Every approach we've tried so far shares the same underlying pattern: the cache key contains a version marker, and we invalidate by rotating that marker. Content changes → hash changes → cache key changes → old entries become orphaned → new entries get created under a new key.

This is a passive invalidation strategy. Nothing actively removes stale entries; we just stop addressing them. They sit around until Cloudflare's LRU policy decides to evict them. The cache fills up with ghosts.

The alternative is active invalidation: the cache key stays stable across content changes, and when translations update, we explicitly tell Cloudflare to delete the affected entries.

Once I stated it that way, it became obvious that I'd been solving the wrong problem. I'd been trying to make cache keys carry versioning information. But cache keys are identifiers, not metadata. Their job is to answer "which piece of content is this?" - not "when was it last modified?" Versioning information belongs somewhere else.

The New Cache Key Shape

If the key doesn't need to carry a version, it becomes simpler:

i18n:<locale>:<namespace>

That's the logical identifier. Wrapped into the URL shape that Cloudflare's Cache API expects, it becomes:

https://<PROJECT.id>/<encoded-identifier>

One key per locale:namespace pair. Stable forever. The same key that stores the Spanish landing translations today will store them in a year - whatever version "today" happens to be.

There's another change baked into this shape that I glossed over in the earlier examples. Previously, the cache key encoded a comma-joined list of namespaces:

i18n:v<hash>:<locale>:<ns1,ns2,ns3>

Every unique combination of namespaces requested by a page produced a unique cache entry. A page asking for common,landing created one entry; a page asking for common,landing,newsletter created a completely separate entry, even though two-thirds of the content overlapped. Same translations, cached three times under three different keys.

With static per-namespace keys, each namespace is its own cache entry. A page that needs common,landing,newsletter does three parallel cache lookups, assembles the result, and any other page requesting common,landing gets cache hits on both - the namespaces are shared across requests.

What the Hot Path Looks Like Now

Let me walk through a realistic request with this architecture.

A user hits /es/blog/some-article. The page needs common, blog, and newsletter namespaces. The fetcher issues three cache lookups in parallel:

const cacheResults = await Promise.all(
  namespaces.map(async (ns) => {
    const req = buildTranslationCacheRequest(locale, ns)
    const cached = await cache.match(req)
    return { ns, data: cached ? await cached.json() : null, hit: !!cached }
  })
)

If all three are in the cache - FULL HIT - the function returns immediately. Zero KV reads. One round of parallel cache lookups, not a sequential chain. The total latency is bounded by the slowest of the three parallel lookups, not their sum.

If one namespace is missing - say blog was recently invalidated - the fetcher filters down to just the missing ones and issues a single KV batch call:

const missing = cacheResults.filter((r) => !r.hit).map((r) => r.ns)
const kvKeys = missing.map((ns) => buildTranslationKvKey(locale, ns))
const kvBatch = await env.TRANSLATIONS.get(kvKeys, { type: 'json' })

One KV batch. One call regardless of how many namespaces are missing. Results get merged with the cache hits, written back to the cache, and returned.

This is genuinely better than both previous architectures on every metric I care about:

Hot path: zero KV reads, one parallel cache roundtrip.
Partial miss: exactly the missing namespaces fetched, in one batch.
Cache bloat: none - each locale:namespace is exactly one cache entry, period.
Version tracking overhead: zero - there's no version to track at the request layer.

How Do Translation Updates Reach Users Without Key Rotation?

But I haven't addressed the elephant in the room. If cache keys are stable and never change, how does a translation update ever reach users?

The cache entry for edgekits.dev:i18n:es:landing stores the Spanish landing translations as of the last time that entry was written. If I edit that translation in KV and the cache entry is still present, the user keeps seeing the old content. Forever, in principle - we removed the cache TTL because we didn't want arbitrary expiry windows. An entry written once will be served until Cloudflare evicts it for space reasons, which on an active site could be weeks or months.

So we need a way to, after i18n:migrate pushes a change to KV, explicitly remove the affected cache entries. Not rotate keys. Not change cache TTLs. Actually delete specific entries from the Cloudflare edge cache.

The thing is, I'd been vaguely aware this capability existed. Every developer who's used Cloudflare has seen the "Purge Cache" button in the dashboard. It purges static assets. It's what you use when you've just pushed a new version of your CSS and you want everyone to see it immediately. I'd categorized it mentally as "a CDN tool, for static file deploys" - something orthogonal to how I think about Workers and application state.

What I hadn't registered is that the purge system works on any URL that's in the Cloudflare cache - including URLs that were put there by the Workers Cache API. cache.put(cacheRequest, response) inside a Worker uses the same underlying storage that serves static assets. And the same API that purges styles.css can purge an application-level cache entry.

So the architecture becomes:

Cache keys are stable. <PROJECT.id>:i18n:<locale>:<namespace>.
Cache entries have effectively infinite TTL. Cache-Control: s-maxage=31536000, immutable.
Invalidation is explicit. When i18n:migrate runs, it calls the Cloudflare Purge API and hands it the list of URLs to invalidate.
Invalidation is granular. Only the cache entries for the namespaces that actually changed get purged. Everything else stays warm.

This is the architecture I ended up shipping. The rest of the article is about how to make it actually work - the Purge API mechanics, how to detect which namespaces changed, how to deploy and configure the whole thing, and the trade-offs you should know before adopting it.

Let's look at the Purge API first.

Cloudflare Purge API - The Missing Piece

The Cloudflare Purge API is one of those platform features that most developers know exists but have never actually used from code. It's the mechanism behind the "Purge Cache" button in the dashboard. It's what gets mentioned in passing when someone asks "how do I force a cache refresh." And it's rarely discussed in the context of Workers application architecture, even though it slots in perfectly.

Let's look at what it actually does and what constraints it imposes.

How Purge-by-URL Works

The Purge API has several modes - purge everything, purge by hostname, purge by tag, purge by prefix, and purge by single file. The one we care about is purge by single file (also called purge by URL), which takes a list of specific URLs and invalidates them immediately across Cloudflare's entire edge network.

The request shape is straightforward:

POST https://api.cloudflare.com/client/v4/zones/<ZONE_ID>/purge_cache
Authorization: Bearer <API_TOKEN>
Content-Type: application/json

{
  "files": [
    "https://edgekits.dev/i18n%3Aen%3Alanding",
    "https://edgekits.dev/i18n%3Aes%3Alanding"
  ]
}

You hand it a list of URLs. It returns success and deletes those exact entries from the edge cache, globally. The next request to each of those URLs results in a cache miss, the Worker falls through to KV, and the fresh content is re-cached under the same key. One API call, global invalidation, takes about a second to propagate.

There's something worth noticing here: the URLs in the purge request are the same URLs we used as cache keys in the previous section. The https://<PROJECT.id>/<encoded-key> shape isn't just a convention for cache.put - it becomes the exact addressing scheme for purge_cache.

This is the part that ties the whole architecture together. The fetcher writes cache entries under a URL; the migration script deletes cache entries under the same URL. One formula, shared between two files.

This is why translations-keys.ts exists as a dedicated module in the implementation. Cache URLs need to be computed identically in two contexts - at request time inside the Worker, and at deploy time in the Node.js migration script. Any drift between the two, and the purge silently misses. Centralizing the formula in one file eliminates that class of bug by construction.

Rate Limits and How They Affect Us

Free-tier Cloudflare accounts get 5 purge requests per minute, with a token bucket capacity of 25. Each purge request can include up to 30 URLs for the free tier (paid tiers get higher numbers of URLs per request, but the request rate limits are similar or more relaxed).

Let me put those limits in context for an i18n workload. A typical project has, say, 5 locales and 10 namespaces - that's 50 possible locale:namespace cache entries total. Even if every single one of them changed simultaneously, that's 50 URLs to purge, which splits into two API calls of 30 + 20. Well within the per-minute request budget.

In practice, translation updates almost never touch every namespace at once. A typical update changes one or two namespaces in one locale - maybe a typo fix in the Spanish landing page, or a new key added to the German pricing copy. That's one or two URLs per migration, and the rate limit is effectively infinite for that workload.

The only scenario where rate limits could matter is the first migration on a fresh setup, where no hash file exists yet and every namespace is treated as "changed." We'll come back to this in the next section - the solution is just chunking the purge into batches of 30 URLs with a brief pause between batches.

The Proxied-Domain Requirement

There's one architectural constraint that trips people up, and it's worth calling out clearly before you spend an evening debugging it.

The Purge API operates on Cloudflare's CDN layer. It requires that your domain is proxied through Cloudflare - the orange cloud icon next to your DNS records. If your Worker is only deployed to a *.workers.dev subdomain, or if your custom domain has the grey cloud (DNS-only mode), neither the Cache API nor the Purge API actually do anything.

On *.workers.dev in particular, cache.put() silently returns without storing, cache.match() always returns undefined, and every request falls straight through to KV - because the Workers Cache API is tied to zone-level caching that doesn't exist for the shared workers.dev subdomain.

I noticed this while testing the implementation: wrangler tail showed no cache hits at all on the *.workers.dev deployment - every single request went to KV. Meanwhile the migration script reported successful purges.

It took me a while to realize the two observations were related: there was no cache to purge, because there was no cache to begin with. The Purge API was returning success because the request was syntactically valid, but there was nothing in front of the Worker on that URL to invalidate.

The moment I pointed the same test at the proxied custom domain, everything fell into place. Cache hits started appearing in tail logs. Purge requests actually removed entries. New content propagated within seconds globally.

This requirement is worth respecting when you decide whether to adopt this architecture. If your project is deployed exclusively on workers.dev - say, it's an internal tool, or you're in early development and haven't bought a domain yet - this whole approach doesn't apply.

You have two reasonable alternatives: stick with the content-hash architecture from Part 1 (we'll revisit this in the trade-offs section at the end), or simply disable edge caching entirely by setting I18N_CACHE=off and read translations directly from KV on every request.

For a preview deployment with modest traffic, the KV free tier gives you plenty of headroom - 100,000 reads per day is more than enough for most pre-launch projects, and you get perfectly up-to-date content without any invalidation machinery at all.

API Token and Zone ID Setup

The Purge API requires an API token with the Cache Purge permission, scoped to your specific zone. This is a different token than the one Wrangler uses for deployment - and that's actually a good thing. The purge token has minimal permissions: it can only delete cache entries on one zone. Even if it leaks, the blast radius is "an attacker can make your translations briefly uncached," which is annoying but not catastrophic.

You create the token at dash.cloudflare.com/profile/api-tokens either via the Cache Purge template or manually with Zone → Cache Purge → Purge permissions scoped to your domain. The token then goes into .dev.vars for local execution of the migration script, and into Worker Secrets for any production-side code that might need it.

Importantly, the Zone ID is a separate piece of information - it identifies which zone you're purging, not who is authorized to purge. Zone IDs are not secrets. You can find yours on the overview page of your Cloudflare domain dashboard, and it's safe to commit to wrangler.jsonc as a plain vars entry.

This distinction matters when you're setting up the project in a public repository: the token stays out of git, but the zone ID can live alongside the rest of your config.

Why Purge API Fits Edge Cache Invalidation

If I'd known how perfectly Purge API's semantics matched what I needed, I would have gone straight here from the start. The API does exactly one thing: delete specific URLs from the edge cache, immediately, globally, at the zone level. That's the whole feature. And "delete specific URLs, immediately, globally" is the exact primitive that was missing from every previous architecture.

What remains is one detail - a small but important one. When i18n:migrate runs, we don't want to naively purge every possible translation URL. That would work, but it would cause a cache stampede - every edge node would simultaneously cold-fetch every namespace from KV on the next request to each locale.

For a project with dozens of namespaces across multiple locales, that's a lot of unnecessary KV reads for no benefit.

What we want is to purge only the entries that actually changed. And to do that, we need a way to track what "actually changed" means between one run of i18n:migrate and the next.

Incremental Purging - The Hash File Strategy

We have two pieces of the architecture in place: static cache keys that never change, and a Purge API that can delete specific URLs on demand. What's missing is the part that decides which URLs to delete when i18n:migrate runs.

The naive version is easy: purge every possible locale:namespace URL every time. It would work, and for a small project with a handful of namespaces it might even be fine. But at any real scale, this approach has a cost.

Why "Purge Everything" Causes a Cache Stampede

Imagine a project with 5 locales and 12 namespaces - that's 60 cache entries total. You fix a typo in en/landing.json. One file changed. With naive invalidation, all 60 entries get purged.

The next time users hit your site:

Every edge node that had warm cache entries now has cold cache entries.
Every page load triggers a parallel cache miss.
Every miss triggers a KV read.
Multiplied across every edge node globally.

This is a cache stampede - a sudden burst of origin reads triggered by simultaneously invalidating content that was previously hot. For a busy site, that burst can be significant. Across hundreds of edge nodes, a single "fix a typo" operation produces thousands of redundant KV reads to re-populate cache entries that didn't need to change in the first place.

The cost isn't catastrophic - KV is fast, and this isn't a database hitting its connection limit. But it's wasteful in the exact way that caching was supposed to prevent. We already know that 59 of those 60 namespace-locale pairs are identical to what they were before. Why would we tell every edge node in the world to forget them?

What we want is: en/landing.json changed, purge exactly edgekits.dev/i18n:en:landing, leave the other 59 entries alone. Surgical invalidation. Zero wasted cache evictions. The other locales keep serving warm cache forever - or at least until someone changes them.

What "Changed" Actually Means

To purge selectively, we need to know which namespaces actually changed between two runs of i18n:migrate. Python developers might reach for mtimes. Database folks might reach for updated_at columns. But we have something simpler available: the content of the files themselves.

The idea is this: after every successful migration, we compute a SHA hash of each locale-namespace JSON and store the hashes in a local file. On the next migration, we compute the hashes again and compare. Any pair whose hash differs between the two runs is a pair that changed. Any pair whose hash matches is untouched.

// After reading all locale JSON files:
const currentHashes: Record<string, string> = {}
for (const locale of locales) {
  for (const ns of namespaces) {
    const content = JSON.stringify(translations[locale][ns])
    currentHashes[`${locale}:${ns}`] = sha256(content)
  }
}

// Compare against previous run:
const previousHashes = readHashFile() ?? {}
const changedKeys: string[] = []
for (const key of Object.keys(currentHashes)) {
  if (currentHashes[key] !== previousHashes[key]) {
    changedKeys.push(key)
  }
}

changedKeys is now the exact list of locale:namespace pairs whose content differs from the last migration. Feed those into buildTranslationCacheUrl and you've got the precise list of URLs to purge.

Where the Hash File Lives

The hash file is .i18n-hashes.json in the project root. Two important properties:

It's local state, not shared state. The file records what was last successfully pushed from your machine. If a teammate runs i18n:migrate from their machine without having your hash file, their first run will see no previous hashes, treat everything as changed, and purge all URLs - which is the correct safe default for a first run.

It's gitignored. Committing it would be wrong for two reasons. First, it's a representation of state held on a specific machine at a specific time, not something that belongs in a repo. Second, if two developers with different hash files both committed, you'd get merge conflicts on a file nobody should be manually editing. The file is a cache - treat it like any other local cache (the .wrangler/ directory, dist/, etc.).

The trade-off is that a fresh clone on a different machine always produces a "purge everything" outcome on its first run. For most projects, this is fine - the worst case is a single cache stampede right after setup, which self-heals within the first few minutes of traffic.

If you care about avoiding even that, there are options (storing the hash file in your R2 bucket, committing it with a merge-driver-style strategy, etc.), but for the reference implementation I chose the simpler path.

The Full i18n:migrate Invalidation Pipeline

Putting everything from this section together, the complete flow of i18n:migrate looks like this:

 1. Read all JSON files under ./locales/**.
 2. Compute SHA hashes per locale:namespace pair.
 3. Write i18n-data.json (the KV bulk payload).
 4. Push translations to remote KV via wrangler kv bulk put.
 5. Read .i18n-hashes.json (previous state). Missing file = first run.
 6. Diff against current hashes → produce list of changed keys.
 7. If changedKeys is empty → skip purge. Log "no cache entries to purge."
 8. Otherwise → build Purge URLs via buildTranslationCacheUrl.
 9. Call Cloudflare Purge API, chunking if needed to stay under rate limits.
10. On success → write updated hashes to .i18n-hashes.json.
11. On purge failure → log warning, do not update hash file (retry next time).

Step 11 is worth pausing on. If KV was updated but the purge call failed - say the API token expired, or we hit a rate limit - we deliberately do not write the updated hash file.

The reasoning: on the next migration, we want the changed namespaces to still look "changed" relative to the last known good state, so the retry happens automatically.

This gives us graceful recovery without manual intervention. If i18n:migrate reports a purge failure, you just run it again - the hash diff will include everything that was supposed to be purged last time.

Rate Limit Arithmetic (Revisited)

Back in the Purge API section, I noted that free tier allows 5 purge requests per minute with up to 30 URLs per request. Let me put this in the context of the incremental strategy.

In normal operation, a single i18n:migrate run purges somewhere between 1 and 3 URLs - a content editor fixing copy in one or two namespaces. That's one API call, well inside limits. The rate limit is effectively irrelevant.

The only situation where you might approach the rate limit is a fresh setup with a large project: no hash file, 10 locales × 20 namespaces = 200 URLs to purge on the first migration. 200 URLs ÷ 30 URLs per request = 7 API calls. Free tier allows 5 per minute, so two of those calls would be queued for the second minute. Still finishes in under two minutes total.

For practical usage, the implementation handles this with a simple chunking loop: split URLs into groups of 30, send each chunk, and pause between chunks if a rate limit is hit. We'll see the specific code in the Implementation Walkthrough.

But the headline is: rate limits matter only for the very first run on a large project, and even then they're a mild speed bump, not a real constraint.

What This Gives Us

With the hash-file strategy layered on top of static keys and Purge API, the architecture now satisfies every requirement we set out in the first section:

Translation updates are a pure data operation. No deploys, no version constants, no Wrangler variables. Just i18n:migrate.
Cache invalidation is explicit and external to the Worker bundle. The Worker doesn't know or care about versions; it just reads from a stable URL.
Invalidation is granular. Only the URLs that correspond to actually-changed content get purged. Everything else stays warm.
The hot path is one parallel cache lookup with zero KV reads. Unchanged by the complexity of invalidation machinery - because invalidation happens out-of-band at deploy time, not in-band at request time.

The conceptual work is done. What remains is making this work in actual code - how fetcher.ts, bundle-translations.ts, and translations-keys.ts fit together, and the concrete patterns that make the whole thing maintainable.

Let's walk through the implementation.

Implementation Walkthrough

The architecture we've built splits naturally across three files, each with a distinct responsibility. Let's look at how they fit together.

translations-keys.ts is the single source of truth for addressing cache entries. It's imported by both the runtime fetcher and the migration script, so both sides of the invalidation contract speak the same URL format.

fetcher.ts is the hot-path code that runs inside the Worker. It reads translations from the cache, falls back to KV when cache is cold, and writes results back to the cache for next time.

bundle-translations.ts is the Node.js script that runs on your machine. It generates TypeScript artifacts, pushes translations to KV, detects which namespaces changed, and calls the Cloudflare Purge API with the exact URLs to invalidate.

Three files. Each one has exactly one job. Most of the complexity of the whole invalidation system lives in the third file; the first two stay lean.

The Keys Module

src/domain/i18n/translations-keys.ts exports three functions that together cover every way we need to address a translation entry:

// src/domain/i18n/translations-keys.ts

// KV key - used by env.TRANSLATIONS.get() inside the Worker
export function buildTranslationKvKey(locale: Locale, ns: Namespace): string {
  return `${PROJECT.id}:${ns}:${locale}`
}

// Cache URL - used as the key for the Workers Cache API
export function buildTranslationCacheUrl(
  locale: Locale,
  ns: Namespace
): string {
  const cacheId = `i18n:${locale}:${ns}`
  return `https://${PROJECT.id}/${encodeURIComponent(cacheId)}`
}

// Cache Request - what cache.match() and cache.put() actually take
export function buildTranslationCacheRequest(
  locale: Locale,
  ns: Namespace
): Request {
  return new Request(buildTranslationCacheUrl(locale, ns))
}

These three functions are the glue that holds the whole architecture together. The fetcher uses buildTranslationCacheRequest to look up and write entries. The migration script uses buildTranslationCacheUrl to construct purge URLs. The KV access layer uses buildTranslationKvKey to read from and write to KV. If any one of them drifted in format from the others, things would silently break - purge URLs would miss their targets, or cache reads would look for the wrong keys.

Centralizing all three into one module enforces consistency at the type level. You can't accidentally build a cache URL one way in fetcher.ts and another way in bundle-translations.ts. There's only one place that knows the format.

The Fetcher

src/domain/i18n/fetcher.ts is where the hot-path logic lives. The function takes a locale and a list of namespaces, and returns the merged translation dictionaries. Under the hood, it does four things in sequence - though the first step runs in parallel across namespaces.

1. Check the cache for each namespace in parallel.

// src/domain/i18n/fetcher.ts

const cacheResults = await Promise.all(
  namespaces.map(async (ns) => {
    const cacheRequest = buildTranslationCacheRequest(locale, ns)
    try {
      const cached = await cache.match(cacheRequest)
      if (cached) {
        return { ns, data: await cached.json(), hit: true }
      }
    } catch (error) {
      debug(env, `i18n cache READ error for ${ns}`, error)
    }
    return { ns, data: null, hit: false }
  })
)

Every namespace is checked independently. If you requested common, landing, and newsletter, all three cache lookups happen at the same time. The Promise.all wait is bounded by the slowest of the three - not their sum. Any individual lookup that throws (say the cache returned a malformed response) is caught per-namespace and demoted to a cache miss rather than failing the whole request.

2. Separate hits from misses in a single pass.

// src/domain/i18n/fetcher.ts

const finalData: Partial<PickSchema<N>> = {}
const missingNamespaces: N[] = []

for (const { ns, data, hit } of cacheResults) {
  if (hit) {
    finalData[ns] = data as PickSchema<N>[typeof ns]
  } else {
    missingNamespaces.push(ns)
  }
}

if (missingNamespaces.length === 0) {
  // All namespaces served from cache - zero KV reads.
  return finalData as PickSchema<N>
}

This is the fast path. If every namespace was a cache hit, the function returns immediately with the merged result - we never touch KV, never allocate anything further. For a busy site with warm caches, the vast majority of requests take this path.

3. Fetch missing namespaces from KV in a single batch.

// src/domain/i18n/fetcher.ts

const missingKvKeys = missingNamespaces.map((ns) =>
  buildTranslationKvKey(locale, ns)
)

let kvResults = new Map<string, unknown | null>()
let kvFailed = false

try {
  kvResults = (await env.TRANSLATIONS.get(missingKvKeys, {
    type: 'json' as const,
  })) as Map<string, unknown | null>
} catch (error) {
  kvFailed = true
}

Cloudflare's KV batch get() accepts up to 100 keys per call and returns a Map keyed by the KV keys. One network round-trip, regardless of how many namespaces are missing. If KV is entirely unavailable - service outage, misconfigured binding, transient network issue - we catch the error into a kvFailed flag instead of propagating it. The flag becomes the signal for the next step to use fallbacks only.

4. Merge with fallbacks and schedule cache writes.

// src/domain/i18n/fetcher.ts

const putPromises: Promise<void>[] = []

for (let i = 0; i < missingNamespaces.length; i++) {
  const ns = missingNamespaces[i] as N
  const kvKey = missingKvKeys[i] as string

  const kvValue = kvFailed ? {} : ((kvResults.get(kvKey) as object) ?? {})

  const fallbackConstName = `FALLBACK_${String(ns).toUpperCase()}`
  const fallback = FALLBACKS?.[fallbackConstName]

  const nsData = fallback ? deepMerge(fallback, kvValue) : kvValue
  finalData[ns] = nsData as PickSchema<N>[typeof ns]

  const cacheRequest = buildTranslationCacheRequest(locale, ns)
  const response = new Response(JSON.stringify(nsData), {
    headers: {
      'Content-Type': 'application/json; charset=utf-8',
      'Cache-Control': 'public, s-maxage=31536000, immutable',
    },
  })

  putPromises.push(
    cache.put(cacheRequest, response.clone()).catch((error: unknown) => {
      debug(env, `i18n cache WRITE error for ${ns}`, error)
    })
  )
}

For each missing namespace we construct the final value (KV result merged over the compiled fallback, or just the fallback if KV failed), write it into finalData for the return value, and also enqueue a cache write for next time. The cache put is wrapped in .catch() - a failed write is logged and discarded, it doesn't break the request.

Two things about the cache write itself. First, Cache-Control: public, s-maxage=31536000, immutable - we tell the cache this entry lives for a year and never revalidates. Its only exit path is explicit purging. Second, response.clone() is necessary because cache.put takes ownership of the response body stream, and the stream can only be consumed once.

5. Run the cache writes as background work.

// src/domain/i18n/fetcher.ts

if (putPromises.length > 0) {
  const allPuts = Promise.all(putPromises)

  if (waitUntil) {
    // Real Workers: schedule as a non-blocking background task.
    waitUntil(allPuts)
  } else {
    // Dev / non-Workers: await directly so cache is actually written.
    await allPuts
  }
}

return finalData as PickSchema<N>

In production, all cache writes are batched into one waitUntil call so they happen in the background after the response has already been sent. The user doesn't wait for the cache write - the page renders immediately, and the cache entry lands shortly after.

The waitUntil-or-await fallback matters for local development. Astro's dev server runs the fetcher in Node.js rather than inside a Cloudflare Worker, and there's no waitUntil there. If we blindly scheduled the writes via waitUntil?.() and it was undefined, the writes would never run, and the cache would stay empty. Falling back to await keeps the code testable locally - cache writes are synchronous in dev but non-blocking in prod.

The Migration Script

scripts/bundle-translations.ts is the longer and more interesting file. It does a lot:

Parses command-line flags (--fallbacks, --local, --deploy-version).
Reads every JSON file under ./locales/**.
Computes per-namespace content hashes and detects changes against .i18n-hashes.json.
Generates four artifacts: i18n-data.json, i18n.generated.d.ts, runtime-constants.ts, and optionally fallbacks.generated.ts.
Pushes translations to KV (local or remote depending on the --local flag).
Builds Purge URLs for changed namespaces only.
Calls the Cloudflare Purge API with those URLs, chunking as needed.
Updates .i18n-hashes.json - but only if the purge step actually succeeded.

I'll walk through the parts that matter for this article's architecture - hash comparison, purge call, and the graceful recovery logic. The other parts (JSON reading, TS codegen) are mechanical and already described in Part 1.

Loading `.dev.vars` Manually

One small but important detail: the script needs access to CLOUDFLARE_CACHEPURGE_API_TOKEN, which lives in .dev.vars. wrangler dev reads that file automatically at runtime, but tsx (which is what runs the migration script) doesn't. So we parse it ourselves, once, right before the purge step:

// scripts/bundle-translations.ts

const devVarsPath = path.join(ROOT, '.dev.vars')
if (fs.existsSync(devVarsPath)) {
  const lines = fs.readFileSync(devVarsPath, 'utf8').split('\n')
  for (const line of lines) {
    const trimmed = line.trim()
    if (!trimmed || trimmed.startsWith('#')) continue
    const eqIndex = trimmed.indexOf('=')
    if (eqIndex === -1) continue
    const key = trimmed.slice(0, eqIndex).trim()
    const value = trimmed.slice(eqIndex + 1).trim()
    if (key && !(key in process.env)) {
      process.env[key] = value
    }
  }
}

The !(key in process.env) guard is important - if a variable is already set in the real environment (say by an explicit shell export), we don't overwrite it. Real environment wins; .dev.vars fills the gaps.

This is the kind of detail that's easy to miss until you spend an hour debugging why your script can't find a token that's definitely in the right file.

Computing Hashes and Diffing

After reading all JSON files, the script computes current hashes and compares against the previous run in a single pass:

// scripts/bundle-translations.ts

const previousHashes: HashMap = fs.existsSync(HASHES_FILE)
  ? (JSON.parse(fs.readFileSync(HASHES_FILE, 'utf8')) as HashMap)
  : {}

const currentHashes: HashMap = {}
const changedKeys: string[] = [] // "<locale>:<namespace>" pairs that changed

for (const [locale, namespaces] of Object.entries(collected)) {
  for (const [ns, json] of Object.entries(namespaces)) {
    const hashKey = `${locale}:${ns}`
    const hash = computeHash(json)
    currentHashes[hashKey] = hash

    if (previousHashes[hashKey] !== hash) {
      changedKeys.push(hashKey)
    }
  }
}

changedKeys is a flat array of strings in the form "<locale>:<namespace>". Missing file on disk → empty previousHashes → every current key is "changed" → all URLs get purged on first run. This is the correct safe default I described in the last section.

Two implementation details worth calling out.

stableStringify instead of JSON.stringify. Regular JSON.stringify preserves key order from the source object. That's fine if your JSON files never have their keys reordered, but it's fragile - a prettier version bump or a text editor that alphabetizes keys on save would produce different hashes for identical content. stableStringify sorts keys deterministically before serializing, so the hash reflects content, not key order.

Truncated hash (12 chars). SHA-256 produces 64 hex characters. We only need enough bits to detect collisions between a few hundred namespace contents, and 12 hex chars is plenty - that's 48 bits of entropy, far more than needed for this use case. Shorter hashes make logs and debugging output more readable.

The Purge API Call

Once we have changedKeys, we build the full list of URLs to purge:

// scripts/bundle-translations.ts

const purgeUrls = changedKeys.map((hashKey) => {
  const [locale, ns] = hashKey.split(':') as [string, string]
  return buildTranslationCacheUrl(locale as any, ns as any)
})

This is where translations-keys.ts pays off most visibly. The same function that the fetcher uses to construct cache keys for cache.put and cache.match is now producing the list of URLs to delete. There's no second "how to construct a purge URL" function anywhere - just one formula, used in three different places.

Now the chunking and rate-limit handling. Cloudflare's Purge API accepts up to 100 URLs per single request (this is the same limit across all plans), and the Free plan allows 800 URLs per second total. So we chunk into groups of 100 and throttle to 8 chunks per second at most:

// scripts/bundle-translations.ts

const CHUNK_SIZE = 100
const MAX_CHUNKS_PER_SEC = 8

for (let i = 0; i < urls.length; i += CHUNK_SIZE) {
  const chunk = urls.slice(i, i + CHUNK_SIZE)
  const currentChunkIndex = Math.floor(i / CHUNK_SIZE) + 1

  const response = await fetch(
    `https://api.cloudflare.com/client/v4/zones/${zoneId}/purge_cache`,
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${apiToken}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ files: chunk }),
    }
  )

  if (response.status === 429) {
    // Rate limit hit - wait and retry the same chunk.
    await sleep(1000)
    i -= CHUNK_SIZE
    continue
  }

  if (!response.ok) {
    return false // propagate failure to caller
  }

  // After 8 chunks (= 800 URLs), pause a second to stay under the cap.
  if (
    currentChunkIndex % MAX_CHUNKS_PER_SEC === 0 &&
    i + CHUNK_SIZE < urls.length
  ) {
    await sleep(1000)
  }
}

return true

For the vast majority of real-world uses - a handful of URLs per migration - this loop runs once and exits. The retry logic and the pacing pause only matter on a fresh setup where hundreds of URLs need purging at once.

Updating the Hash File (Carefully)

Here's the part that makes the system recover gracefully from partial failures. The hash file is updated only in outcomes where invalidation was either successful or not needed:

// scripts/bundle-translations.ts

let shouldWriteHashes = false

if (IS_LOCAL) {
  // Local: no edge cache exists, purge is not applicable.
  shouldWriteHashes = true
} else if (changedKeys.length === 0) {
  // Remote with no changes: nothing needed purging.
  shouldWriteHashes = true
} else {
  // Remote with changes: purge must succeed to commit the new state.
  if (!zoneId || !apiToken) {
    console.warn('[i18n] Skipping purge - credentials missing.')
    // shouldWriteHashes stays false
  } else {
    const purgeSuccess = await purgeTranslationsCache(
      zoneId,
      apiToken,
      purgeUrls
    )
    if (purgeSuccess) {
      shouldWriteHashes = true
    } else {
      console.error('[i18n] Purge failed - hash file NOT updated.')
    }
  }
}

if (shouldWriteHashes) {
  fs.writeFileSync(
    HASHES_FILE,
    JSON.stringify(currentHashes, null, 2) + '\n',
    'utf8'
  )
}

Four outcomes, only three of which commit the new state to disk. The fourth outcome - remote run with changes and a failed purge - deliberately leaves the hash file untouched. The next migration will see the same diff as this one and re-attempt the invalidation automatically. No manual intervention, no silent staleness, no wedged state.

This is the "graceful recovery" pattern from the previous section made concrete. A successful migration updates the ledger. A failed migration leaves the ledger where it was, so the next attempt gets a free retry on exactly the same set of URLs.

End-to-End Flow: From Migration to Edge Cache

Here's the full picture of how the three files cooperate during a translation update:

You:   edit en/landing.json
       run npm run i18n:migrate
              │
              ▼
bundle-translations.ts:
   │
   ├── read locales, codegen artifacts
   ├── stableStringify + sha256 → currentHashes
   ├── read .i18n-hashes.json → previousHashes
   ├── diff → changedKeys = ["en:landing"]
   ├── push to KV: wrangler kv bulk put i18n-data.json --remote
   ├── load .dev.vars → process.env
   ├── imports translations-keys.ts
   ├── buildTranslationCacheUrl('en', 'landing')
   │     → "https://edgekits.dev/i18n%3Aen%3Alanding"
   ├── POST to Cloudflare Purge API with [purgeUrl]
   ├── purge succeeded → write currentHashes to .i18n-hashes.json
   └── done. 1 URL purged, other namespaces remain warm.

Next request from a user for /en/:
       │
       ▼
fetcher.ts (inside the Worker):
   │
   ├── imports translations-keys.ts
   ├── buildTranslationCacheRequest('en', 'landing')
   │     → same URL as above, as a Request object
   ├── cache.match(req) → MISS (we just purged it)
   ├── KV batch read for locale=en, ns=['landing']
   │     → returns fresh content
   ├── merge with FALLBACK_LANDING, write to finalData
   ├── cache.put(req, freshResponse) via waitUntil
   └── return merged translations to page

Every request after that:
       │
       ▼
fetcher.ts:
   ├── cache.match(req) → HIT
   ├── return cached translations
   └── zero KV reads

The invalidation happens at migration time, out of band. Requests are never slowed down by the invalidation machinery - they only benefit from the cache it produces. And because translations-keys.ts is shared between the Worker and the migration script, the URLs that get purged are guaranteed to be the same URLs the fetcher writes and reads. No drift. No silently-missed invalidations.

This is the design in its entirety. Everything else is configuration.

Production Setup & DX Considerations

The code is the easy part. The awkward part, which I ended up rewriting notes about three times, is the order in which you have to set up the pieces on the Cloudflare side to make the first migration actually work.

The pieces that need to exist before npm run i18n:migrate runs are:

A real Cloudflare KV namespace with a real ID in wrangler.jsonc.
A deployed Worker attached to your custom domain (proxied through Cloudflare).
An API token with Cache Purge permission, accessible to the script via .dev.vars.
The zone ID of your Cloudflare-managed domain, readable from wrangler.jsonc.
That same API token registered as a Worker Secret on Cloudflare, for any production runtime code that might want it.

None of this is complicated individually. But the ordering matters, because several of the steps depend on outputs from earlier steps. Here's the sequence that works, in the order I wish someone had handed me.

1. Create the KV Namespace

npx wrangler kv namespace create TRANSLATIONS

Wrangler prints the new namespace's ID. Copy it into wrangler.jsonc:

"kv_namespaces": [
  {
    "binding": "TRANSLATIONS",
    "id": "<your-real-kv-id>"
  }
]

Note the absence of preview_id. The Cloudflare docs are clear that preview_id is only required when using wrangler dev --remote to develop against remote resources - which this project doesn't. For local development, Wrangler uses id as a folder name inside .wrangler/state/v3/kv/ and never validates the format. So the same field works for both local dev (where the value is just a folder name) and remote deploys (where it resolves to an actual KV namespace).

Incidentally, this means that before you've created a real namespace, wrangler.jsonc can contain a placeholder like "id": "your_kv_id_here" and local dev still works. npm run dev in this starter runs Astro's Node.js dev server - it doesn't call Wrangler at all, so there's no authentication step involved there. npm run i18n:seed does invoke wrangler kv bulk put --local, which writes to a local folder under .wrangler/state/ without hitting any remote API, but depending on your Wrangler version and any previously-cached credentials, it may still try to verify your account. If that prompt appears on a first-time setup, wrangler logout or clearing ~/.config/.wrangler/ is usually enough to reset it into a true no-account state.

2. Add the Zone ID to `wrangler.jsonc`

"vars": {
  "CLOUDFLARE_ZONE_ID": "<your-zone-id>",
  "I18N_CACHE": "on",
  "DEBUG_I18N": "off",
  "DEMO_MODE": "off"
}

The zone ID is visible on the Overview page of your Cloudflare domain dashboard, in the right sidebar. It's not a secret - it's just an identifier for your zone, similar to an account number. Committing it to a public repository is fine.

Types for the Env interface regenerate automatically the next time you run npm run dev (the starter's dev script runs wrangler types before Astro starts). If you want to pick up the new variable immediately in your IDE without restarting the dev server - say you're editing runtime code that references env.CLOUDFLARE_ZONE_ID - run npm run typegen explicitly.

3. Create the API Token

Go to Cloudflare API Tokens and click Create Token. Either use the Cache Purge template directly, or create a custom token with the permission: Zone → Cache Purge → Purge. Scope the token to your specific zone, not "all zones."

Once the token is created, paste it into .dev.vars in your project root:

CLOUDFLARE_CACHEPURGE_API_TOKEN=<your-token>

.dev.vars is gitignored by default in this starter - verify it is in yours before pasting anything. A leaked Cache Purge token has a narrow blast radius (worst case: an attacker can briefly invalidate your cache), but leaking any token is still bad hygiene.

4. Deploy the Worker

npm run deploy

The Worker has to exist in Cloudflare's infrastructure before the first i18n:migrate can run. The migration script doesn't deploy the Worker itself - it only pushes data and purges cache. If there's no Worker there, there's nothing to purge from.

If your custom domain is already configured as a Worker route or custom domain binding, verify it's proxied (orange cloud in DNS). Without proxying there's no Cloudflare CDN layer in front of your Worker - the Cache API won't have anywhere to store entries, and the Purge API won't have anywhere to purge from. The migration script will still run, reporting successful KV updates and successful purge requests, but none of the caching behavior this architecture relies on will actually happen.

5. Register the Token as a Worker Secret

Even though the migration script doesn't need this, registering the same token as a Worker Secret means production runtime code can access it if you ever add a feature that needs to purge cache from inside a Worker:

npx wrangler secret put CLOUDFLARE_CACHEPURGE_API_TOKEN

Or, equivalently, through the Cloudflare dashboard: Worker → Settings → Variables and Secrets → Add.

This step is optional if you're sure you'll only ever purge cache from the migration script. But adding it now is free, and it means future-you has one less thing to debug when a webhook handler wants to invalidate a specific translation on content-change events from a CMS.

6. Run Your First Migration

npm run i18n:migrate

On the very first run, .i18n-hashes.json doesn't exist yet. The script treats every namespace as changed, pushes all translations to KV, and issues purge requests for every URL. The next request to your site populates the cache fresh. From this point on, every subsequent migration purges only the namespaces that actually changed.

If something goes wrong - missing credentials, network error, rate limit - the graceful recovery logic from the last section kicks in. KV will be updated (that part succeeds first), but the hash file will stay in its old state, so the next migration re-attempts the invalidation automatically. You just re-run i18n:migrate after fixing whatever was wrong.

DX Considerations for Translation Workflows

Beyond the setup checklist, there are a few ergonomic decisions baked into the implementation worth mentioning. None of them are architectural, but they add up to the difference between a starter you want to use and one that feels like homework.

Placeholder KV IDs work out of the box. A new developer cloning the repo can start working without creating a Cloudflare account first. wrangler.jsonc ships with "id": "your_kv_id_here", which Wrangler treats as a local folder name under .wrangler/state/. npm run dev uses Astro's Node.js dev server and doesn't touch Wrangler at all; npm run i18n:seed writes to that local folder via wrangler kv bulk put --local. Neither command needs a real KV namespace ID.

Three commands, each doing one thing. The package.json exposes:

"i18n:bundle":  "tsx scripts/bundle-translations.ts",
"i18n:seed":    "tsx scripts/bundle-translations.ts --deploy-version --local",
"i18n:migrate": "tsx scripts/bundle-translations.ts --deploy-version"

Same script, three different modes via flags. bundle generates artifacts only (useful for CI type checking). seed pushes to local KV. migrate pushes to remote KV and purges cache. No one has to remember which flag does what - the command names tell you.

--fallbacks as an opt-in. The compiled fallback dictionaries aren't generated by default because they add build time and bundle size, and most projects don't need the extra runtime safety net if KV is reliable. Append --fallbacks to any of the three commands to enable them, or set I18N_GENERATE_FALLBACKS=true in .dev.vars to always generate them. The fetcher checks for the generated file at runtime and uses it if present, so switching fallbacks on or off doesn't require any code changes.

Gitignore discipline. The starter's .gitignore excludes .dev.vars, i18n-data.json, src/i18n.generated.d.ts, and .i18n-hashes.json. All four are machine-local state or generated artifacts - committing them causes merge conflicts, accidental secret leaks, or stale type definitions in CI. The README documents this explicitly so new contributors don't "fix" it by removing entries they think are missing.

Non-fatal missing credentials. If CLOUDFLARE_ZONE_ID or CLOUDFLARE_CACHEPURGE_API_TOKEN are missing, the script logs a warning and continues without attempting the purge step. This is deliberate - sometimes you want to push translations without also invalidating (say, seeding a fresh namespace that doesn't have cache entries yet). The graceful recovery pattern means skipping purge doesn't corrupt state; it just means the hash file stays where it was and the next migration retries.

What the Full Setup Gives You

If you've followed the sequence above, you now have an operational setup where:

A non-developer on your team can update any JSON file in ./locales/** and trigger a migration themselves, without going near the deploy pipeline.
That migration pushes new content globally in about a second - the time it takes Cloudflare's Purge API to propagate.
Only the namespaces that actually changed get invalidated; everything else stays warm in cache.
The Worker itself never gets redeployed. It just keeps running, serving increasingly well-cached translations, and reading from KV only when content genuinely changes.

This is what decoupling translations from code deployments actually looks like in practice. It's not a single clever trick - it's a small constellation of platform features (KV, Cache API, Purge API, Worker Secrets, wrangler.jsonc vars) composed in a specific order so that each one carries exactly the weight it's designed for.

What I want to show next is what this costs and what it returns, in concrete numbers. It's one thing to say "zero KV reads on the hot path"; it's another to look at an actual production log and watch the arithmetic hold up.

Performance in Production: Real wrangler tail Logs

A good architecture survives contact with a production log. It's one thing to claim "zero KV reads on the hot path"; it's another to watch it happen, line by line, on a real deployment serving real traffic.

Let me walk through actual wrangler tail output from edgekits.dev - not cherry-picked best cases, just consecutive requests captured during normal use - and trace what each one cost in KV reads, cache lookups, and purge operations.

Steady-State Hot Path: Zero KV Reads

Here's what a warm cache looks like. Multiple users hitting different pages, all locales, all namespaces already populated:

GET https://edgekits.dev/en/legal/refund-policy/ - Ok @ 18:42:04
  (log) i18n cache FULL HIT { locale: 'en', namespaces: [ 'legal' ] }
  (log) i18n cache FULL HIT { locale: 'en', namespaces: [ 'landing' ] }
  (log) i18n cache FULL HIT { locale: 'en', namespaces: [ 'landing' ] }

GET https://edgekits.dev/de/legal/refund-policy/ - Ok @ 18:42:12
  (log) i18n cache FULL HIT { locale: 'de', namespaces: [ 'legal' ] }
  (log) i18n cache FULL HIT { locale: 'de', namespaces: [ 'landing' ] }
  (log) i18n cache FULL HIT { locale: 'de', namespaces: [ 'landing' ] }

GET https://edgekits.dev/de/legal/terms/ - Ok @ 18:42:16
  (log) i18n cache FULL HIT { locale: 'de', namespaces: [ 'legal' ] }
  (log) i18n cache FULL HIT { locale: 'de', namespaces: [ 'landing' ] }
  (log) i18n cache FULL HIT { locale: 'de', namespaces: [ 'landing' ] }

Every line starts with FULL HIT. No KV batch, no cache PUT. Three fetchTranslations calls per page - one in the layout for legal (legal pages pull a shared legal-copy namespace), two in subcomponents for landing (header and footer use landing namespace) - and every single one of them is served directly from the edge cache.

Total KV reads for this entire three-request sequence: zero. Each page is assembled from cache entries that were warmed minutes or hours earlier and haven't been invalidated since. This is the default cost of serving a request in steady state.

First-Touch Cache Warming Per Edge Node

When a request hits an edge node that hasn't served the requested locale before, the cache is cold for that locale. Here's what that looks like:

GET https://edgekits.dev/es/legal/refund-policy/ - Ok @ 18:42:31
  (log) i18n cache PARTIAL/FULL MISS { locale: 'es', hit: 0, miss: 1 }
  (log) i18n KV batch OK { locale: 'es', missingNamespaces: [ 'legal' ] }
  (log) i18n cache PUT scheduled { locale: 'es', missingNamespaces: [ 'legal' ] }
  (log) i18n cache PARTIAL/FULL MISS { locale: 'es', hit: 0, miss: 1 }
  (log) i18n cache PARTIAL/FULL MISS { locale: 'es', hit: 0, miss: 1 }
  (log) i18n KV batch OK { locale: 'es', missingNamespaces: [ 'landing' ] }
  (log) i18n cache PUT scheduled { locale: 'es', missingNamespaces: [ 'landing' ] }
  (log) i18n KV batch OK { locale: 'es', missingNamespaces: [ 'landing' ] }
  (log) i18n cache PUT scheduled { locale: 'es', missingNamespaces: [ 'landing' ] }

This is the first Spanish request on this edge node, and there's a detail worth noticing. The landing namespace shows three PARTIAL MISS and three KV batch OK entries - not one. Why?

Because this particular page has three components that independently call fetchTranslations(runtime, 'es', ['landing']): the header, a featured content block, and the footer. They all execute in parallel inside the same Astro SSR pass. All three check the cache simultaneously and all three miss simultaneously - because the cache hasn't been populated yet. All three then fetch from KV in parallel.

This is a one-time cost. Look at the very next Spanish request:

GET https://edgekits.dev/es/legal/delivery-policy/ - Ok @ 18:43:01
  (log) i18n cache FULL HIT { locale: 'es', namespaces: [ 'legal' ] }
  (log) i18n cache FULL HIT { locale: 'es', namespaces: [ 'landing' ] }
  (log) i18n cache FULL HIT { locale: 'es', namespaces: [ 'landing' ] }

All three FULL HIT. The parallel misses warmed the cache with three concurrent cache.put calls - the last one wins, they all wrote the same content anyway. From this request onward, every Spanish-locale page gets a free ride from cache until an explicit purge invalidates an entry.

Could we eliminate that parallel-miss cost? In principle, yes - a request-scoped memoization layer in Astro.locals would ensure only one component out of the three actually hits KV, and the others wait on its promise. But in practice this optimization doesn't earn its complexity.

The parallel miss happens once per locale per edge node, ever, until the cache is explicitly invalidated. Three KV reads at warmup time, in exchange for no request-scoped state to maintain, no additional abstraction between components and the fetcher. I chose to leave it as-is.

Mixed Traffic: Partial Cache Hits + KV Batch Fallback

Real traffic rarely hits the extremes of "all cold" or "all warm." Here's a more realistic mix - users bouncing between locales, where some namespaces are cached and others aren't:

GET https://edgekits.dev/es/ - Ok @ 18:45:13
  (log) i18n cache PARTIAL/FULL MISS { locale: 'es', hit: 1, miss: 3 }
  (log) i18n KV batch OK {
  locale: 'es',
  missingNamespaces: [ 'common', 'newsletter', 'messages' ]
}
  (log) i18n cache PUT scheduled {
  locale: 'es',
  missingNamespaces: [ 'common', 'newsletter', 'messages' ]
}
  (log) i18n cache FULL HIT { locale: 'es', namespaces: [ 'landing' ] }
  (log) i18n cache FULL HIT { locale: 'es', namespaces: [ 'landing' ] }

The homepage requested common, landing, newsletter, messages - four namespaces total. One of them (landing) is already cached from that earlier legal-page request; three aren't. The fetcher does exactly what you'd hope: PARTIAL MISS { hit: 1, miss: 3 }, one KV batch call for the three missing ones, one combined cache PUT for all three.

Note the KV batch. missingNamespaces: [ 'common', 'newsletter', 'messages' ] - three keys, one round-trip. This is why step 3 of the fetcher uses env.TRANSLATIONS.get(missingKvKeys, ...) with an array argument instead of calling .get() individually. Even with four namespaces, we never do more than one KV round-trip per page.

Granular Invalidation in Action: One URL Purged

Now the payoff. What happens when translations actually change?

This is from the migration script's console output after editing a single string in en/landing.json:

$ npm run i18n:migrate
[i18n] Changed namespaces (1):
  - en:landing
[i18n] Pushing translations to remote KV...
[i18n] ✅ KV updated (remote).
[i18n] Purging 1 cache entries via Cloudflare API...
[i18n] Purging cache for 1 URL(s)...
[i18n] [Chunk 1] Purged 1 URL(s).
[i18n] ✅ Cache purge completed.
[i18n] ✅ .i18n-hashes.json updated.

One URL. That's it. en:landing was the only pair whose content hash differed from the previous run, so only https://edgekits.dev/i18n%3Aen%3Alanding got invalidated. Every other locale:namespace combination - en:common, en:blog, de:landing, es:landing, ja:landing, and so on - remained warm in the cache everywhere in the world.

Immediately after that, the first user to hit the English landing page triggered a cold-cache response for exactly one namespace:

GET https://edgekits.dev/en/ - Ok @ 18:56:53
  (log) i18n cache PARTIAL/FULL MISS { locale: 'en', hit: 3, miss: 1 }
  (log) i18n KV batch OK { locale: 'en', missingNamespaces: [ 'landing' ] }
  (log) i18n cache PUT scheduled { locale: 'en', missingNamespaces: [ 'landing' ] }

hit: 3, miss: 1. Three of the four namespaces on this page - common, newsletter, messages - were still in cache, untouched by the migration. Only landing was missing, and only landing was re-fetched from KV. The re-fetch pulled the updated content, wrote it back to cache, and the next request saw the new text.

From the second request onward, everything was warm again:

GET https://edgekits.dev/en/ - Ok @ 18:57:51
  (log) i18n cache FULL HIT {
  locale: 'en',
  namespaces: [ 'common', 'landing', 'newsletter', 'messages' ]
}

The user who fixed the Spanish typo doesn't trigger cache invalidation for German users. Fixing German doesn't touch English. Fixing landing doesn't touch blog. This is what "granular" means in practice.

KV Reads and Purge Costs, by Operation

Let me total up the operational costs for a realistic workload. Assume a project with 5 locales and 10 namespaces (50 total locale:namespace pairs), traffic spread across a few dozen edge nodes, and translation updates happening a few times a week.

Serving requests (per edge node, steady state):

Zero KV reads per request. Bounded only by parallel cache lookups per namespace.
Per page: typically 3–4 parallel cache.match calls, all hitting local edge cache.

First request per locale per edge node (after a deploy or eviction):

One KV batch call with up to N keys, where N = number of missing namespaces (typically 3–5).
Parallel cache.put calls via waitUntil - doesn't block the response.

Translation migration (per i18n:migrate run):

One wrangler kv bulk put pushing all 50 key/value pairs to remote KV.
One Cloudflare Purge API call with 1–5 URLs (matching the number of namespaces that actually changed).
One local disk write for .i18n-hashes.json.

First request per locale per edge node after a migration that touched that namespace:

Same as first-touch warming, but scoped only to the invalidated namespace. Other namespaces stay cached.

Across a month of this workload, the KV read budget spent on actually-used data is dominated by first-touch warming - a few thousand reads total, depending on how many distinct edge nodes see traffic. Purge API calls total maybe 20–40 for the entire month. Nothing even approaches the free-tier ceiling on either metric.

What Changed Versus Part 1

For completeness, here's what the same workload cost under the old architecture:

Serving requests: same, zero KV reads on cache hit. No change.
First request per locale: one KV read, but for the combined namespace bundle under a versioned key. Any overlap between pages was cached separately (one cache entry for common,landing, another for common,landing,newsletter, another for just common). Cache footprint was larger than strictly necessary.
Translation update: required npm run i18n:migrate AND npm run deploy. The migrate step pushed to KV; the deploy step updated TRANSLATIONS_VERSION. Without both steps, users saw stale content.
Cache after update: every versioned cache entry for every locale-namespace combination became orphaned all at once. LRU eventually cleaned them up. Cache stampede on the first request to any page in any locale that hadn't been warmed under the new version.

The new architecture eliminates the deploy requirement, eliminates cache bundle duplication, and reduces the cache stampede from "every entry" to "only changed entries." Performance on the hot path is identical to the old one - both architectures deliver zero KV reads when the cache is warm. The improvement is entirely in the invalidation path, which happens at deploy time rather than at request time.

Which is, finally, what Part 1 promised.

Trade-offs & When to Use Which Approach

Software architecture writing has a bad habit of pretending there's one right answer. There rarely is. Part 1's content-hash approach and Part 3's explicit-purge approach are both valid - they just solve the same problem under different constraints, for different project shapes.

Rather than steer you toward one, let me describe the actual decision criteria I'd use myself. The two architectures live in two separate branches of the repo, and picking between them is a legitimate choice you should make consciously.

The Short Version

Use v1-version-based-cache when your situation has any of these properties:

You don't want to manage an additional Cloudflare API token.
Your translations rarely change - maybe once a month, or only at release time.
It's a solo project or a small team where "run two commands instead of one" isn't a real concern.
You're still in early development and just want something that works without additional configuration.

Use main (the Part 3 architecture) when:

You've got a custom domain proxied through Cloudflare (orange cloud DNS).
Translations change independently from code - content editors, translators, or a CMS pushing updates.
You want a non-developer to be able to deploy content changes without any help.
Translation update velocity matters enough that "seconds to propagate" is better than "wait for a deploy."
You plan to grow into a workload where avoiding redundant cache stampedes actually matters.

Axis 1 - Proxied Domain Requirement

Before we get to the axis that differentiates the two approaches, it's worth being clear about what they share. Both architectures need an orange-clouded (proxied) custom domain to perform any edge caching at all.

Cloudflare's Workers Cache API is tied to zone-level caching, which simply doesn't exist on *.workers.dev subdomains or on custom domains with grey-cloud DNS-only mode. In either of those configurations, cache.put silently discards, cache.match always returns undefined, and every request falls through to KV. This is true regardless of which branch you're on.

Where the two architectures diverge is what happens when you don't have that proxied domain.

For Part 1, it's mostly fine - the version-keyed caching doesn't fail, it just doesn't do anything. Translations are read from KV on every request, which is slower than a cache hit but correct. For a low-traffic preview or a pre-launch build, the KV free tier (100k reads/day) is generously more than you'll ever need.

For Part 3, the same is true for the Cache API, but the Purge API is an additional piece that also requires the proxied setup. Without it, i18n:migrate will happily run - it pushes to KV, reports a successful purge API call, updates the hash file - but none of that actually does anything to invalidate cache, because there's no cache in front of the Worker to begin with. The script doesn't know this. It just quietly produces a no-op where you expected surgical invalidation.

So if you know your domain won't be proxied any time soon, Part 3 isn't broken per se, but its signature feature is inactive. Either stick with the Part 1 branch (which doesn't depend on Purge API at all), or set I18N_CACHE=off and accept the slightly higher KV read volume in exchange for guaranteed freshness.

Axis 2 - Operational Complexity Tolerance

Part 3 requires more moving parts than Part 1 does. That's just true, and pretending otherwise would be dishonest.

Specifically, to adopt Part 3 you need:

A Cloudflare API token with Cache Purge permission on your zone.
That token stored in .dev.vars (which must be gitignored).
The zone ID in wrangler.jsonc as a Wrangler variable.
Awareness of what .i18n-hashes.json is and why it's gitignored.
Basic understanding of what the graceful-recovery pattern means, so that "purge failed, rerun migrate" doesn't panic you.

None of this is individually hard, but the sum is "about half an hour of additional setup, done once" on top of the baseline shared with Part 1. Both branches still need a KV namespace, a Worker deploy, and a proxied domain - Part 3 just adds a purge token, zone ID, and hash-file awareness on top.

For a solo project where you're both the developer and the content editor, that additional half-hour is real. It might be more than the entire translation-update time you'll spend all year. Part 1 is strictly simpler, and simpler is a valid choice when complexity doesn't earn its keep.

Axis 3 - Content Update Frequency

This is where the decision actually lives for most projects.

If translations change once a month on release day, the redeploy requirement of the Part 1 architecture is close to invisible - you're deploying anyway, whether for content or for code. Nobody on the team will notice the coupling because it mirrors their natural cadence.

If translations change weekly, the redeploy requirement starts feeling heavy. Not fatal, but it means every German typo fix requires running two commands and watching a deploy pipeline. Part 3 makes this one command.

If translations change daily - say, a marketing team adjusting hero copy, or a CMS with real content authors pushing updates - the Part 1 approach becomes actively painful. Every content tweak blocks on a deploy. Part 3 reduces this to a single command that takes seconds and affects zero production code.

There's also a second-order effect. When translation updates are cheap and decoupled, you start using them more. Small copy fixes that weren't worth a deploy become casual - a typo caught in a screenshot, a better phrasing proposed by a reviewer, an A/B test variant, a hero headline being retuned to match a new ranking keyword, a meta description being rewritten after a Search Console report.

The cost structure shapes behavior. Part 3 makes translation iteration cheap enough that you actually iterate - including the kind of continuous SEO-driven copy refinement that most projects silently abandon because "it's not worth redeploying for."

Axis 4 - Team Composition

Part 1's architecture has a hidden assumption baked into it: translations and code changes flow through the same deploy pipeline, which implies they flow through the same person or team. A content editor who can't deploy a Worker can't deploy a translation update either, because the Worker embeds the translation version.

For solo projects, this is fine. You wear both hats.

For two-person teams where both are developers, still fine.

For teams where content is owned by a non-developer - a copywriter, a translator, a product manager - Part 1's architecture doesn't scale. Either the non-developer needs deploy access they shouldn't have, or every translation change creates a deploy bottleneck for whoever does.

Part 3 solves this cleanly: the migration script is a command-line tool, and wrangler kv bulk put plus i18n:migrate can be triggered by anyone who has the tokens, independent of whether they ever touch the code.

If you plan to let a non-developer update translations, Part 3 is not an optimization - it's a prerequisite.

Axis 5 - Scale and Cache Bloat

At small scale this axis doesn't matter. At larger scale it starts to.

Part 1 caches translations under combined keys: every unique set of namespaces that any page requests becomes its own cache entry. A page pulling common,landing creates one entry. A page pulling common,landing,newsletter creates another. A page pulling just common creates a third. Same underlying translation data, three cache entries.

For a small site with a handful of page types, this duplication is invisible. For a site with many page types and many locales, the multiplicative effect starts to add up - you might have 5 locales × 20 distinct namespace-set combinations = 100 cache entries for content that fundamentally represents 5 × 10 = 50 unique namespace loads.

Part 3's per-namespace keys eliminate this duplication entirely. One cache entry per locale:namespace pair. Full stop. Cache footprint is predictable and scales linearly with locales × namespaces, not with page-template count.

This probably doesn't matter until you're running a content-heavy multilingual site with dozens of page templates. But when it does matter, Part 1 requires a painful retrofit to fix. Part 3 gets it right by construction.

Axis 6 - Recovery from Partial Failures

Both architectures handle KV failures gracefully via fallback dictionaries. Where they diverge is what happens when the invalidation step itself fails.

In Part 1, invalidation is implicit - change the content, the hash changes, old cache keys orphan. There's nothing to fail. If your i18n:migrate script errors out mid-run after pushing to KV, users start seeing new content on the next request via the new hash. No manual recovery needed.

In Part 3, invalidation is explicit via a Purge API call. That call can fail - rate limits, network errors, invalid token, zone misconfiguration. We built the graceful recovery pattern specifically to handle this: KV gets pushed first, hash file only updates if purge succeeds, so retrying i18n:migrate replays the same invalidation automatically. But it's still an extra failure mode to reason about, and an extra thing to check in your operational runbook.

If your project has strict uptime and observability requirements and you're running this at scale, Part 1 is simpler to operate. Fewer moving pieces means fewer things to page you in the middle of the night.

Choosing Between Content-Hash and Purge API Architectures

Honestly, for a solo indie project just getting started, I'd probably still reach for the Part 1 architecture first. It's ~20 lines of additional setup to eliminate, and it lets you ignore an entire category of operational concerns.

Later, when the project has scale and a content workflow that justifies the complexity, you can migrate to Part 3 - the branches exist in the same repo and the migration is small and localized.

Start with the simpler one. Upgrade when you actually need to.

The reason I ended up shipping Part 3 for edgekits.dev is that I knew the content workflow I wanted - non-developer updates, fast iteration, a path toward real content management - was incompatible with the redeploy requirement. For that specific project, Part 3 wasn't optional.

For your project, the answer depends on which of the six axes above dominate your constraints. The nice thing about having both branches is that you don't have to commit to the answer before building anything. Pick the simpler one, build, and switch later if the axes shift.

Conclusion

Three articles in, let me step back and look at what the whole arc has actually been about.

Part 1 argued that translations are data, not code, and proposed an architecture that moved them into KV and cached them at the edge.

Part 2 extended that philosophy to user-facing forms and their server-side error pathstranslated content flowing through validation, through API responses, through locale-aware error codes, all without client-side i18n bundles.

And Part 3, as it turned out, was about finishing what Part 1 started.

Because I had moved translations into KV, I genuinely believed I had separated them from code. But the cache invalidation layers small, technical-looking detail I didn't think much about at the timekept them coupled.

Every content edit still required a code deploy, because the thing that told the cache "this content is stale" lived inside the code. The philosophy was right. The implementation didn't fully live up to it.

The resolution, once I found it, came from a small reframing. Not "how do I make the cache key reflect content changes?"which led me through three architectures that each had their own regression. But "how do I delete specific cache entries when content changes?"

That framing pointed directly at a Cloudflare primitive I'd been ignoring: the Purge API. And once I started treating invalidation as an explicit operation on data rather than an implicit consequence of cache-key rotation, the coupling dissolved. Not moved. Dissolved.

The Pattern Underneath: State Lifecycles on the Edge

I think there's a generalizable insight here, and it's less about i18n and more about how we reason about state at the edge.

When you first start building on Workers, you tend to think of caches and KV and env vars as interchangeable places where state can live. You pick whichever one "feels right" for a particular piece of data. But each of these layers has a specific purpose that matches a specific lifecycle, and fighting that alignment produces subtle couplings you don't notice until you try to evolve the system.

Environment variables are for how the Worker is configured. They live with the Worker. They change when the Worker changes.

KV is for durable data that the Worker reads. It lives independently of the Worker. It can change without the Worker knowing.

The Cache API is for transient acceleration. It's downstream of KV. It gets populated by the Worker and exists to save network round-trips.

If you store versioning information in an env var, you're saying "this version is part of the Worker's identity"and you'll pay for that every time the version should change without the Worker's identity changing. If you store content in an env var, you're saying "this content changes at the same rate as my code"which is true for feature flags, maybe, but wrong for translations.

The refactor in this article was, underneath the surface detail, really an exercise in putting each piece of state in the right layer and letting the platform's natural lifecycles handle propagation. Content goes in KV. Configuration stays in env vars. Cache entries are downstream of both. Invalidation is an explicit operation between them, not a byproduct of key naming.

Once the pieces sit in their right layers, the whole system composes cleanly.

What "Data, Not Code" Actually Means

The original claim from Part 1 was that translations should be data, not code. That's a slogan. Part 3 made me articulate what it actually means operationally:

The format in which content is stored doesn't require recompilation to update. (KV stores JSON. Editing JSON isn't "changing the code.")
The pathway through which content propagates doesn't intersect the code deploy pipeline. (A translation update calls wrangler kv bulk put, not wrangler deploy.)
The invalidation signal that tells downstream caches to refresh is itself data, not code. (A Purge API call triggered by a script, not a new hash baked into a bundle.)
The lifecycle of the content is independent of the lifecycle of the Worker. (The Worker runs for weeks while translations update daily beneath it.)

All four bullets have to be true simultaneously for "data, not code" to be more than an aspiration. Part 1 delivered the first two. Part 3 delivered the other two. You need all four before non-developer teammates can actually own translations without needing a developer.

What Comes Next

There's a larger question humming underneath this article, and I'm going to name it rather than hide it: what else in a typical SaaS is quietly shipped as code when it should be shipped as data?

Feature flags. A/B test variants. UI copy outside the i18n system. Pricing configurations. Error message templates. Marketing banners. Onboarding step sequences. Email templates.

All of these routinely live in code repositories, get deployed alongside features, and create the same kind of subtle coupling between product changes and engineering cycles that I just spent 8,000 words untangling for translations.

I don't have a general solution to offer heredifferent types of data have different invalidation patterns, different consistency requirements, different audiences. But the framework I arrived at for i18n static cache keys, explicit invalidation, graceful recovery, per-item granularityseems to generalize.

A future post might walk through how the same patterns apply to feature flags, or to lightweight CMS-backed content. We'll see.

For now, what I can offer is this: if you've been accumulating that vague sense of "deploys are weirdly tangled up with content operations on our project," you're probably not imagining it.

The tangle is usually real. And it's usually fixable by asking a simple question for each piece of data in your system - "what's its natural lifecycle, and which part of my platform is designed for exactly that?" - and then storing it there, directly, instead of cramming it into whichever place was convenient at the time.

Thank You For Reading

This has been a long series. Thank you for sticking with it.

If you build something on this stack, I'd love to hear about it. And if you found these articles useful, a star on the repo is always appreciated - it's not something I chase, but it genuinely feels good to see one land. The code from both architectures is open source:

The main branch of astro-edgekits-core contains the Part 3 architecture described here.
The v1-version-based-cache branch preserves the Part 1 architecture, which remains a legitimate choice for the use cases outlined in the trade-offs section.

More deep dives are already brewing - this stack has a lot of surface area and I want to keep covering it properly rather than hand-waving at the interesting parts. What comes next will depend on where the starter kits land and what the most common friction points turn out to be in practice.

For now, go ship a German typo fix without redeploying ;)

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.

The continuation is here: how to completely separate translation from code deployment on Cloudflare Workers. Per-namespace cache keys and the Purge API for granular, instant i18n updates.

Read Part 3: Stop Redeploying to Update Translations here.

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.

Parts 2 and 3 is out! 🚀

You can read 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.

How to completely separate translation from code deployment on Cloudflare Workers. Per-namespace cache keys and the Purge API for granular, instant i18n updates.