- Country, language and commercial market answer different questions.
- The page URL should make the chosen country and language clear.
- A customer’s explicit choice must win over automatic detection.
- Changing country requires rechecking delivery, tax and payment assumptions.
- Fallbacks should help the customer choose, not silently invent a market.
The client needed more than a language selector
A French-speaking visitor may shop in Belgium rather than France. The client therefore needed URLs, explicit preferences and geolocation to resolve one supported commercial country without letting browser language invent currency or delivery rules. A country change also had to reconsider cart state rather than merely swap a flag.
Medusa regions supplied the commercial configuration once a country was known. They did not define the TanStack Start routing contract, the precedence between URL, saved choice and geolocation, or the cart migration experience. We built those storefront and backend transitions, including validation against configured regions, address and shipping cleanup, and dependent cache refresh.
Three choices that are often confused
Language answers ‘which words should we display?’ Country answers ‘where is the customer shopping or receiving the order?’ Market answers ‘which commercial rules apply?’ A market can control currency, price lists, taxes, payment methods, delivery options and product availability. These choices influence one another, but they are not interchangeable.
Belgium makes the distinction obvious. A customer may choose Belgium as the delivery country and French or Dutch as the language. France and Belgium can both use euros while having different delivery methods, legal text or product availability. Guessing country from language would send some Belgian customers into the French market and show a checkout that looks translated but is commercially wrong.
What goes wrong when they are combined
The visible symptom may be a language switch that unexpectedly changes prices. More serious effects appear later: tax calculated for the wrong country, a pickup method offered where it is unavailable, an address rejected, or a payment option disappearing at the final step. Analytics also become unreliable because the company cannot distinguish language preference from market demand.
Search engines need the distinction too. If several URLs show different market versions, each page must state which audience it serves and how it relates to alternatives. A locale code such as ‘fr’ is not enough to describe a French-language page for Belgium versus France. The URL contract should make the commercial context understandable to customers, developers and crawlers.
Put the explicit choice in the URL
We prefer a route that carries both country and language, such as /be/fr/ or /be/nl/. A shared link then opens the same intended market and language on another device. The server can resolve prices and content correctly before the browser loads, avoiding a flash from one market to another.
The exact format is less important than consistency. Every link, redirect, canonical tag and sitemap entry must interpret it the same way. Unsupported combinations should lead to a clear choice or a documented redirect, not an invisible default. Older language-only URLs need one migration rule so they do not become a second, competing routing system.
Respect the customer before guessing
When resolving the storefront state, an explicit country and language in the URL should win. Next comes a choice the customer previously saved. Browser language or approximate location can help suggest an option only when no explicit choice exists. Automatic detection is a convenience, not authority.
This priority prevents the website from fighting the customer. Someone travelling abroad, using a corporate network or buying for another country may not match their IP address. If the desired combination is unsupported, explain what is available. A good fallback says ‘we do not currently deliver there; choose another country’. A bad fallback silently moves the customer to a plausible market and lets them discover the mismatch during payment.
Changing country is more than changing a flag
A country change can invalidate delivery methods and addresses already attached to the cart. The server clears country-dependent delivery state while the client refreshes market data before the customer continues.
The transition revalidates region, currency, prices, taxes, inventory visibility, shipping, pickup location, promotions and payment assumptions. Material changes should be shown before checkout continues. A selector that only swaps a flag leaves hidden commercial state behind and can fail much later in the journey.
Test combinations, not isolated selectors
Test one language across two countries and two languages within one country. Open a shared URL in a clean browser. Change country with products in the cart, a delivery method selected and payment started. Confirm that server rendering and browser state agree, and that the old market does not flash before the new one.
Also test conflicts: URL says Belgium, saved preference says France and location suggests Germany. The URL should win. Test unsupported country-language pairs and customers with no usable signal. These scenarios prove the decision order. A collection of unit tests for separate cookie and URL helpers does not prove that the customer experiences one coherent market.
The international storefront checklist
Document country, language and market as separate fields. Decide which combinations are supported and who owns the mapping. Put explicit choices in stable URLs. Let customer intent beat automatic detection. Recheck the entire cart when country changes. Keep routing, canonical pages, alternate-language links and sitemaps derived from the same contract.
For leaders, the practical question is not whether the site has a language selector. It is whether every customer sees one internally consistent commercial offer—from landing page to payment—while still being free to choose their language. That is the difference between translation and international commerce architecture.
Common questions
No. The same language is used in several countries, and one country may support several languages. Market should be resolved from an explicit country or commercial choice.
It makes links shareable, supports correct server rendering and gives search engines an unambiguous description of the intended audience.
Re-evaluate region, prices, taxes, shipping, pickup, promotions and payment. Remove or replace choices that are no longer valid and explain material changes.