Hreflang sitemap example: two language pages, checked end to end

A complete two-page example

Suppose a fictional service has an English page and a French page that offer the same service to different language audiences. The URLs below are examples, not live Shipwork pages. Both sitemap records list both versions, and each record’s <loc> identifies the page that record describes.

<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:xhtml="http://www.w3.org/1999/xhtml">
  <url>
    <loc>https://example.test/en/guide/</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.test/en/guide/" />
    <xhtml:link rel="alternate" hreflang="fr" href="https://example.test/fr/guide/" />
    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.test/en/guide/" />
  </url>
  <url>
    <loc>https://example.test/fr/guide/</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.test/en/guide/" />
    <xhtml:link rel="alternate" hreflang="fr" href="https://example.test/fr/guide/" />
    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.test/en/guide/" />
  </url>
</urlset>

The xhtml namespace declaration belongs on the enclosing urlset. The alternate links sit inside each URL record. The English record points to itself and French; the French record does the same. Here, x-default deliberately falls back to the English page. It could instead point to a language selector or another suitable fallback if that better serves visitors with no matching version.

These pages should be genuine equivalents, not unrelated pages grouped because they share a template. Google’s guidance describes hreflang as a way to identify alternate language or regional versions, and asks each version to include itself and its other versions. See Google’s localized-versions guidance. An annotation helps search systems understand the relationship; it does not guarantee that a particular page will be shown or indexed.

Plan the URL set before generating XML

Most avoidable mistakes start in the source list, so make that list reviewable before turning it into markup. For every page family, record the locale code, the canonical live URL, and the person or rule that confirms the page is a real equivalent.

Before generating, check four things:

• Codes describe the page. Use a language code when the content is language-specific and add a region only when the page targets that region. Avoid inventing codes for internal market names.
• URLs are final and canonical. Prefer the public HTTPS URL that returns the intended page, not a staging address, tracking URL, redirecting alias or URL that canonicalises elsewhere.
• The content is equivalent. A translated page can differ in wording and examples; it should still answer the same basic need. A language homepage is not automatically an alternate for every product detail page.
• The fallback has a reason. Choose an x-default destination intentionally. Do not treat it as another language code.

Shipwork’s hreflang generator accepts one code and URL per line and produces both page-head tags and a sitemap fragment, adding x-default to the first URL when you omit it. It generates a fragment for the submitted set; it does not discover all translated pages, edit your sitemap, or build every URL record in a large sitemap for you. For two pages, use the generated alternate set in both records as shown above.

Add entries without losing sitemap coverage

Put each record in the sitemap file that already lists its <loc>, or in the relevant child sitemap if your index points to several files. Keep the URL list and alternate set together in the system that builds the sitemap, if possible. That makes a future translation launch less likely to add the new page in one place and omit it from the others.

For a small hand-maintained sitemap, compare each new record against a checklist. For a generated sitemap, update the data source or template that emits URL records, then rebuild. Avoid appending a lone fragment to an unrelated file: XML must remain well formed, the namespaces must be declared, and the sitemap index must still reference the child sitemap that contains the pages.

If you use page-head annotations as well, keep the page tags and sitemap declarations aligned. Google documents HTML, HTTP header and sitemap methods; using one method consistently is usually easier to maintain than two copies of the same relationship. If your implementation has both, verify both after a deployment rather than assuming one updates the other.

Verify the live relationship, not just the file

Run this review after publishing and whenever a locale is added, removed or moved:

1. Fetch the public sitemap and confirm it returns successfully with parseable XML and the expected namespaces.
2. Find every localized <loc>. Confirm its alternate set contains every intended locale, itself, and the same fallback decision.
3. Request each alternate URL. It should resolve to the intended page without an unexpected redirect, error, or conflicting canonical.
4. Compare the page’s rendered or raw annotations with the sitemap set if you use both methods.
5. Repeat for a sample from each relevant child sitemap and make sure the sitemap index still exposes those files.

A compact review log makes follow-up easier: keep the sitemap file, locale set, date checked, URLs sampled, and any exception beside the deployment note. If a locale page redirects to a replacement, update the alternate set to the final URL rather than preserving the old address as if it were a live version. If a page is intentionally retired, remove it from all alternate sets and the sitemap, then confirm the remaining language pages still reference one another. This turns a one-time markup review into a repeatable release check.

Use the hreflang sitemap check to inspect sitemap declarations and compare them with page information, then use the reciprocal hreflang check for page-level return links. These checks can reveal mismatches in the URLs they inspect; they cannot establish that a search engine has indexed a page or will choose a particular regional result. For a broader sitemap fetch problem, start with the sitemap check.

The useful working artifact is not only the XML. Keep the reviewed locale-to-URL list beside the sitemap build process. When a translator or product team adds a version, update the set, regenerate or rebuild every affected entry, and run the same live checks again.

Questions

Keep reading