Creating Multilingual 404 Pages in Jekyll

By -

Why Multilingual 404 Pages Matter

As your Jekyll site grows and reaches a broader audience, offering localized content becomes essential. This includes your 404 page. A multilingual 404 experience enhances user satisfaction, improves engagement, and reflects the professionalism of your brand. Ignoring it, on the other hand, risks confusing or frustrating users who encounter an unfamiliar language when something goes wrong.

What Makes a Good Multilingual 404 Page

  • Detects or adapts to user language preference
  • Displays content in that language
  • Links to equivalent resources in that language
  • Maintains brand voice and helpful tone

Folder-Based Language Architecture in Jekyll

One of the simplest methods for supporting multiple languages in Jekyll is to organize your content—including 404 pages—into language-specific folders.

Example Structure


/404.html  (default fallback)
/en/404.html
/fr/404.html
/es/404.html

Each localized 404 page can then be fully customized with its own tone, voice, search options, and links relevant to that language's audience.

Detecting Language Preference with JavaScript

Although Jekyll itself is static, JavaScript can enhance your 404 UX by detecting the user's preferred language and redirecting them to a translated error page if available.

Sample Script

<script>
  const userLang = navigator.language || navigator.userLanguage;
  if (userLang.startsWith('fr')) {
    window.location.href = '/fr/404.html';
  } else if (userLang.startsWith('es')) {
    window.location.href = '/es/404.html';
  }
</script>

This snippet can be placed in your default /404.html to automatically redirect visitors to a localized version if one exists.

Using Data Files for Localized Messages

To reduce duplication and centralize translation, consider storing your 404 messages in a YAML data file inside the _data directory.

Example: _data/errors.yml

en:
  title: "Page not found"
  message: "We couldn't find the page you were looking for."
  link: "Return to homepage"
fr:
  title: "Page non trouvée"
  message: "Nous n'avons pas trouvé la page demandée."
  link: "Retour à l'accueil"

Displaying Translations in Templates

Load the right language using a lang front matter variable or folder context:

{% raw %}
{% assign lang = page.lang | default: "en" %}
<h2>{{ site.data.errors[lang].title }}</h2>
<p>{{ site.data.errors[lang].message }}</p>
<a href="/">{{ site.data.errors[lang].link }}</a>
{% endraw %}

Fallback Strategies for Untranslated Pages

Not all languages may have a translated 404 page. You can implement graceful fallbacks to ensure users still receive a usable experience.

  • Default to English or your primary language
  • Show a list of available languages
  • Link to support or contact pages for further help

Universal Template Fallback

Create a template that renders translated content if available, and falls back otherwise:

{% raw %}
{% if site.data.errors[lang] %}
  <h2>{{ site.data.errors[lang].title }}</h2>
  <p>{{ site.data.errors[lang].message }}</p>
{% else %}
  <h2>{{ site.data.errors["en"].title }}</h2>
  <p>{{ site.data.errors["en"].message }}</p>
{% endif %}
{% endraw %}

Case Study: Localizing a Documentation Site

A software documentation site serving users in five languages faced bounce issues when users encountered a 404 page in English. After implementing multilingual 404 pages using a combination of YAML data and folder-based templates, bounce rate on 404s dropped by 35%. Visitors now felt reassured even when something broke, thanks to a familiar language and contextual guidance.

SEO Considerations

Localized 404 pages should avoid duplicate content issues and clearly indicate the intended language to search engines using proper HTML attributes.

Best Practices

  • Use lang attributes in your HTML element
  • Do not allow translated 404s to be indexed—use noindex meta tags
  • Submit canonical URLs when needed

Accessibility and UX Tips

  • Make sure error messages are clear in every language
  • Use simple vocabulary appropriate for error context
  • Always include a link back to the homepage or site map

Conclusion

Building multilingual 404 pages in Jekyll adds a layer of empathy and professionalism to your site. Whether through data-driven templates or folder-based routing, this extra effort improves user trust and keeps international visitors engaged even when they hit a dead end.