- Start with the storefront’s country-and-language URL contract.
- Generate canonical and alternate pages from the same source as routing.
- Only publish sitemap URLs that return a complete, indexable page.
- Treat CMS overrides as governed editorial decisions.
- Detect sudden sitemap loss and keep the last known good route list.
Medusa knew commerce; it did not own the public URL policy
The project combined Medusa products and categories with CMS documents, translated application pages and country-language routes. The client needed one publishing decision across canonical URLs, alternate pages, environment indexing and the sitemap. A correct product record alone cannot tell a crawler which market URL should rank.
We built that SEO projection in the TanStack Start storefront: route-aware metadata, environment guards and a sitemap federating static, commerce and editorial sources. The same market model now informs the customer route and the signals presented to search engines.
The business problem behind international SEO
An international shop may show similar products in several countries and languages. Search engines need to know which page is intended for which audience, which version is the preferred address and which alternatives belong together. If those signals disagree, the wrong market can appear in search, duplicate pages can compete and valuable products can disappear from the index.
The solution begins before metadata. The storefront must first define what a URL means. If /be/fr/product means the French-language Belgian offer, routing, prices, availability and content must all honour that promise. SEO tags cannot repair a page that says Belgium in its address but resolves French prices or an unsupported catalogue.
Canonical, alternate pages and sitemap in plain English
A canonical address tells search engines which URL the business considers the main address for this page. Alternate-language and market links tell them where equivalent pages for other audiences live. The sitemap is the list of pages the company actively wants crawled. These are three views of the same publishing decision, not independent files assembled by different teams.
If a URL appears in the sitemap but points canonically somewhere else, the business sends mixed instructions. If alternate links mention a market route that redirects or returns no product, the relationship is false. We generate these signals from the same market-and-route contract used by the application, then verify the rendered pages rather than trusting string-building helpers.
Decide what deserves its own search page
Not every combination of filters, sorting and market state deserves indexation. Product, category and editorial pages usually have deliberate search value. Thousands of faceted catalogue combinations can create thin, duplicate or empty pages. The business needs a policy for which combinations are curated landing pages and which remain useful to customers but are not indexed.
The same applies across markets. A product unavailable in Belgium should not appear in the Belgian sitemap merely because it exists in the global catalogue. A translated page with no local offer may not deserve to compete. SEO architecture should project commercial truth: supported market, published content, reachable route and an indexation decision owned by the business.
Give editors control without allowing accidental damage
Editors sometimes need to point similar content to one preferred page. A CMS-managed canonical can support that decision, but a typo or external URL can redirect search value away from an entire page family. The safe rule is to accept only relative URLs or absolute URLs on the storefront’s configured production origin, validate their form and make overrides visible in editorial review.
An override should carry a reason, author and review date. It must not quietly contradict routing or alternate-page relationships. Editorial freedom works best inside a clear safety boundary: the CMS can choose among valid public destinations, while code prevents malformed, private or external targets from entering the published metadata.
A broken data source must not erase the site overnight
Sitemaps often combine pages from commerce and the CMS. If one source becomes unavailable, the publishing process must not quietly replace a valid catalogue with an incomplete list.
A production policy can retain the last known good route manifest, compare every new generation and alert on an unexpected drop. Fallback country and language values must remain visible to operators instead of masquerading as current business configuration. Search engines may take time to rediscover removed URLs, so one empty generation can have consequences long after the technical error is fixed.
Test the pages search engines will actually receive
After generating the sitemap, request every listed URL from the built application. It should return 200 without a redirect, declare itself indexable, use the expected canonical and render the correct country and language. Titles and descriptions should be present and sufficiently distinct. Alternate links should point to valid equivalents, including a sensible default where the strategy requires one.
This end-to-end gate catches problems that helper tests cannot: a route that redirects, a product missing in one market or metadata that changes during server rendering. The final HTTP response is what search engines consume, so that is where the publishing contract must be verified.
A practical international SEO checklist
Define supported country-language routes and derive canonical, alternate and sitemap output from that definition. Include only complete, public, indexable pages. Govern CMS overrides. Prevent preview hosts and private routes from appearing. Compare sitemap size with the last successful build and investigate large changes before deployment.
After launch, sample each route family and market, then feed search-console duplicate and coverage reports back into the same ownership process. International SEO becomes manageable when it is treated as a tested projection of the commerce system—not a set of tags added after the storefront is finished.
Common questions
It is the address the business declares as the preferred version of a page when several URLs contain the same or very similar content.
No. Include deliberate, valuable landing pages. Keep unlimited or thin filter combinations functional for users but govern their indexation separately.
Alert or block the release, compare with the last known good manifest and avoid publishing a suddenly incomplete sitemap as if it were valid.