Start a Shopify hreflang audit by comparing your Markets and language settings with the alternate URLs delivered on real storefront pages. Shopify normally generates tags for a Markets-based Online Store theme, so adding another snippet can create the problem you are trying to fix. The useful question is whether the generated relationships match the localized pages you actually intend to publish.
These seven checks connect settings, page content, tag ownership, and public responses. They apply primarily to Shopify Online Store themes. A custom Hydrogen storefront needs its own routing and metadata verification; use the separate Shopify Hydrogen SEO checklist for that implementation. The examples below are illustrative, not results from a tested merchant store.
1. Match each market to a distinct public URL
A market in Shopify admin is not automatically a separate page that Google can show. If two customer groups use exactly the same URL, changing currency or market context does not create two hreflang destinations. Shopify's international SEO documentation says automatic alternates are generated for markets with distinct domains, subdomains, or subfolders.
Open Markets, select the relevant market, and inspect its domain and language configuration. Record what is assigned, not what the market name suggests. A market named “United Kingdom” does not establish that /en-gb/ exists, and a folder name alone does not prove which language-region code the page should declare.
Also inspect inherited settings. Shopify documents that submarkets inherit domain and language settings from their parent unless customized. A new submarket can therefore continue using an existing URL structure. Use the actual domain and language assignment rather than creating a second URL in your audit spreadsheet merely because you added a country.
Build a small configuration record before collecting tags. This example describes an invented store:
| Market | Language | Assigned public base | Expected relationship |
|---|---|---|---|
| United States | English | https://example.com/ |
US English resource URL |
| United Kingdom | English | https://example.com/en-gb/ |
A distinct UK English resource URL |
| France | French | https://example.com/fr-fr/ |
A distinct French resource URL |
| Another market sharing the US base and language | English | https://example.com/ |
Verify the shared configuration; do not invent another destination |
Check the active configuration and open the assigned URL directly. Record the market, language, domain, whether settings are inherited, and the intended public resource. Domain connections or assignments that differ from the plan belong with the person managing Markets, before anyone changes theme code.
A useful result is a verified mapping between market settings and real URLs. This is not a recommendation to create a separate domain or folder for every country. Only publish distinct versions when they serve a real localized experience that your team can maintain.
2. Check published languages and equivalent resources
Confirm that each intended language is published and assigned to the right domain. Adding a language, translating content, and publishing that language are different actions. Shopify's language-management guidance explains these states and notes that a language can be published even when translations have not been added.
That distinction matters during an audit. A French URL and a French hreflang label do not prove that the product description is in French. Read the actual page, including the main product information, availability, and the customer's next step. Record untranslated or outdated content separately from a malformed tag. Hreflang does not translate the page.
Then map equivalent resources at page level. For a product, connect that product's localized versions rather than three pages that happen to use similar paths. For a collection, verify the collection's purpose and destination. If a resource is not offered in a market, do not substitute the homepage or an unrelated collection simply to fill an alternate slot.
A fictional product map might look like this:
| Resource | Locale | Expected localized URL |
|---|---|---|
| Travel mug | en-US |
https://example.com/products/travel-mug |
| Travel mug | en-GB |
https://example.com/en-gb/products/travel-mug |
| Travel mug | fr-FR |
https://example.com/fr-fr/products/gobelet-voyage |
The French handle differs intentionally. Shopify supports translated URL slugs, so replacing a domain or adding a folder to an English path is not enough to establish the correct destination. Start with the localized resource that the storefront actually serves. For separate Shopify stores, maintain an explicit cross-store equivalence map; do not assume resource IDs or handles are shared between stores.
Sample more than the homepage. Include a product with a translated handle, a collection, a content page, and a resource missing from one market. These cases expose different mapping failures without requiring an arbitrary page-count target.
If an alternate unexpectedly loads English content, distinguish missing translation from a wrong market assignment or redirect before changing tags. If the resource is intentionally absent, record that absence and keep it out of the expected equivalent set. The passing condition is a real, appropriate localized destination, not a spreadsheet with every cell filled.
3. Identify the system that owns hreflang output
Inspect the complete HTML head before adding or removing anything. Shopify's theme developer guidance says native Markets tags are added through content_for_header, rendered inside the head of layout/theme.liquid. Not finding literal hreflang tags in the theme editor does not establish that the public page lacks them.
List every possible source: Shopify's automatic output, custom Liquid, an app, and any separate-store integration. Compare the entries each source produces. Repeated identical entries are a maintenance warning; the more serious conflict is one language-region label pointing to different destinations or an old generator continuing to reference retired URLs.
| Current arrangement | What to establish before a change |
|---|---|
| Native Markets output only | Does the public set match the actual Markets and language assignments? |
| Native output plus theme or app tags | Which source is responsible for each entry, and which source will remain complete? |
| A custom implementation with native output disabled | Does it cover every intended resource, self-reference, and return relationship? |
| Separate regional Shopify stores | Who maintains the cross-store resource map and changes on every store? |
Shopify currently documents an Automatic hreflang tags control under Online Store > Preferences. If a theme or app supplies a complete alternative implementation, the native generator can be disabled to avoid competing output. That is a conditional ownership decision, not the first step for every store with an audit warning. Keep a record of the current setting and prove the replacement's coverage before switching responsibility.
If you return to native generation, remove the custom output and ensure the app or theme will not add it again, following Shopify's current instructions. Do not remove content_for_header to eliminate hreflang. That object is the theme integration point, not an isolated hreflang snippet; changing it is a much broader action than resolving duplicate tags.
For an agency handoff, ask for the name of the active generator, its resource-mapping source, the setting it relies on, and the person responsible for updates. “An SEO app handles it” is not enough evidence. The passing result is one coherent implementation whose ownership and output you can explain, even if several systems contribute other unrelated head elements.
4. Verify the full page-level alternate relationship
Collect the tags from every page in one equivalent set, not just from the primary-market homepage. Google's localized-version guidelines call for fully qualified alternate URLs, a reference to the page itself, and return relationships between the relevant versions.
For the fictional travel-mug map above, the expected alternate set could be:
<link rel="alternate" hreflang="en-US"
href="https://example.com/products/travel-mug">
<link rel="alternate" hreflang="en-GB"
href="https://example.com/en-gb/products/travel-mug">
<link rel="alternate" hreflang="fr-FR"
href="https://example.com/fr-fr/products/gobelet-voyage">
<link rel="alternate" hreflang="x-default"
href="https://example.com/products/travel-mug">
This is an illustrative expected-output fixture to compare against all three product pages. It is not code to paste globally into theme.liquid: those literal product URLs would be wrong on other resources, and native Shopify tags may already be present.
Read the set in both directions. The US page should reference the UK and French equivalents; those pages should reference the US version and the other intended equivalents. Each should also include itself under its applicable language or language-region label. If one relationship is missing, record that specific pair and inspect its generator. Do not infer that every hreflang annotation on the entire site has failed. Google's guidance allows it to process reciprocal relationships in an incomplete larger set.
Check labels against the actual market and content. en-GB identifies English for the United Kingdom; en-UK is not the correct country-code form. A region alone is insufficient, and a broad market name such as “Europe” is not a hreflang value. Codes are case-insensitive, so lowercase en-gb alone is not a defect. A language-only label can be appropriate where the configured audience is not country-specific.
Review x-default as a fallback journey rather than another language. Google's guidance supports it for unmatched users; it is not a mandatory extra localized page. Shopify documents a native x-default pointing to the primary domain. Inspect the actual resource-level destination before adding anything, and do not insert a competing tag merely because an older guide says Shopify lacks one.
Finally, confirm the alternate link elements appear in a valid HTML head. A language switcher's visible links help customers, but do not by themselves prove the hreflang annotation set is correct. Save the complete set and its source URL so you can distinguish a configuration error from a stale or partial inspection.
5. Check destination status, canonical and indexing policy
Open every declared alternate directly. A correctly formatted tag can still point to a redirect, a missing product, a login page, or the wrong resource returning HTTP 200. Confirm both the response and the main content before calling the target valid.
If you use a terminal with curl, this read-only request saves the response headers and HTML without automatically following redirects. Replace the illustrative address with a URL from your own inventory:
curl -sS --max-time 20 \
-D headers.txt -o page.html \
https://example.com/fr-fr/products/gobelet-voyage
Inspect the status and any Location header first. When a URL redirects, follow the destination separately and record both addresses. Update the responsible mapping to the intended final localized resource rather than hiding the redirect chain in the audit. A successful command is not evidence that the returned page is the correct product.
Review the canonical URL alongside the hreflang destination. Shopify documents self-referencing canonicals for distinct market versions. If the French product unexpectedly canonicalizes to an English product, compare the actual head with native output, theme overrides, and app output. Do not immediately remove every cross-region canonical: an intentional consolidation policy for substantially similar same-language pages needs to be understood before it is changed. Google's canonical guidance treats canonicalization as a separate set of signals.
Check HTML robots directives, X-Robots-Tag, and crawl access. A public language page that is deliberately noindexed is not ready to be treated as an intended search destination merely because it has hreflang. Google's noindex documentation also explains that a crawler must be able to fetch the page to read that rule. A robots.txt block is not proof that a URL has been removed from search.
Use URL Inspection for the individual URL's indexed evidence and, where appropriate, a live fetch. The indexed report can show Google's selected canonical; a live test cannot predict that selection. A live pass also does not validate all return links in your cluster or guarantee indexing.
Keep the causes separate in the record: response failure, wrong resource, canonical-policy mismatch, or indexing restriction. An out-of-stock product is not automatically a missing URL. Inspect the actual storefront state instead of applying a blanket rule based on inventory status. Screpy's canonical tag troubleshooting guide covers the broader diagnosis when canonical signals conflict.
6. Separate customer routing from crawler access
A customer changing countries in the storefront and a crawler requesting a localized URL are different journeys. Inspect both without assuming that one proves the other.
Shopify's current Markets documentation says its native automatic redirection applies to customers while known search-engine crawlers are excluded. A normal visitor being redirected therefore does not, by itself, show that Google cannot reach the original market URL. An app, custom theme script, or external redirect rule may behave differently from Shopify's native handling.
Compare these situations for a representative product:
| Request or journey | What to record |
|---|---|
| Direct visit to the localized URL | Final resource, language, market and any redirect |
| Country or language selector | Whether it reaches the equivalent resource and an available language |
| A repeat visit with a saved preference | Whether the remembered choice explains the route |
| Available search-engine fetch evidence | Whether that specific URL can be fetched and which content is returned |
Shopify's domain-and-language guidance explains that requested language, current language, and the domain's default can affect selection. For example, a target domain that does not offer French cannot be assumed to preserve a French-language journey. Check the configured choices before treating the switcher's behavior as a broken hreflang tag.
If all direct links collapse to one market, identify which rule performs the redirect. Google's multi-regional site guidance warns that automatic routing can prevent access to alternate versions. Apply that concern to the behavior you can establish, while accounting for Shopify's documented crawler exception.
Do not “prove” Googlebot access by changing only the user-agent string in a request. That does not make the request an authenticated Google crawler. Likewise, a country-specific customer test or VPN result answers a customer-routing question, not whether Google has indexed every locale.
The passing condition is that customers can choose a usable localized experience and the intended search destinations remain accessible to the relevant crawler. If custom routing blocks that access, send the exact source URL, redirect destination, rule owner and fetch evidence to the responsible team. Avoid changing native settings merely because one ordinary visitor request redirected.
7. Recheck after market, language and theme changes
Shopify updates native hreflang when market domains or languages change. That automation does not replace checking whether your new configuration matches the intended storefront. Keep a short regression set so the team can compare the same resources before and after a change.
Revisit the fixture when you:
- Add, deactivate, or reorganize a market and its inherited domain settings.
- Publish or unpublish a language, or change its domain assignment.
- Translate or rename a resource handle.
- Change which products or collections are available to a market.
- Update the theme, translation integration, or custom hreflang generator.
- Change a domain or redirect policy.
Include a translated product, a collection, a content page, and the missing-market case used earlier. Compare the emitted labels and destinations, then open the target URLs again. Test at least one return relationship from the affected locale back to an unchanged locale. A homepage-only check can miss a product mapping broken by a handle change.
Treat unpublishing as a URL change with consequences. Shopify says links to an unpublished language return 404 and that the language is removed from its assigned domains. Its domain guidance also notes that deactivated market subfolders can stop working. Check existing references and the planned redirect destinations; do not leave retired URLs in a custom alternate set simply because they worked in the last audit.
Read the current sitemap for each relevant public domain and follow its listed child sitemaps. Compare the intended public resource URLs with what Shopify exposes. If you also use sitemap-based hreflang annotations, compare those relationships with the page evidence. Sitemap inclusion and an alternate declaration are different things; record which one you actually verified.
Google supports HTML, sitemap and HTTP-header annotation methods without a Search advantage from maintaining all three. Do not add a second custom system just to make an audit look more complete. Investigate unexpected omissions at the responsible configuration or generator instead.
Save the change date, affected resource set, before-and-after evidence, and unresolved differences. A later search-result change is a separate observation: it does not prove the tags caused a ranking movement, and corrected tags do not establish when Google will recrawl or display a different URL.
Keep a Shopify hreflang evidence record
Use one row per observed resource and locale. Copy this CSV header into a spreadsheet and keep the captured head, response and relevant settings with the record:
checked_at,store,market,language,resource_key,expected_url,requested_url,final_url,http_status,declared_hreflang,declared_alternates,canonical_url,robots_state,generator,settings_reference,return_pair_checked,issue,owner,next_action
Use a resource key your team can reconcile, not a guessed cross-store ID. Record missing values as unknown. A field left unverified should not become a green “passed” result because another page in the market worked.
Route each issue to the layer that can resolve it:
| Evidence | Likely starting owner or investigation |
|---|---|
| A market shares an unintended URL or language assignment | Markets configuration owner |
| A language is unpublished or content is untranslated | Localization and publishing owner |
| Two sources emit conflicting destinations | Theme/app owner coordinating with native-tag settings |
| One translated handle maps to the wrong resource | Resource-mapping owner |
| A destination redirects, is unavailable, or contradicts indexing policy | Storefront, domain, or SEO policy owner |
| A change leaves stale custom alternates | The generator owner named in the change record |
These are starting points, not diagnoses established by a single tag. Resolve the cause, then rerun the affected resource set and its return links. Keep customer language access, canonical selection, indexing eligibility and actual search performance as separate observations.
This guide uses current Shopify and Google documentation, with illustrative URL maps and audit records. It was researched and drafted with AI assistance and automated checks; it does not report a hands-on test of your store or an independent human review. The focus is the Shopify-specific path from settings to public hreflang. For wider store issues beyond that path, use the Shopify SEO guide.