Internationalization (i18n) Architecture

Internationalization (i18n) Architecture

Overview

metinet.de supports English (default, root /) and German (/de/). The system uses Jekyll front matter and data files — no plugins required beyond the standard github-pages gem.

URL Structure

Language URL Prefix Example
English (default) / /blog/2026/03/02/my-post/
German /de/ /de/blog/2026/03/02/mein-beitrag/

Key Concepts

1. lang Front Matter

Every page and post must have a lang key:

lang: en   # or "de"

The _config.yml defaults set lang: en for all root content and lang: de for everything under de/. Posts must explicitly set lang in their front matter.

2. ref Front Matter (Translation Linking)

The ref key is a shared identifier that links equivalent content across languages:

# English post
lang: en
ref: future-software-dev-ai

# German translation
lang: de
ref: future-software-dev-ai

Pages and posts with the same ref are considered translations of each other. The language switcher and translation banner use this to find counterparts.

3. UI Translations

All translatable UI strings live in:

  • _data/i18n/en.yml — English
  • _data/i18n/de.yml — German

Access in templates:



Home

4. Includes

Include Purpose
_includes/lang-switcher.html Language toggle link in the navigation header
_includes/translation-banner.html Banner on posts linking to the translation counterpart

Adding a New Language

  1. Create _data/i18n/<code>.yml with all translation keys.
  2. Create <code>/ directory with index.html, blog/index.md, contact.html, etc.
  3. Add defaults in _config.yml under the new path.
  4. Update tailwind.config.js content paths.
  5. Update lang-switcher.html to handle the new language.

Adding a New German Blog Post

  1. Create the file in _posts/ with the format YYYY-MM-DD-slug.md.
  2. Set front matter:
---
layout: post
title: "Deutscher Titel"
date: YYYY-MM-DD HH:MM:SS +0100
categories: [...]
tags: [...]
author: Metin Özkan
description: "..."
lang: de
ref: shared-ref-key
permalink: /de/blog/:year/:month/:day/:title/
---
  1. The ref must match the English counterpart’s ref (if one exists).
  2. The permalink must include the /de/ prefix.

How the Language Switcher Works

  1. Reads page.lang and page.ref.
  2. Searches site.pages and site.posts for a matching ref in the other language.
  3. If found, links to that page/post.
  4. If not found, falls back to the other language’s home page.

SEO

  • <html lang="..."> is set from page.lang in default.html.
  • <link rel="alternate" hreflang="..."> tags are generated automatically for pages with a ref that has a counterpart.