Multilingual Jekyll Sites Using Data Files and Liquid

By -

Why Multilingual Support Matters

As your audience grows, supporting multiple languages can dramatically improve accessibility and engagement. Whether you're targeting international markets or serving diverse communities, a multilingual Jekyll site ensures:

  • Wider audience reach
  • Improved user experience for non-English readers
  • Better local SEO in specific regions
  • Compliance with language accessibility standards

Planning Your Multilingual Architecture

To support multiple languages in Jekyll effectively, you should separate content and interface labels using structured data. Each language can have its own folder or be handled via URL parameters depending on your SEO and UX goals.

Recommended Structure


_data/
  translations/
    en.yml
    fr.yml
    es.yml
    id.yml

_pages/
  en/
    index.md
    about.md
  fr/
    index.md
    about.md

Creating Your Language Data Files

Each YAML file in _data/translations contains localized labels for UI and page content. Example en.yml:


home: "Home"
about: "About Us"
contact: "Contact"
welcome: "Welcome to our site"

And fr.yml:


home: "Accueil"
about: "À propos"
contact: "Contact"
welcome: "Bienvenue sur notre site"

Accessing Translations in Templates

Use the page’s front matter to define a language key:


---
layout: default
lang: fr
title: "Accueil"
---

Then use Liquid in your layout or includes to load the appropriate language file:

{% raw %}
{% assign t = site.data.translations[page.lang] %}

<nav>
  <ul>
    <li><a href="/{{ page.lang }}/">{{ t.home }}</a></li>
    <li><a href="/{{ page.lang }}/about/">{{ t.about }}</a></li>
    <li><a href="/{{ page.lang }}/contact/">{{ t.contact }}</a></li>
  </ul>
</nav>

<h2>{{ t.welcome }}</h2>
{% endraw %}

Creating Language Switcher Links

Add a language switcher in your layout using manual links or auto-generated ones:

{% raw %}
<div class="lang-switcher">
  <a href="/en{{ page.url | remove: '/' | prepend: '/' }}">EN</a> |
  <a href="/fr{{ page.url | remove: '/' | prepend: '/' }}">FR</a>
</div>
{% endraw %}

This assumes consistent file naming across languages (e.g. index.md under en and fr).

Best Practices for Multilingual Jekyll Sites

  • Use short language codes (en, fr, es, etc.) in folder names and URL structures
  • Translate all interface labels using data files, not hardcoded strings
  • Use consistent content structure across language folders
  • Localize meta descriptions and page titles via front matter variables

Case Study: From English-Only to Global Reach

A documentation site initially created in English started receiving traffic from Spanish-speaking regions. By localizing their UI and duplicating key content in Spanish using this Jekyll multilingual structure, they saw a 40% increase in time-on-site from new users. Additionally, localized metadata improved organic visibility in Google.es search results.

SEO Considerations

For multilingual SEO:

  • Add hreflang tags in the head to help search engines understand language variants
  • Ensure URLs reflect language codes (e.g., /en/about/, /fr/about/)
  • Use localized title and description tags for each page

Scalability Tips

As you add more languages:

  • Keep translation keys organized alphabetically or thematically
  • Use separate data files per language to reduce complexity
  • Automate or semi-automate translation workflows with GitHub Actions or scripts

Summary

Multilingual support in Jekyll is powerful and scalable when built using data files and Liquid. It allows for separation of content and presentation while supporting a global audience. Whether for a blog, documentation portal, or marketing site, this setup is robust, maintainable, and SEO-friendly.

Series Wrap-Up

This concludes the 11-part series on optimizing GitHub Pages and Jekyll for structured, scalable, and performance-oriented sites. From layout optimization to dynamic data and multilingual capabilities, you now have the tools to build a professional static website tailored for growth.