multilang-core

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

What it does

• Adds Eleventy’s built-in I18nPlugin so locale-aware URLs and filters are available.
• Builds a collections.translationsMap map keyed by translationKey with per-language entries.
• Lets you link alternates (hreflang) and look up localized counterparts in templates.

Defaults

• defaultLanguage: "en" if not provided.
• errorMode: "allow-fallback" (Eleventy I18n option).

Options

• defaultLanguage (string, recommended): Primary locale used for fallbacks.
• languages (array or object, optional): Your language definitions; used to decide if multilingual is on and to pass to sitemap-core. Not passed to Eleventy’s I18n plugin.
• Peer deps: none (uses Eleventy’s built-in I18n plugin).

How it works

• Registers Eleventy’s I18nPlugin with the provided defaultLanguage and errorMode.

• Creates collections.translations (array) and collections.translationsMap (map):

  • Keyed by each page’s translationKey.
  • translations (array): safe copies of pages that have a translationKey, each with locale: { translationKey, lang, isDefaultLang } plus page metadata (url, data, file info).
  • translationsMap (map): each key contains an object keyed by language code: { title, url, lang, isDefaultLang, data }.
  • lang is resolved from page.data.lang → page.data.language → defaultLanguage.

• Filters available:

  • 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.

• Sitemaps: hreflang alternates use translationsMap to render <xhtml:link> entries.

• You can render alternate links in Nunjucks, e.g.:

  {% set t = collections.translationsMap[page.translationKey] or {} %}
  {% set defaultLang = site.defaultLanguage %}
  {% set currentLang = page.locale.lang or defaultLang %}
  {% if t[currentLang] %}
    <link rel="alternate" hreflang="{{ currentLang }}" href="{{ t[currentLang].url | url }}">
  {% endif %}
  {% for lang, entry in t %}
    {% if lang != currentLang %}
      <link rel="alternate" hreflang="{{ lang }}" href="{{ entry.url | url }}">
    {% endif %}
  {% endfor %}
  {% if t[defaultLang] %}
    <link rel="alternate" hreflang="x-default" href="{{ t[defaultLang].url | url }}">
  {% endif %}

Tips

• Every localized page should set both translationKey and lang in front matter.
• Keep your default-language page present; it powers the x-default alternate.
• Store user-facing labels by language in a map (e.g., { en: "Hello", nl: "Hallo" }) for simple inline translations in Nunjucks.
• If multilingual: true and a languages map is set, sitemap-core will emit a sitemap index and per-locale sitemaps.
• See the “Multilingual Site” tutorial for a step-by-step setup and hreflang examples.
• Tutorial: Build a Multilingual Baseline Site