multilingual related posts in jekyll using data and language detection

By -

Why Multilingual Related Posts Matter

For multilingual Jekyll sites, simply reusing the same related post data across all languages leads to a poor UX. Users might click related links that aren’t in their preferred language. This breaks immersion, especially in knowledge bases or documentation.

✅ Goal:

  • Only show related posts that match the current post's language
  • Support shared related post groups across languages
  • Optional: Fallback if translation is missing

Step 1: Add Language to Post Front Matter

Add lang to each post:

---
title: "Optimisasi Template di Jekyll"
lang: id
related_group: template-performance
---

And its English version:

---
title: "Template Optimization in Jekyll"
lang: en
related_group: template-performance
---

Step 2: Update YAML Related Group File

Reuse same group keys for all languages, keeping just URLs:

template-performance:
  title:
    en: "Template Optimization Series"
    id: "Seri Optimisasi Template"
  posts:
    - /jekyll/template-basics/
    - /jekyll/layout-optimizations/
    - /jekyll/template-performance/
    - /jekyll/minification/

Step 3: Multilingual Logic in Layout or Include

Use the following Liquid logic to render related posts that match page.lang:

{% assign group_key = page.related_group %}
{% assign group_data = site.data.related[group_key] %}
{% if group_data %}
  {% assign lang = page.lang | default: "en" %}
  <div class="related-posts">
    <h3>{{ group_data.title[lang] | default: group_data.title["en"] }}</h3>
    <ul>
    {% for url in group_data.posts %}
      {% assign post = site.posts | where: "url", url | where: "lang", lang | first %}
      {% if post and post.url != page.url %}
        <li><a href="{{ post.url }}">{{ post.title }}</a></li>
      {% endif %}
    {% endfor %}
    </ul>
  </div>
{% endif %}

This code:

  • Loads the group from _data/related.yml
  • Uses the correct group title based on the page language
  • Only displays related posts that match the current language

Optional: Language Fallback for Missing Translations

If a translation is missing, you can show a fallback post (e.g., English):

{% assign fallback_post = site.posts | where: "url", url | where: "lang", "en" | first %}
{% assign post = site.posts | where: "url", url | where: "lang", lang | first | default: fallback_post %}

Step 4: Add Translated Titles to Related YAML

To make it fully multilingual, include title translations in your YAML:

jekyll-basics:
  title:
    en: "Jekyll Basics Series"
    id: "Seri Dasar Jekyll"
  posts:
    - /jekyll/setup/
    - /jekyll/structure/
    - /jekyll/markdown-guide/

Use {{ group_data.title[page.lang] }} to render it dynamically.

Optional: Language-Based Navigation Menus

You can even use this data structure to build multilingual section menus per language:

<nav class="group-nav">
  <h4>{{ group_data.title[lang] }}</h4>
  <ul>
  {% for url in group_data.posts %}
    {% assign post = site.posts | where: "url", url | where: "lang", lang | first %}
    {% if post %}
      <li{% if post.url == page.url %} class="active"{% endif %}>
        <a href="{{ post.url }}">{{ post.title }}</a>
      </li>
    {% endif %}
  {% endfor %}
  </ul>
</nav>

Recap: Why This System Works

  • ๐Ÿ“Œ Keeps logic clean — data-driven instead of per-post
  • ๐ŸŒ Language-aware related post experience
  • ๐Ÿ’ก Can be expanded into navigation, sidebars, or custom blocks

What’s Next?

We’ve now built:

  1. Basic related post system using front matter
  2. Advanced system using _data/related.yml
  3. Multilingual support based on page.lang

In the next part, we'll explore **automatically generating related post suggestions** using Liquid filters, word overlaps, or tag intersections—ideal when you don’t want to curate related groups manually.