Guides

Building International SEO with open-source tools

This guide outlines the technical implementation of International SEO for modern web applications. It focuses on establishing a scalable URL architecture, automating hreflang tag injection, and managing edge-level geo-targeting to ensure search engines correctly index and serve region-specific content.

4-6 hours6 steps
1

Select and Implement URL Structure

Choose between subdirectories (example.com/de/), subdomains (de.example.com), or ccTLDs (example.de). For most SaaS applications, subdirectories are recommended as they consolidate domain authority and simplify SSL management. Configure your framework to handle locale prefixes in the routing logic.

next.config.js
// next.config.js example for subdirectory routing
module.exports = {
  i18n: {
    locales: ['en-US', 'fr-FR', 'es-ES', 'de-DE'],
    defaultLocale: 'en-US',
    localeDetection: false
  },
};

⚠ Common Pitfalls

  • •Using URL parameters (example.com?lang=fr) which are often ignored or poorly indexed by search engines.
  • •Mixing subdomains and subdirectories, which splits link equity.
2

Automate Hreflang Tag Injection

Every localized page must contain <link rel="alternate"> tags in the <head> that point to all other language versions of that page, including a self-referencing tag. This prevents duplicate content issues and helps Google serve the correct version to the user.

head-metadata.html
<!-- Example for a page available in EN and FR -->
<link rel="alternate" hreflang="en-US" href="https://example.com/en-us/product" />
<link rel="alternate" hreflang="fr-FR" href="https://example.com/fr-fr/product" />
<link rel="alternate" hreflang="x-default" href="https://example.com/en-us/product" />

⚠ Common Pitfalls

  • •Forgetting the self-referencing tag, which can invalidate the entire hreflang set.
  • •Using relative URLs instead of absolute URLs in the href attribute.
3

Configure the x-default Tag

The x-default hreflang attribute signals to search engines which version of the page should be shown to users who do not match any specified language/region. This is typically your global landing page or your primary market version.

⚠ Common Pitfalls

  • •Pointing x-default to a page that forces a redirect based on IP, which can prevent crawlers from accessing the content.
4

Generate Multi-Language XML Sitemaps

Instead of a standard sitemap, generate a sitemap that includes xhtml:link attributes. This provides a secondary signal for language relationships and is more efficient for large sites than head-tag injection alone.

sitemap.xml
<url>
  <loc>https://example.com/en/page</loc>
  <xhtml:link rel="alternate" hreflang="de" href="https://example.com/de/page"/>
  <xhtml:link rel="alternate" hreflang="en" href="https://example.com/en/page"/>
</url>

⚠ Common Pitfalls

  • •Inconsistent data between the XML sitemap and the HTML head tags.
  • •Exceeding the 50,000 URL limit per sitemap file when multiplying pages by locales.
5

Implement Edge-Level Redirects and Geolocation Headers

Use a CDN like Cloudflare to detect user location via IP and inject headers (e.g., cf-ipcountry). Use this data to suggest a locale change via a UI banner rather than forcing an automatic redirect, which can frustrate users and block search bots.

worker.js
// Cloudflare Worker snippet
addEventListener('fetch', event => {
  const country = event.request.headers.get('cf-ipcountry');
  // Logic to append a recommendation header or cookie
  event.respondWith(handleRequest(event.request));
});

⚠ Common Pitfalls

  • •Hard-redirecting users based on IP, which prevents Googlebot (mostly crawling from US IPs) from seeing your international content.
  • •Failing to cache the page correctly when varied by country headers.
6

Validate via Search Console International Targeting

After deployment, use the International Targeting report in Google Search Console to monitor for 'no return tags' errors. This confirms that your cross-page references are correctly reciprocated across your locale-specific URLs.

⚠ Common Pitfalls

  • •Ignoring errors in Search Console for more than 48 hours, as incorrect hreflang can lead to rapid de-indexing of regional variants.

What you built

Successful international SEO implementation relies on maintaining strict consistency between your URL structure, HTML metadata, and XML sitemaps. By automating the generation of these signals and avoiding forced redirects, you ensure that both users and search engines can navigate your global content efficiently.