Eleventy Plugin Baseline

A magic carpet ride

Table of Contents

multilang-core

Note: The options API is still evolving; expect tweaks as the project grows.

What it does

multilang-core adds Eleventy’s built-in I18nPlugin, builds translation collections keyed by translationKey, and registers i18n filters for looking up localized counterparts in templates. It shares language normalization with sitemap-core through a common langNormalization helper in core/helpers.js.

Defaults

  • defaultLanguage: ”en” if not provided.
  • errorMode: ”allow-fallback” (passed to Eleventy’s I18n plugin).
  • Language resolution: page.data.lang → page.data.language → defaultLanguage.

Options

Option Type Default Description
defaultLanguage string ”en” Primary locale, used for fallbacks and isDefaultLang flags.
languages object or array — Language definitions. Object { en: {}, nl: {} } or array [‘en’, ‘nl’]. Arrays are normalized to objects.

All three — multilingual: true, a truthy defaultLanguage, and a non-empty languages map — must be set for this module to load.

How it works

  1. I18n plugin.

    Registers Eleventy’s I18nPlugin with the provided defaultLanguage and errorMode, so locale-aware URLs and filters are available.

  2. Translation collections.

    Builds two collections from pages that have a translationKey:

    • collections.translations — an array. Each entry is a safe copy of the page with locale: { translationKey, lang, isDefaultLang } plus page metadata (url, data, file info).
    • collections.translationsMap — a map keyed by translationKey, then by language code. Each entry holds { title, url, lang, isDefaultLang, data }.

  3. Filters.

    Three filters for looking up translations in templates:

    • i18nTranslationsFor(page, collections.translations) — all siblings for the page’s translationKey.
    • i18nTranslationIn(page, collections.translations, lang) — specific language variant, or null.
    • i18nDefaultTranslation(page, collections.translations) — default-language variant, or null.

  4. Sitemap integration.

    Shares the langNormalization helper (from core/helpers.js) with sitemap-core, so per-language sitemaps and hreflang alternates resolve against the same normalized language map.

Rendering alternate links

Use translationsMap in your layout to render hreflang links:

{% set t = collections.translationsMap[translationKey] %}
{% if t %}
  {% for lang, entry in t %}
    <link rel=”alternate” hreflang=”{{ entry.lang }}” href=”{{ entry.url }}”>
    {% if entry.isDefaultLang %}<link rel=”alternate” hreflang=”x-default” href=”{{ entry.url }}”>{% endif %}
  {% endfor %}
{% endif %}

Tips

  • Every localized page should set both translationKey and lang in front matter. Without translationKey, the page won’t appear in translation collections.
  • Keep your default-language page present — it powers the x-default alternate.
  • When multilingual: true and a languages map is set, sitemap-core emits a sitemap index and per-locale sitemaps automatically.
  • See Build a Multilingual Baseline Site for a step-by-step setup with hreflang examples.

Peer deps

None — uses Eleventy’s built-in I18n plugin.

Previous: head-core

Next: navigator-core