Forem: Gary Stupak

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.

Read Part 3: Stop Redeploying to Update Translations here.

Get the Code

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

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

Forem: Gary Stupak

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

Untangling Translations from Deployments: What We'll Build

Anatomy of Translation-Deploy Coupling

How TRANSLATIONS_VERSION Behaves in Production

The Mental Model Mismatch

What Decoupling Translations Actually Requires

First Attempt - Version Variable via wrangler deploy --var

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

How wrangler.jsonc Overwrites CLI Variables

Why This Approach Can't Work

Translations as First-Class KV Citizens

The First Implementation

The Hot Path Regression

Attempting to Cache the Version Too

The Free Tier Math

The Double Cache Lookup Problem

Stepping Back

The Breakthrough - Static Keys + Explicit Invalidation

The New Cache Key Shape

What the Hot Path Looks Like Now

How Do Translation Updates Reach Users Without Key Rotation?

Cloudflare Purge API - The Missing Piece

How Purge-by-URL Works

Rate Limits and How They Affect Us

The Proxied-Domain Requirement

API Token and Zone ID Setup

Why Purge API Fits Edge Cache Invalidation

Incremental Purging - The Hash File Strategy

Why "Purge Everything" Causes a Cache Stampede

What "Changed" Actually Means

Where the Hash File Lives

The Full i18n:migrate Invalidation Pipeline

Rate Limit Arithmetic (Revisited)

What This Gives Us

Implementation Walkthrough

The Keys Module

The Fetcher

The Migration Script

Loading .dev.vars Manually

Computing Hashes and Diffing

The Purge API Call

Updating the Hash File (Carefully)

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

Production Setup & DX Considerations

1. Create the KV Namespace

2. Add the Zone ID to wrangler.jsonc

3. Create the API Token

4. Deploy the Worker

5. Register the Token as a Worker Secret

6. Run Your First Migration

DX Considerations for Translation Workflows

What the Full Setup Gives You

Performance in Production: Real wrangler tail Logs

Steady-State Hot Path: Zero KV Reads

First-Touch Cache Warming Per Edge Node

Mixed Traffic: Partial Cache Hits + KV Batch Fallback

Granular Invalidation in Action: One URL Purged

KV Reads and Purge Costs, by Operation

What Changed Versus Part 1

Trade-offs & When to Use Which Approach

The Short Version

Axis 1 - Proxied Domain Requirement

Axis 2 - Operational Complexity Tolerance

Axis 3 - Content Update Frequency

Axis 4 - Team Composition

Axis 5 - Scale and Cache Bloat

Axis 6 - Recovery from Partial Failures

Choosing Between Content-Hash and Purge API Architectures

Conclusion

The Pattern Underneath: State Lifecycles on the Edge

What "Data, Not Code" Actually Means

What Comes Next

Thank You For Reading

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

Under the Hood: The Subscription Flow Stack

The Bottleneck: Zod i18n and Client Bundle Bloat

Zero-JS Validation: Error Codes as a Domain Contract

Step 1: Strict Literal Types

Step 2: Zod Speaks in Codes

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

Loading `.dev.vars` Manually

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

Astro Actions Error Handling & The `DomainContext` Pattern

The `DomainContext` Solution

The Component: `FieldErrorLocalized`

Safe Interpolation: The `fmt()` Helper