Language-Aware Navigation Menus in Jekyll

Explore More Passive Income Ideas

Language-Aware Navigation Menus in Jekyll

Why Multilingual Navigation Matters

When building a multilingual Jekyll site, maintaining separate navigation menus for each language manually is inefficient and error-prone. To create a better user experience and simplify content management, we can use data-driven navigation with language-specific YAML files and modular Liquid includes.

Step 1: Structure Your Language Folders

For each supported language, create a corresponding folder in the root of your site (e.g. /en, /fr, /de). Within each folder, include an index.md file and other localized content.

This folder structure allows you to route users correctly and serve language-appropriate navigation.

Step 2: Create YAML Data Files for Menus

Inside your _data directory, create a subfolder called menus and place one YAML file for each language, such as:

_data/menus/en.yml
_data/menus/fr.yml
_data/menus/de.yml

Sample `en.yml`


- title: "Home"
  url: "/en/"
- title: "Blog"
  url: "/en/blog/"
- title: "Docs"
  url: "/en/docs/"
- title: "Contact"
  url: "/en/contact/"

Sample `fr.yml`


- title: "Accueil"
  url: "/fr/"
- title: "Blog"
  url: "/fr/blog/"
- title: "Documentation"
  url: "/fr/docs/"
- title: "Contact"
  url: "/fr/contact/"

Step 3: Build a Reusable Navigation Include

Create a new file in your _includes directory, for example: nav.html.


<nav class="site-nav">
  <ul>
    {% assign lang = page.lang | default: 'en' %}
    {% assign nav_items = site.data.menus[lang] %}
    {% for item in nav_items %}
      <li><a href="{{ item.url }}">{{ item.title }}</a></li>
    {% endfor %}
  </ul>
</nav>

This include uses the current page's lang front matter to determine which navigation to load. If lang is not set, it defaults to English.

Step 4: Use the Include in Your Layouts

In your base layout file, insert the navigation include where you want the menu to appear:


<body>
  {% include nav.html %}
  <main>{{ content }}</main>
</body>

Step 5: Add `lang` to Each Page

Ensure every page has a lang key in its front matter:


---
layout: default
lang: fr
title: "Documentation"
permalink: /fr/docs/
---

This allows the navigation include to fetch the correct language file dynamically.

Bonus: Highlight Active Menu Item

To visually indicate the current page, enhance the nav.html like this:


<li class="{% if page.url == item.url %}active{% endif %}">
  <a href="{{ item.url }}">{{ item.title }}</a>
</li>

Add corresponding CSS to style the .active class.

Use Case: Open Source Project with 5 Languages

An open-source project with documentation in English, Japanese, Korean, French, and Arabic used data-driven multilingual navigation. Instead of editing five separate navigation sections manually, they simply updated the YAML files, which reduced maintenance time by 60% and avoided cross-language inconsistencies.

Benefits of This Approach

Scalable to any number of languages
One include file for all navigation logic
Easy updates via YAML — no HTML edits needed
Reduces human error across language versions

Conclusion

Managing multilingual menus in Jekyll doesn’t have to be hard. By using YAML data files and Liquid includes, you can build robust, scalable, and DRY (Don't Repeat Yourself) navigation systems that adapt to user language automatically. This technique is foundational for international websites and improves both maintainability and user experience.

In the next article, we’ll explore how to localize SEO meta tags and Open Graph data for each language in your Jekyll site to increase discoverability and shareability globally.