Dynamic Routing Documentation with i18n

Since Astro doesn’t natively support URL localization out of the box, a different approach was needed to enable multilingual pages. This project uses dynamic parameters ([...pages]) to implement localized paths.

🏗️ Project Architecture Overview

The project implements an internationalization (i18n) system that enables:

• ✅ SEO-friendly URLs in multiple languages
• ✅ Automatic static generation at build time
• ✅ Language-specific content loading
• ✅ Seamless integration with translation system
• ✅ Smart language switching with context preservation

📁 File Structure

src/
├── components/           # Components (Header, Footer, LanguagePicker)
├── content/              # Content (blogs, authors)
│   ├── blog/
│   │   ├── en/           # English posts
│   │   └── sl/           # Slovenian posts
│   └── authors/          # Author data
├── data/                 # Navigation data
│   └── navigationData.ts
├── i18n/                 # Internationalization system
│   ├── routes.ts         # Path translations
│   ├── ui.ts             # Language configuration
│   └── utils.ts          # Utility functions
├── layouts/              # Base layouts
├── locales/              # Translation files
│   ├── en/               # English translations
│   └── sl/               # Slovenian translations
├── pages/                # Pages with dynamic routing
│   ├── [about]/          # About pages
│   │   ├── [...index].astro
│   │   ├── _about-en.mdx
│   │   └── _about-sl.mdx
│   ├── [blog]/           # Blog detail pages
│   │   └── [...slug].astro
│   ├── [dyn_routing]/    # Dynamic routing examples
│   │   ├── [subpage2]/
│   │   │   └── [...index].astro
│   │   └── [...subpage1].astro
│   ├── [pages]/          # General pages
│   │   ├── [...index].astro
│   │   ├── _pages-en.mdx
│   │   └── _pages-sl.mdx
│   ├── [pagination]/     # Pagination examples
│   │   └── [...page].astro
│   ├── [...blog].astro   # Blog listing page
│   ├── [...contact].astro # Contact page
│   ├── [...index].astro  # Home page
│   └── 404.astro         # Error page
└── styles/              # Style files

🔀 How Dynamic Routing Works

1. URL Structure

Examples assume defaultLang = "en" and showDefaultLang = false. These URLs adapt automatically when you change these settings.

2. Visual Routing Flow

File: [about]/[...index].astro
│
├── English path
│   ├── URL: /about
│   ├── Parameters: { about: "about", index: undefined }
│   ├── Props: { lang: "en" }
│   └── Content: _about-en.md
│
└── Slovenian path
    ├── URL: /sl/o-projektu
    ├── Parameters: { about: "sl", index: "o-projektu" }
    ├── Props: { lang: "sl" }
    └── Content: _about-sl.md

3. Page Structures

There are two main patterns for implementing dynamic pages:

Pattern A: [...pages].astro

import { buildLocalizedStaticPaths } from "@i18n/utils";

// Single-file: [...pages].astro
export function getStaticPaths() {
    return buildLocalizedStaticPaths("/pages", ["...pages"]);
}

Pattern B: [pages]/[...index].astro

import { buildLocalizedStaticPaths } from "@i18n/utils";

// Folder pattern: [pages]/[...index].astro
export function getStaticPaths() {
    return buildLocalizedStaticPaths("/pages", ["pages", "...index"]);
}

⚙️ Key System Components

1. src/i18n/routes.ts - Path Translations

This file defines mappings between English and localized paths:

export const routes: Record<string, Record<string, string>> = {
    sl: {
        about: "o-projektu",
        blog: "spletni-dnevnik",
        "dynamic-routing": "dinamicno-usmerjanje",
        "blog-pagination": "spletni-dnevnik-paginacija",
        pages: "strani",
        "subpage-1": "podstran-1",
        "subpage-2": "podstran-2",
    },
};

Important: Keys must match parameters in getStaticPaths() functions!

2. src/i18n/ui.ts - Language Configuration

This file contains key configurations for language support:

• languages - defines supported languages and their labels; add new languages here
• defaultLang - sets the default application language; flipping this moves the root (/) to that language
• showDefaultLang - toggles whether the default language appears in URLs (e.g., /en/ instead of /)

These are fully supported across pages, blog, and pagination.

export const languages = {
    en: "English",
    sl: "Slovenian",
};

export const defaultLang = "en"; // set to "sl" to make Slovenian the root
export const showDefaultLang = false; // true → always prefix: /en/..., /sl/...

How to flip the default language

1. Open src/i18n/ui.ts and set:
   • defaultLang = "sl" (or your new default)
   • showDefaultLang = true | false depending on whether you want a prefix for the default language
2. The root becomes:
   • / when showDefaultLang = false
   • /{defaultLang}/ when showDefaultLang = true
3. No other changes are needed: all pages use useTranslatedPath() in getStaticPaths() so URLs adapt automatically.
4. Sanity check a few URLs (home, about, blog list/post, pagination) and the language switcher.

3. src/i18n/utils.ts - Utility Functions

getLangFromUrl(url: URL)

Extracts the current language from the URL:

const lang = getLangFromUrl(Astro.url); // "sl" or "en"

useTranslations(lang: string)

Returns a function for translating texts:

const t = useTranslations(lang);
const title = t("main:head.title");
const navHome = t("menu.list.home"); // Uses "common" namespace

Supported key formats:

• "namespace:key" → t("main:title")
• Direct keys → t("menu.home") (defaults to “common” namespace)
• Parameters → t("footer.made", { what: "Astro" })

useTranslatedPath(lang: string)

Returns a function for translating paths:

const translatePath = useTranslatedPath(lang);
<a href={translatePath("/about")}>About</a>; // "/o-projektu" for Slovenian

switchLanguageUrl(currentUrl: URL, targetLang: string)

Enables language switching while preserving current page context:

const newUrl = await switchLanguageUrl(Astro.url, "sl");

🧩 Helper: buildLocalizedStaticPaths()

Generates localized getStaticPaths() entries from an English base path and a simple param pattern. It translates the base path for each language, splits it into segments, and maps those segments into Astro route params.

Signature:

function buildLocalizedStaticPaths(
  basePath: string,
  pattern: string[],
  extraProps?: (lang: string) => Record<string, any>
): Array<{ params: Record<string, string | undefined>; props: Record<string, any> }>

Pattern rules:

• Fixed param names: “about”, “dyn_routing”, “subpage2”
• Trailing catch‑all: prefix with ... and put it last (e.g., “…index”, “…subpage1”, “…blog”)
• Missing segments become undefined automatically (as Astro expects)
• Respects defaultLang and showDefaultLang

Examples:

// About folder: [about]/[...index].astro
export function getStaticPaths() {
  return buildLocalizedStaticPaths("/about", ["about", "...index"]);
}

// Dynamic Routing root: [dyn_routing]/[...index].astro
export function getStaticPaths() {
  return buildLocalizedStaticPaths("/dynamic-routing", ["dyn_routing", "...index"]);
}

// Dynamic Routing subpage 1: [dyn_routing]/[...subpage1].astro
export function getStaticPaths() {
  return buildLocalizedStaticPaths("/dynamic-routing/subpage-1", ["dyn_routing", "...subpage1"]);
}

// Dynamic Routing subpage 2 (nested): [dyn_routing]/[subpage2]/[...index].astro
export function getStaticPaths() {
  return buildLocalizedStaticPaths("/dynamic-routing/subpage-2", ["dyn_routing", "subpage2", "...index"]);
}

// Blog listing: [...blog].astro
export function getStaticPaths() {
  return buildLocalizedStaticPaths("/blog", ["...blog"]);
}

// Optional: extra props per language
export function getStaticPaths() {
  return buildLocalizedStaticPaths("/services", ["services", "...index"], (lang) => ({ section: "services", lang }));
}

Note (pagination): the pagination route uses this helper to resolve the localized base (e.g., blog-pagination → spletni-dnevnik-paginacija) and then fans out pages with paginate() while preserving the i18n URL shape.

4. src/data/navigationData.ts - Navigation

const navigationData = [
    {
        label: "menu.list.home", // Translation key
        href: "/", // English path (default)
        children: [],
    },
    {
        label: "menu.list.service",
        href: "/services",
        children: [
            {
                label: "menu.list.subpage-1",
                href: "/services/service-1",
            },
        ],
    },
];

Note: URLs in navigation are always in English because they’re automatically localized via translatePath().

🗣️ Translation System

1. Translation File Structure

src/locales/
├── en/
│   ├── common.json    # Shared translations (navigation, footer)
│   ├── main.json      # Main page
│   ├── about.json     # About page
│   └── blog.json      # Blog page
└── sl/
    ├── common.json
    ├── main.json
    ├── about.json
    └── blog.json

2. Translation File Example (common.json)

{
    "menu": {
        "list": {
            "home": "Home",
            "about": "About",
            "blog": "Blog"
        }
    },
    "footer": {
        "made": "Made with {{what}}"
    }
}

Note: For common.json files, you don’t need to prefix with common:. Use t("menu.list.home") directly, not t("common:menu.list.home").

3. Using Translations in Components

---
import { useTranslations } from "@i18n/utils";
const t = useTranslations(lang);
---

<h1>{t("main:hero.title")}</h1>
<p>{t("menu.list.home")}</p>
<footer>{t("footer.made", { what: "Astro" })}</footer>

📝 Blog System with linkedContent

1. Linking Content Between Languages

The blog system enables linking posts between different languages. The key question is: how does the system know the user is still on the same post when switching languages?

🔗 Solution: Each blog post must have a linkedContent identifier in the frontmatter. This identifier connects posts in different languages that cover the same topic. When users switch languages, the system uses this identifier to find the corresponding post in the target language.

Each blog post must have a linkedContent identifier in the frontmatter:

English post (en/security-trends.md):

---
title: "Top Security Trends for 2025"
linkedContent: "security-trends-2025"
author: "Nik Klemenc"
---

Slovenian post (sl/varnostni-trendi-2025.md):

---
title: "Glavni varnostni trendi za leto 2025"
linkedContent: "security-trends-2025" # Same identifier!
author: "Nik Klemenc"
---

2. Authors with Multilingual Data

The system enables linking authors with blog posts. In this case, a JSON format is used where each author has multilingual data. Under the “position” key, positions are defined in English and Slovenian, which are then dynamically displayed based on the selected language.

{
    "nik-klemenc": {
        "name": "Nik Klemenc",
        "image": "./nik.jpg",
        "position": {
            "en": "Full-stack Developer",
            "sl": "Full-stack razvijalec"
        }
    }
}

📄 Pagination

The project includes an example of pagination in [pagination]/[...page].astro, implemented using Astro’s default paginate() and adapted for localized URLs.

// Pagination with Astro's paginate()
export const getStaticPaths = async ({ paginate }) => {
    const posts = /* fetch posts and sort per language */ [];
    return paginate(posts, {
        pageSize: 4,
        params: { pagination: "blog-pagination" },
        props: {
            /* lang, authors, totals */
        },
    });
};

• URLs: EN /blog-pagination, /blog-pagination/2; SL /sl/spletni-dnevnik-paginacija, /sl/spletni-dnevnik-paginacija/2.
• The template uses page.data, page.currentPage, and page.lastPage.

💻 Usage Examples

1. Basic Page with Dynamic Routing

---
import { useTranslations, buildLocalizedStaticPaths } from "@i18n/utils";

export function getStaticPaths() {
    return buildLocalizedStaticPaths("/services", ["services", "...index"]);
}

const { lang } = Astro.props;
const t = useTranslations(lang);
---

<Base title={t("services:head.title")}>
    <h1>{t("services:title")}</h1>
</Base>

2. Language Switching

---
// LanguagePicker.astro - actual implementation
import { switchLanguageUrl, getLangFromUrl, useTranslations } from "@i18n/utils";
import { languages } from "@i18n/ui";

// Get current language
const currentLang = getLangFromUrl(Astro.url);
const t = useTranslations(currentLang);

// Prepare URLs for all languages
const languageUrls = await Promise.all(
    Object.entries(languages).map(async ([lang, label]) => {
        const targetUrl = await switchLanguageUrl(Astro.url, lang);
        const translatedLabel = t(`menu.languages.${lang}`);
        return { lang, label: translatedLabel, targetUrl };
    })
);
---

<!-- Dropdown selector -->
<select
    name="language"
    onchange="window.location.href = this.value"
    aria-label={t("menu.languagesText.selectLanguage")}
>
    {languageUrls.map(({ lang, label, targetUrl }) => (
        <option
            value={targetUrl}
            selected={lang === currentLang}
        >
            {label}
        </option>
    ))}
</select>

3. Localized Links

---
import { useTranslatedPath } from "@i18n/utils";

const translatePath = useTranslatedPath(lang);
---

<a href={translatePath("/about")}>
    {t("menu.list.about")}
</a>

✨ Best Practices

1. File Naming

• Use English names for files in the pages/ directory
• Localize only URLs via routes.ts
• Examples: [about] folder, not [o-projektu]

2. Translation Keys

• Use hierarchical structure (menu.list.home)
• Separate by namespaces (main:title, about:description)
• Add context to key names

3. Content Linking

• Always add linkedContent identifier to blog posts
• Use consistent naming between languages
• Test language switching on all pages

4. SEO Optimization

• Add title and description meta data
• Use hreflang attributes for multilingual pages
• Implement structured data

❓ Frequently Asked Questions

Why not use Astro’s built-in i18n?

Astro doesn’t provide fully localized, per-segment URLs with content-linked slugs and the precise prefix behavior used here (defaultLang/showDefaultLang + route translations). This project implements a small i18n layer (routes.ts, useTranslatedPath, switchLanguageUrl) that guarantees:

• Translated route segments (e.g., /about → /o-projektu)
• Optional prefix for the default language
• Language switching that preserves context, including blog slugs via linkedContent

How do I add a new language?

1. Add the language to src/i18n/ui.ts (languages).
2. Create translation files in src/locales/[lang]/....
3. Add route mappings in src/i18n/routes.ts for any segments you localize.

No changes to page files are required — all getStaticPaths() use useTranslatedPath() and automatically pick up the new language.

How does language switching work for blog posts?

Each post has a linkedContent identifier. switchLanguageUrl() uses this to find the matching post in the target language, translate the base route (blog ↔ spletni-dnevnik), and apply the correct prefix depending on showDefaultLang.

Can I use relative paths?

Use absolute paths with a leading slash (/about, not about). Path translation relies on consistent absolute segments.

🎯 This approach enables fully localized URLs with static generation performance and predictable SEO-friendly paths.