Alternate Language URLs and Hreflang for Jekyll SEO

By -

Why Alternate Language URLs Matter for SEO

When you offer the same content in multiple languages, search engines must understand which version to show to which user. Mismanaging this can cause duplicate content issues, indexing of the wrong version, or missed opportunities in international search rankings.

To address this, you should implement a robust system of alternate language URLs using structured routing and the HTML hreflang tag in your Jekyll site.

Step 1: Define Language-Specific URLs

The best practice is to have separate URLs for each language version. For example:

  • /en/guide/getting-started/ – English version
  • /es/guide/getting-started/ – Spanish version
  • /fr/guide/getting-started/ – French version

This ensures each language is treated as a unique document by Google, which is essential for proper indexing and ranking.

Configure Permalinks in Front Matter

Inside your content file, define a language-specific permalink:


lang: en
permalink: /en/guide/getting-started/

Do the same for the translated version:


lang: es
permalink: /es/guide/getting-started/

Step 2: Link Alternate Versions with Hreflang

The hreflang tag tells search engines which versions of a page exist for which languages or regions. Add the following in your Jekyll layout head:

{% raw %}
{% assign translations = site.pages | where:"ref", page.ref %}
{% for trans in translations %}
  <link rel="alternate" hreflang="{{ trans.lang }}" href="{{ site.url }}{{ trans.url }}" />
{% endfor %}
{% endraw %}

This assumes each translated file shares a ref identifier in its front matter, such as:


ref: guide-getting-started

Example Output


<link rel="alternate" hreflang="en" href="https://example.com/en/guide/getting-started/" />
<link rel="alternate" hreflang="es" href="https://example.com/es/guide/getting-started/" />
<link rel="alternate" hreflang="fr" href="https://example.com/fr/guide/getting-started/" />

Step 3: Include x-default Hreflang

To guide users when no specific language match is found, include an hreflang="x-default" entry:

{% raw %}
<link rel="alternate" hreflang="x-default" href="{{ site.url }}/" />
{% endraw %}

Step 4: Localized Navigation Using URLs

Make sure your navigation links respect the user's language and don't break context. For example, use:

{% raw %}
<a href="{{ site.baseurl }}/{{ page.lang }}/about/">About</a>
{% endraw %}

Step 5: Localized Canonical Tags

Each language version should define itself as canonical to avoid conflicts:

{% raw %}
<link rel="canonical" href="{{ site.url }}{{ page.url }}" />
{% endraw %}

Step 6: Build a Language Switcher Component

Create a simple language switcher to help users navigate between translations:

{% raw %}
<div class="lang-switcher">
  {% assign translations = site.pages | where:"ref", page.ref %}
  {% for trans in translations %}
    <a href="{{ trans.url }}">{{ trans.lang | upcase }}</a>
  {% endfor %}
</div>
{% endraw %}

Style it with basic CSS to make it user-friendly.

Step 7: Declare Site Language in HTML Tag

For accessibility and SEO, declare the page’s language in the HTML tag of your layout:

{% raw %}
<html lang="{{ page.lang }}">
{% endraw %}

Use Case: International Developer Documentation

Imagine you manage documentation for an open-source framework. You offer it in English, Japanese, and German. With correct hreflang tags and language URLs, a user from Japan sees the Japanese version in search results, while a US-based user sees the English version — no duplicate content issues and optimal regional indexing.

Bonus: XML Sitemap with Multilingual Support

Enhance your sitemap to include alternate links using a custom XML generator:

{% raw %}
{% for page in site.pages %}
  <url>
    <loc>{{ site.url }}{{ page.url }}</loc>
    {% assign translations = site.pages | where:"ref", page.ref %}
    {% for trans in translations %}
      <xhtml:link rel="alternate" hreflang="{{ trans.lang }}" href="{{ site.url }}{{ trans.url }}" />
    {% endfor %}
  </url>
{% endfor %}
{% endraw %}

Conclusion

By using alternate URLs and hreflang tags correctly, your Jekyll site becomes search engine-friendly and regionally optimized. This not only improves visibility but also creates a better user experience for visitors across different languages and countries.

In the next tutorial, we'll dive into localized navigation menus powered by data files, enabling language-aware menus with minimal duplication and maximum control.