Edge Localization and Geo-Routing for PADI Properties

About 250 countries group into 12 to 15 regions. A region carries one currency, one unit system, and one default language. It is all one JSON file with a version number, published to npm and Composer so every stack uses the same names.

• Several countries can share one region. Monaco uses France. A country we have not listed falls back to default. Most countries should not have a region of their own.
• The language list is global, not per region. Each region only names its defaultLanguage. The per-region languages list is there for real exceptions such as padi.cn; if a region does not have one, it serves every language. Matching against Accept-Language follows BCP-47, so zh-Hans and zh-Hant stay separate, and so do pt-BR and pt-PT.
• Units belong to the region, which is how we describe the metric and imperial split in one place.

CI checks the file on every change, which is what makes it safe for people outside the platform team to edit. It checks that the file matches the schema; that every ISO country code is either mapped or listed as deliberately left on the default; that each defaultLanguage is one the region actually serves; that language tags and currency codes are valid; that each dedicated domain belongs to exactly one region; and that every region-and-language page is one the redirect rules will leave alone.

Every real page URL names both the region and the language. A URL with only the region, such as /be, cannot be a page: two visitors who want different languages would share one cached copy and one search result.

A link that names a region but no language is not redirected. It renders in that region's default language with a canonical tag pointing at the proper URL, so old links and hand-typed addresses keep working without adding another kind of redirect.

Every step except 3 happens inside the Worker with no network calls. Step 3 is the only one that reads from a database, and it is deliberately the only one that does not run at the edge. That is decision D7, and it is why this service has no dependencies.

Five teams will read this, so it is written as a rule rather than a description. Anything vague here becomes a different bug on each site.

Three details are easy to miss and expensive to miss. Check the method, because a 302 on a POST quietly throws away the body. Use 302 and not 301, because browsers and proxies cache a permanent redirect and it is very hard to take back. And do it in one step: going from / to /be to /nl-be/ would charge the visitor twice for the arrival cost in section 11, for nothing. ?__geo=XX forces a country outside production; in production it needs a signed value with an expiry.

This is the contract every site codes against. It is the same in all three transports.

Three ways to receive it, all carrying the same data: x-padi-* request headers; a JSON block added to <head> after the cache read; and GET /_padi/locale for clients with no Worker in front of them.

Two rules keep this workable as sites deploy on their own schedules. Only add, never change: headers are never removed or reused, and x-padi-config-version says which version arrived. Every site works without us: if the headers are missing, show the worldwide region rather than an error. The Worker is an improvement, never a requirement.

Everything above describes what the service does. These eleven decisions say why it is built that way, and this is where most of the risk sits. Each one names the alternative we rejected, so a future reader can tell whether something has changed enough to reopen it.

Cloudflare already handles TLS for these sites, so the Worker runs inside something that is already happening. It adds no extra network hop.

The redirect is the cost, not the Worker, and it only happens when someone arrives at a root. The gap between the last two rows is a reason to prefer paths over country domains, which points the same way as D3. The site should get faster overall. This design pushes us to make HTML cacheable at the edge, which saves 200 to 800 ms on a cache hit. That only works if the origins send cacheable headers, and Next.js does not by default. These are estimates, not measurements.

Workers are covered by our Enterprise agreement rather than the public per-request plan, so what needs checking is volume against the contracted allowance, not list prices. The reason to skip images and scripts at route level is the twenty-fold jump in the last row — headroom and blast radius, not the bill. Cost should not drive any decision here. Cache hit rate and search indexing are where the real money is. Tiered Cache is included with Enterprise. The one commitment that still costs real money is the Cloudflare China Network, a separate subscription on top of Enterprise (D11).

D10 says nothing may break the page. That is only reassuring if we say exactly what the degraded version looks like.

• HighIf a redirect ever gets cached, everyone served by that Cloudflare location goes to the wrong region.Put no-store on every redirect, audit the Cache Rules, and add a test that checks the root is never served from cache.
• HighThe site root becomes a redirect, which changes what ranks on our strongest URL.Crawlers get a normal page with x-default; people get a redirect. That is defensible, but one address now answers two ways. SEO needs to sign this off properly, not glance at a diagram.
• HighChina depends on an ICP filing, not on engineering.It needs a Chinese legal entity, JD Cloud content vetting, and usually four weeks or more. Workers do run on the China Network, but it is a separate subscription and has no Tiered Cache, so that region will run colder than the rest.
• MediumSeveral hundred versions of each page, and too many hreflang tags to fit in the head.Most traffic hits a few of them and the rest stay cold on purpose. Tiered Cache wins back a lot everywhere except China, which does not support it, and we watch the hit rate per version. Publish hreflang through XML sitemaps built from regions.json so the two cannot drift apart.
• MediumWithout cookies, a visitor who is not logged in is redirected from the root every single visit.They have to bookmark the region URL or use the banner each time. Logged-in visitors are fine through D7.
• MediumThe sites drift apart, or work out geography for themselves anyway.Drupal geolocation modules and framework language detection will fight the edge and give different answers. Find them and turn them off site by site during rollout.
• LowVPN, corporate proxy, and satellite users are put in the wrong place.Location data is right about 99% of the time overall, but consistently wrong for these. confidence flags them, and the switcher is the way out. Never trap someone in a region.
• LowAn IP address is personal data under GDPR, and the banner can shift the page as it loads.Log the region we worked out rather than the IP, check the session-token approach with legal, and leave space for the banner so nothing jumps.

Because nothing ever looks broken, monitoring is not optional here. It is the only way we find out.

Testing, most useful first:

• A fixture listing all ~250 country codes and the region each should get. When someone edits the config, the diff on this file is what gets reviewed, which is what makes it safe for people outside the platform team to change it.
• Property tests: whatever the inputs, the language we return is always one we support, and changing the language never changes the region, currency, or units.
• A loop check: for every region-and-language page the rules leave it alone, and every redirect lands on one of those pages in a single step.
• A contract test on each site, with all headers present, all headers missing, and an unknown region. The missing-headers case is the one that actually breaks in production.
• Synthetic checks from several places: the right redirect from each, no-store on every redirect, complete hreflang in the sitemaps, and a second request served from cache.

Rollout goes in four stages, and none of them changes behaviour at the same time as adding something. Stage 0, two weeks: the Worker works out the answer, logs it, and sets the headers. No redirects, no site reads them. Visitors see no difference, and the traffic-per-region numbers are the cheapest place to catch a country mapped wrong. Stage 1: sites start reading the headers and the banner appears, each on its own schedule. Stage 2: turn on redirects, one region at a time. Stage 3: serve China from inside China, once the ICP filing is done. Start that filing now, because nothing in engineering makes it faster.

Beyond those tests, we will know it works when:

• The Worker only runs on pages. Images and scripts do not show up in the request counts, and 99th percentile CPU stays under 2 ms in production.
• The site root is never served from cache, and a POST to it is never redirected.
• Search engines get a normal page at the site root and at each region root, and no version is left out of the index.
• Every site still renders the worldwide region correctly with all x-padi-* headers missing, and origins reject those headers unless they come from Cloudflare.
• ?__geo=FR behaves the same locally as in production.
• Someone has actually used the kill switch and it restored the old behaviour without a deploy.
• A logged-in visitor whose saved region differs from their location lands in the right place, with no database read at the edge.
• Over two weeks, real-user data shows time to first byte improving per region on cache hits, with no drop in LCP for people arriving at a root.

• GoodOne definition of region, currency, units, and language for every site, changed through code review, with nothing new in the request path and nothing new that can fail.
• GoodPages become cacheable at the edge, and each language gets its own URL — so every version can be cached, indexed, shared, and remembered without storing anything on the visitor's device.
• BadVisitors who are not logged in get redirected from the root every visit, and we cannot remember when they chose otherwise.
• BadEvery site has to adopt the same names and the same URL format, and adding a region now needs a deploy and a loop check.
• NeutralWe will run two edge platforms sharing one function. The store keeps full control of pricing and tax; this layer only suggests what to display.

The Worker is how we deliver this, not what it is. Splitting the work in two lets sites Cloudflare does not sit in front of still get the right answer. This is the same split D11 uses for China:

Only the country lookup differs by platform: cf.country on Cloudflare, CloudFront-Viewer-Country on CloudFront, X-Akamai-Edgescape on Akamai, geo.country_code on Fastly, or a local MaxMind-style database on a plain server. Everything after that is shared.

• Tier 3 works because the browser goes through Cloudflare even when the page did not. The script reads ?padi_locale=nl-be off the incoming link and only calls the endpoint for direct arrivals. That endpoint must be no-store: one URL, but the answer depends on who is asking, so caching it hands the first visitor's country to everybody at that location. Client-side is the ceiling — currency labels, units, and the switcher, never the whole page language.
• Tier 4 uses the region already stored and never works it out again. A confirmation email sent three days later from a different datacentre must arrive in the language the customer actually bought in.
• If we control the DNS, put the site behind Cloudflare and it becomes tier 1, which is easier than building a tier 2 integration. Keeping the tiers consistent is the real work: publish decide() to npm and Composer, test once per tier rather than once per site, and run a nightly check asking every site which region it thinks it is in.