Astro Internationalization (i18n)

Patterns for building multilingual Astro sites without external libraries.

Route Structure (Prefix-based, recommended)

src/pages/
├── index.astro          # / (French default)
├── about.astro          # /about
├── blog/
│   └── [...slug].astro  # /blog/*
└── en/
    ├── index.astro      # /en
    ├── about.astro      # /en/about
    └── blog/
        └── [...slug].astro  # /en/blog/*

Language Detection

Utility Function

// src/utils/i18n.ts
export function getLang(pathname: string): 'fr' | 'en' {
  return pathname.startsWith('/en') ? 'en' : 'fr';
}

export function getLocalizedPath(path: string, lang: 'fr' | 'en'): string {
  const cleanPath = path.replace(/^\/en/, '');
  return lang === 'en' ? `/en${cleanPath}` : cleanPath;
}

When implementing route mapping between languages (static or dynamic), read references/i18n-implementation-patterns.md for complete mapping implementations.

When setting up a translations dictionary with JSON files and helper functions, read references/i18n-implementation-patterns.md for the full dictionary setup and useTranslations pattern.

When organizing multilingual content collections (separate collections, prefixed slugs, or frontmatter-based), read references/i18n-implementation-patterns.md for all three approaches.

When building a language switcher component or multilingual navigation, read references/i18n-implementation-patterns.md for complete LanguageSwitcher.astro and nav patterns.

Quick Reference

URL Patterns

Essential Functions

SEO Tags