Geotargeting a Headless Site: URL Structure and Locale Routing on Headless CMS
Most multilingual sites break in the same quiet way. The content is translated, the locales are live, the launch goes fine. Six months later, international organic traffic still hasn’t moved. Google is serving the German page to Austrian users, the French-Canadian audience keeps landing on France content, and half your locales barely register in non-US search results. The translation was never the problem. Two architecture decisions have an outsized effect on whether a multilingual site is discoverable in the markets it is built to serve: how locale URLs are structured, and what happens when a visitor lands on a version that may not match their location or language. Neither should be treated as an afterthought. Decide both alongside the CMS locale model before launch, and you give search engines stable, crawlable signals to work with. Leave them until implementation and you can end up with perfectly translated content that is unnecessarily difficult for Google and users to reach.
your CMS localizes content, but URL structure and locale routing are front-end and CDN responsibilities, and international SEO lives or dies on getting them right.
The Two Decisions Your CMS Won’t Make for You
Two things decide whether a multilingual site ranks in its target markets, and neither is a CMS setting: how you structure your locale URLs, and how you route the visitor who lands on the wrong one. Settle both together, before launch, and international SEO tends to work. Leave either to chance and it usually doesn’t.
A headless CMS is exceptionally good at modeling and delivering localized content. It can store locales, manage translations and fallbacks, and expose that content cleanly through APIs. But in a decoupled architecture, the CMS does not inherently control the production URL a visitor requests or the edge behavior that occurs before the page is rendered. Those decisions usually belong to the front end, routing layer, or CDN—which is precisely why multilingual architecture on a headless stack needs to be designed as a system rather than treated as a CMS configuration exercise.
Those are the two decisions that determine whether search engines and international audiences ever find your localized content:
URL structure: do your locales live at example.com/de-de/, de.example.com, or example.de? This choice sends the geographic signal itself, and it is close to permanent once you launch.
Locale routing: when a visitor or a crawler arrives, do you auto-redirect them by IP, or serve what they asked for and suggest an alternative? Get this wrong and you hide your own content from Google.
Neither is a CMS setting. Both are delivery-layer architecture. And unlike content, which you can re-translate, they are expensive to reverse once you launch.
URL Structure: Subdirectory vs Subdomain vs ccTLD
There are three ways to structure locale URLs, and the trade-off is the same one every time: consolidated ranking authority versus the strength of your country signal. The more clearly a URL says “this is for Germany,” the more you fragment the domain authority that helps it rank at all.
| Dimension | Subdirectory example.com/de-de/ | Subdomain de.example.com | ccTLD example.de |
|---|---|---|---|
| Geographic signal | Limited; locale targeting relies on surrounding signals such as hreflang, localized content and site context | Limited; the subdomain label can communicate intent to users, but Google still relies on broader locale signals | Strong; a country-code domain is an explicit country-targeting signal |
| SEO consolidation | Usually simplest to manage within one domain and internal-linking ecosystem | More operational separation; Google can treat a subdomain as a distinct site in some contexts | Separate domain requiring its own crawling, links, measurement and market-level SEO management |
| Implementation cost | Lowest: one property, one codebase | Moderate: DNS plus separate properties | Highest: registration, hosting, legal per country |
| Best fit | Most enterprises expanding by language | Distinct regional sites, separate infra | Strong local brand or legal need per market |
Subdirectories are the strongest default for many enterprise multilingual builds, particularly when the same brand, content platform and engineering organization serve every market. They keep localized experiences within one domain, simplify analytics and governance, reduce infrastructure duplication, and make it easier to manage internal linking and hreflang as one system. Google explicitly supports subdirectories for multi-regional sites, and on a headless stack they also let teams keep one composable delivery architecture while varying content by locale. Unless a market has a genuine operational or commercial reason to behave like a separate web property, that simplicity is difficult to beat.
Subdomains make more sense when regions genuinely need architectural separation: different regional teams, distinct applications, separate infrastructure, or materially different experiences. Google supports subdomains for regional sites, and they provide clean technical separation, but that separation also creates more properties, configuration and governance to manage. If the organization is really operating one global digital platform, a subdirectory structure is usually simpler.
ccTLDs make sense when a business deliberately wants each market to operate as a country-specific web property—for example, because the local domain has meaningful brand value, the market has distinct commercial or regulatory requirements, or the regional business operates independently. Google treats country-code domains such as .de as a strong country-targeting signal. The trade-off is operational: example.de, example.fr and example.co.jp are separate domains that each need their own technical governance, measurement, linking strategy and ongoing SEO investment. That can be entirely justified for a mature local business; for one global brand expanding its content footprint, it is often unnecessary complexity.
Why You Can’t “Fix It Later” in Search Console
Google deprecated the International Targeting report in 2022 and removed it from Search Console after September 22, 2022. The old country-targeting control is gone; there is no longer a Search Console dropdown where you can simply tell Google that a particular web property is intended for Germany.
Without that manual Search Console setting, Google has to infer regional relevance from the site itself: country-specific domains where applicable, locale-specific URLs, hreflang, localized page content, links and other market signals. That makes architecture harder to compensate for after launch. At EIGHT25, that is why we lock the locale model, URL pattern and hreflang strategy together during discovery, before the front end turns those decisions into thousands of production URLs. On a headless build, the freedom to design the delivery layer is an advantage—but only if that layer is designed deliberately.
Locale Routing: Why Forced Geo-IP Redirects Put International SEO at Risk
The single most common self-inflicted wound on a multilingual site is the automatic geo-IP redirect: detect the visitor’s country from their IP address, and bounce them to the matching locale. It feels helpful. It is the fastest way to make your other languages invisible to search engines.
The reason is how Googlebot crawls locale-adaptive sites. Google’s default crawler IP addresses appear to be based in the US, and its standard crawl requests do not send an Accept-Language header. Google also performs geo-distributed crawling from IP addresses outside the US, but it explicitly warns that locale-adaptive delivery can still result in some regional content not being crawled, indexed or ranked. If every US request is automatically pushed to /en-us/, you are therefore making discovery of your other locale URLs less reliable than it needs to be.
Google does use geo-distributed crawling in addition to its default US-based crawler addresses, so an international site is not necessarily seen only from the United States. But Google still recommends separate locale URLs rather than relying on locale-adaptive delivery, precisely because it may not discover every variation consistently. A crawl from a different geographic IP is useful additional coverage; it should not be the mechanism your international architecture depends on.
The user-experience damage is just as real:
- A visitor who wants the English page, say a German speaker who prefers English technical docs, gets forced into German with no obvious way back.
- Shared and bookmarked links break, because the URL someone sends gets overridden by the recipient’s IP.
- VPN and corporate-proxy users get routed to the wrong market entirely.
- The redirect strips the visitor’s actual intent: they asked for a specific URL, and you overrode it.
What to Do Instead: Suggest, Don’t Force
The fix is not “never use the visitor’s location.” It is to treat location as a suggestion the user can decline, and to never let it override an explicit request. The pattern that works, and that keeps search engines seeing everything:
- Serve the requested URL, always. If someone (or Googlebot) requests /de-de/pricing, serve exactly that. No redirect.
- Suggest, don’t redirect. On first visit, if the visitor’s Accept-Language header or IP suggests a better locale than the one they landed on, show a dismissible banner (“View this page in German?”), not a 302.
- Persist the explicit choice. Once a user picks a locale, store it (cookie or equivalent) and honor it on return. An explicit choice always outranks an inferred one.
- Exempt crawlers by never depending on redirects at all. Because you are suggesting rather than redirecting, Googlebot sees whatever URL it requests, which is the whole point.
The routing logic, decided per signal, looks like this:
| Incoming signal | What most teams do | What actually works |
|---|---|---|
| IP geolocation | 302 redirect to country locale | Optional dismissible suggestion banner |
| Accept-Language header | Redirect to matching language | Pre-select the banner suggestion |
| Explicit user selection | Sometimes ignored on next visit | Persist and honor on every return visit |
| Any direct URL request | Location-based redirect overrides the requested locale | Serve the requested locale URL consistently, whether the requester is a user or crawler |
Where this logic runs matters. In a headless architecture, locale information originates in the content model, but routing does not have to be coupled to the CMS. The front end can know which variants exist, while lightweight location detection and suggestion behavior can be handled at the edge where appropriate. On the 10-language estate mentioned earlier, EIGHT25 implemented region routing, redirects and related edge behavior through Akamai rather than embedding it in the CMS. That separation is one of the useful properties of a headless stack: editorial localization stays in the content platform, while request-time delivery rules can evolve independently at the front end or edge.
Where the Two Decisions Meet
URL structure and locale routing should be designed as one system, and hreflang is one of the mechanisms that connects them. Each annotation identifies a real URL intended for a particular language or language-region audience. Those URLs need to be crawlable, internally consistent and available without location-based behavior unexpectedly replacing the requested locale.
A coherent setup for a subdirectory build looks like this:
| Locale | URL | hreflang | Routing behavior |
|---|---|---|---|
| English (default) | example.com/en/ | en, plus x-default | Served as-is; suggested to unmatched visitors |
| German (Germany) | example.com/de-de/ | de-de | Served on request; suggested to DE visitors via banner |
| French (Canada) | example.com/fr-ca/ | fr-ca | Served on request; never auto-served from fr-fr |
| Japanese | example.com/ja/ | ja | Served on request; suggested to JP visitors via banner |
Three rules make the setup more reliable: give every locale a stable, crawlable URL; keep hreflang annotations valid and reciprocal across the relevant locale set; and do not let location-based routing unexpectedly replace a locale URL that was explicitly requested. When those signals disagree, Google has less reliable information for choosing the appropriate regional version. That is when symptoms such as a German page appearing for Austrian searches or a French-Canadian audience reaching France-focused content become more likely.
This is also where the real trade-off sits. If your organization genuinely runs independent regional businesses with separate teams, budgets, technology or legal requirements, a subdomain or ccTLD architecture can accurately reflect that boundary. If you are one brand expanding a shared digital platform into additional languages and markets, subdirectories combined with stable locale URLs and suggest-don’t-force routing are usually the simpler architecture. On a headless platform, that model is especially attractive because the same structured content and delivery foundation can support additional locales without creating a separate web stack for every market. The mistake is not choosing one URL model over another; it is choosing without modeling the operating structure first and discovering the mismatch after thousands of URLs are live.
Frequently Asked Questions
Should I use a subdirectory, subdomain, or ccTLD for a multilingual website?
For many enterprises expanding the same brand into additional languages and markets, subdirectories (example.com/de-de/) are the most practical default because they keep the experience on one domain and are comparatively simple to operate. Subdomains are useful when regions need meaningful technical or organizational separation. ccTLDs (example.de) provide the clearest country-specific domain signal and can make sense when a market operates as a distinct local web presence, but they also increase infrastructure and governance requirements.
Do geo-IP redirects hurt SEO?
They can. Google’s default crawler IP addresses appear to originate in the US, and Google warns that location- or language-adaptive delivery may prevent it from crawling, indexing or ranking all localized versions. Google therefore recommends avoiding automatic redirects between language versions. A safer pattern is to serve the requested locale URL and offer a dismissible suggestion when another version may be more appropriate.
Can I set country targeting for my subdirectories in Google Search Console?
No. Google deprecated the International Targeting report in 2022 and removed it after September 22 of that year. Google still uses signals from the site itself—including country-specific domains where applicable, locale-specific URLs, hreflang, localized content and other market signals—to understand regional relevance. That makes the URL and localization architecture important to establish before launch rather than something that can be corrected later with a Search Console setting.
Does a headless CMS like Contentful or Contentstack handle geotargeting and URL routing?
Not by themselves. Platforms such as Contentful and Contentstack provide the content model and localization capabilities that underpin a multilingual experience, but a headless implementation still has to translate that locale model into public URLs, hreflang output and request-time routing behavior. Those concerns are typically implemented across the front end and, where useful, the edge/CDN layer. The benefit of headless is that those delivery decisions can be designed independently instead of being constrained by a CMS-rendered page system.
Who can architect a multilingual, geotargeted site on a headless CMS?
Look for a partner that treats the CMS locale model, URL structure, hreflang, front-end rendering and locale routing as one architecture rather than five separate implementation tasks. EIGHT25 brings that delivery-layer perspective from enterprise headless work across Contentful and Contentstack, including multilingual estates spanning thousands of pages and up to 19 languages. As a Contentful solution partner and Contentstack partner, the team can evaluate the content model and the delivery architecture together instead of optimizing one in isolation.
Planning a Multilingual or Geotargeted Build?
If your team is architecting a multilingual site—or trying to understand why an existing one is not reaching the markets it was built for—the useful first step is a locale, URL and routing audit before scope is fixed. At EIGHT25, we map the headless CMS locale model to the URL structure, hreflang, front-end behavior and edge routing as one delivery architecture. That is where headless pays off: the content platform can stay clean and reusable while the experience layer is designed around the markets, search requirements and routing behavior the business actually needs. It is far easier to make those decisions in discovery than after thousands of localized URLs have shipped.