creating localized post collections in jekyll
Understanding Jekyll Collections for Multilingual Blogs
Jekyll collections offer a flexible structure for organizing content beyond standard posts and pages. When building a multilingual blog, collections make it easier to separate content by language, maintain consistent structures, and apply language-specific templates.
Why Use Collections Instead of Tags or Folders
While you could use tags or language-specific folders to organize multilingual posts, collections provide:
- Custom permalinks per language
- Dedicated layouts for each language
- Explicit configuration for sorting and output
Planning the Folder Structure
Start by creating language-specific collections under a clear and predictable structure:
_posts/
_data/
_en/
_fr/
_es/
Each of these collections (_en, _fr, etc.) will hold blog posts written in the respective language.
Configuring Collections in _config.yml
Next, define these collections in your configuration file:
collections:
en:
output: true
permalink: /en/:title/
fr:
output: true
permalink: /fr/:title/
es:
output: true
permalink: /es/:title/
This allows Jekyll to treat these folders as collections and output them as standalone pages.
Creating Posts Inside Language Collections
Each collection behaves like posts. For example:
_en/
2025-01-01-my-first-english-post.md
_fr/
2025-01-01-mon-premier-article.md
Each file can include language-specific front matter:
---
layout: post
title: "My First English Post"
lang: en
category: tutorials
---
Creating Language-Specific Index Pages
To list all posts for a particular language, create index pages like:
en/index.md
fr/index.md
Inside en/index.md:
---
layout: default
title: "Blog in English"
---
{% raw %}
{% for post in site.en %}
- {{ post.title }}
{% endfor %}
{% endraw %}
Using Shared Layouts with Conditional Rendering
To avoid code duplication, use a shared layout with conditional logic:
{% raw %}
{% if page.lang == "en" %}
<h2>Recent Posts in English</h2>
{% elsif page.lang == "fr" %}
<h2>Articles récents en français</h2>
{% endif %}
{% endraw %}
Case Study: A Language-Learning Blog
A language learning blog needed three separate post collections: English tips, French grammar, and Spanish vocabulary. By using collections instead of folders or tags:
- Authors could focus on one language without interfering with others
- Readers accessed a clean URL path for each language
- SEO was improved through structured permalinks
Setting Up Navigation Between Languages
Use the filename or front matter to create alternate links:
{% raw %}
{% if page.lang == "en" %}
<a href="/fr/{{ page.slug }}">Lire en français</a>
{% endif %}
{% endraw %}
Or define translation mappings in a data file:
# _data/translations.yml
my-first-post:
en: /en/my-first-english-post/
fr: /fr/mon-premier-article/
Optimizing URLs and SEO
Collections give you full control over permalinks, allowing cleaner multilingual slugs. Use slug in front matter and access it for localized URLs.
---
title: "Mon premier article"
slug: mon-premier-article
lang: fr
---
Adding Localized RSS Feeds
Create custom feeds per language with plugins or manual templates:
feed.xml:
{% raw %}
{% for post in site.en %}
<item>
<title>{{ post.title }}</title>
<link>{{ site.url }}{{ post.url }}</link>
</item>
{% endfor %}
{% endraw %}
Common Pitfalls and Solutions
- Mixed content types: Avoid mixing collections and standard posts. Keep them separate for clarity.
- Missing output config: Collections won’t render unless
output: trueis specified. - Duplicate slugs: Always ensure unique
slugper post per language to prevent overwrite conflicts.
Advanced Filtering and Sorting
Sort and filter posts within a collection using Liquid:
{% raw %}
{% assign sorted_posts = site.fr | sort: "date" | reverse %}
{% for post in sorted_posts %}
<a href="{{ post.url }}">{{ post.title }}</a>
{% endfor %}
{% endraw %}
Pagination for Each Language
Jekyll-paginate doesn’t support multiple collections out of the box. You can build a workaround using includes and custom logic or use jekyll-paginate-v2 which supports multiple collections and languages.
Conclusion
Using language-specific post collections in Jekyll gives you structured control, scalable organization, and a better editorial experience. It also enhances your site’s SEO and usability. In the next article, we’ll look at building a language switcher component that works seamlessly with these collections and data-driven templates.
