Posts

Showing posts with the label p14

Structure Jekyll repos for multilingual content

By -

Unlike dynamic CMS platforms that have built-in translation management, Jekyll doesn't come with native support for multilingual content. This means site maintainers must create a clean structure manually for each language, manage navigation separately, and ensure translated content remains consistent across locales.

Without a scalable structure, adding new languages becomes a tangled mess—mixing content, duplicating layouts, and breaking navigation. A well-planned multilingual structure prevents these issues from the beginning.

What are the common strategies for multilingual site organization?

There are two major approaches to structuring multilingual Jekyll sites:

  • Folder-based structure: Each language has its own directory (e.g., /en/, /id/, /fr/).
  • Data-driven translation: Layouts and includes pull language strings from YAML files in _data/.

Both can be used together—folders for page structure, and data files for UI/localization. This allows page content and interface labels to scale independently.

What does a scalable multilingual Jekyll repo structure look like?


/
├── _config.yml
├── _data/
│   ├── translations/
│   │   ├── en.yml
│   │   ├── id.yml
│   │   └── fr.yml
├── _includes/
├── _layouts/
├── assets/
├── pages/
│   ├── en/
│   │   ├── index.md
│   │   └── about.md
│   ├── id/
│   │   ├── index.md
│   │   └── about.md
│   └── fr/
│       ├── index.md
│       └── about.md
├── _posts/
│   ├── en/
│   ├── id/
│   └── fr/
└── README.md

This structure cleanly separates each language’s content. Folders under pages/ and _posts/ represent locale-specific content, while UI translations are centralized in _data/translations/.

How do you switch language versions in layout or navigation?

Use a language key in the front matter of each page to indicate the content’s language: 


---
lang: en
title: "About Us"
layout: page
permalink: /en/about/
---

You can then create a language switcher in _includes/language-switcher.html using the lang variable to offer links to other versions.

How do you organize global UI strings like buttons and menus?

Store all UI strings in language-specific files under _data/translations/. Example: en.yml 


nav:
  home: "Home"
  about: "About"
button:
  read_more: "Read more"

Load translations dynamically in layouts or includes: 


{% raw %}
{{ site.data.translations[page.lang].nav.home }}
{% endraw %}

This allows you to keep the same layout while dynamically rendering text in the appropriate language.

Should you use collections for multilingual content?

Yes. Collections help separate content types like _news/, _testimonials/, or _projects/ and can be duplicated per language. 


collections:
  en_projects:
    output: true
  id_projects:
    output: true

Then create directories: _en_projects/ and _id_projects/. This keeps content localized while maintaining consistent logic across the site.

How do you handle routing and permalinks?

Set the permalink explicitly in each page’s front matter to control URL structure: 


permalink: /id/tentang/

Alternatively, use a base URL variable in your config and front matter to avoid repetition: 


baseurl: ""
languages: ["en", "id", "fr"]

Then: 


permalink: /{{ page.lang }}/{{ page.slug }}/

How do you manage navigation per language?

Build navigation structures inside your language YAML files under _data/: 


menu:
  - title: "Home"
    url: "/en/"
  - title: "About"
    url: "/en/about/"

In your layout: 


{% raw %}
{% for item in site.data.translations[page.lang].menu %}
  <a href="{{ item.url }}">{{ item.title }}</a>
{% endfor %}
{% endraw %}

This allows full control of menu order, labels, and destinations per language.

How do you prevent duplicated effort when adding new languages?

Use base templates and includes that are language-agnostic. Centralize everything that repeats—like headers, footers, and CTAs—into includes that pull translations from the YAML data. Then only the actual content pages need to be localized.

You can also maintain a content checklist (e.g., in a CSV or data file) that tracks which pages are available and translated in each language.

How does structure help future growth and team onboarding?

When structure is consistent:

  • New contributors can easily find language-specific folders.
  • Automation scripts (e.g., for syncing translated content) can assume paths.
  • Navigation and UI logic are centralized and reusable.
  • Adding a new language becomes a matter of duplicating folders and editing YAML.

Conclusion: What’s the best way to scale multilingual Jekyll repos?

Organize by language folder, localize content in YAML, and structure layouts to be language-neutral. Separate UI strings from content, use consistent folder patterns, and standardize metadata. A multilingual site doesn’t have to be complicated if your structure is designed to scale.

Once your repo supports one language cleanly, duplicating that structure for more languages becomes simple. Build once, scale cleanly.

Read more
Subscribe to: Comments (Atom)