Eine Schnellanleitung zur Lokalisierung einer Astro-Website

Erstellen Sie eine mehrsprachige Website mit Astro? Dann müssen Sie zwei verschiedene Herausforderungen bewältigen: die Organisation Ihrer Inhaltsseiten nach Sprachen und die Übersetzung von UI-Elementen wie Buttons und Navigation. Diese Anleitung zeigt Ihnen genau, wie Sie sowohl statische als auch dynamische Lokalisierung in Astro einrichten – von der Grundkonfiguration bis hin zu produktionsreifen Features.

Einrichtung des Astro i18n-Routings für statische Inhalte

Konfiguration der astro.config.mjs für mehrsprachige Unterstützung

Beginnen Sie mit der Konfiguration von Astros integriertem i18n-Routing in Ihrer astro.config.mjs-Datei. Dies teilt Astro mit, welche Sprachen Sie unterstützen und wie Ihre URLs strukturiert werden sollen:

import { defineConfig } from 'astro/config';

export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'fr'],
    routing: {
      prefixDefaultLocale: true // Verwende /en/ für englische URLs
    }
  }
});

Das Setzen von prefixDefaultLocale: true stellt sicher, dass alle Sprachen konsistente URL-Muster verwenden (/en/about, /es/about), was die Verwaltung von Links erleichtert und spätere Routing-Konflikte vermeidet.

Erstellung einer lokalisierten Ordnerstruktur

Organisieren Sie Ihre Seiten, indem Sie sprachspezifische Ordner in src/pages/ erstellen:

src/pages/
  en/
    index.astro
    about.astro
  es/
    index.astro
    about.astro
  fr/
    index.astro
    about.astro

Jeder Ordner entspricht einem in Ihrer Konfiguration definierten Locale. Astro generiert automatisch die korrekten Routen basierend auf dieser Struktur.

Verwaltung statischer und dynamischer Lokalisierung in Astro

Organisation von Content Collections nach Locale

Für Blog-Posts, Dokumentation oder beliebige Content Collections verwenden Sie dieselbe Locale-Struktur:

src/content/
  blog/
    en/
      first-post.md
    es/
      first-post.md
    fr/
      first-post.md

Beim Abfragen von Inhalten filtern Sie nach dem aktuellen Locale:

import { getCollection } from 'astro:content';

const posts = await getCollection('blog', ({ id }) => {
  return id.startsWith(Astro.currentLocale + '/');
});

Implementierung dynamischer Routen mit [locale]-Ordnern

Anstatt Seitendateien für jede Sprache zu duplizieren, verwenden Sie dynamische Routen. Erstellen Sie einen [locale]-Ordner:

src/pages/
  [locale]/
    index.astro
    about.astro
    blog/
      [slug].astro

Verwenden Sie in Ihren Seiten getStaticPaths(), um Routen für alle Locales zu generieren:

export function getStaticPaths() {
  return [
    { params: { locale: 'en' } },
    { params: { locale: 'es' } },
    { params: { locale: 'fr' } }
  ];
}

Handhabung dynamischer UI-Strings mit Paraglide

Installation und Konfiguration von Paraglide für Astro

Während Astro das Seiten-Routing übernimmt, benötigen Sie eine Lösung für UI-Texte. Paraglide bietet exzellente TypeScript-Unterstützung und minimale Bundle-Größe:

npm install @inlang/paraglide-js @inlang/paraglide-astro
npx @inlang/paraglide-js init

Erstellung von Übersetzungsdateien und Message-Keys

Speichern Sie Ihre Übersetzungen in messages/ im Projektroot:

// messages/en.json
{
  "nav.home": "Home",
  "nav.about": "About",
  "button.readMore": "Read more"
}

// messages/es.json
{
  "nav.home": "Inicio",
  "nav.about": "Acerca de",
  "button.readMore": "Leer más"
}

Importieren und verwenden Sie Übersetzungen in Ihren Komponenten:

---
import * as m from '../paraglide/messages.js';
---

<nav>
  <a href={`/${Astro.currentLocale}`}>{m.nav_home()}</a>
  <a href={`/${Astro.currentLocale}/about`}>{m.nav_about()}</a>
</nav>

Erstellung eines Sprachschalters und einer Navigation

Verwendung von getRelativeLocaleUrl() für saubere URLs

Astro bietet Hilfsfunktionen zur Generierung korrekter lokalisierter URLs. Verwenden Sie immer getRelativeLocaleUrl() anstelle manueller String-Verkettung:

import { getRelativeLocaleUrl } from 'astro:i18n';

const aboutUrl = getRelativeLocaleUrl(Astro.currentLocale, 'about');
const blogUrl = getRelativeLocaleUrl(Astro.currentLocale, 'blog/my-post');

Erstellen Sie eine Sprachschalter-Komponente:

---
import { getRelativeLocaleUrlList } from 'astro:i18n';

const localeUrls = getRelativeLocaleUrlList();
---

<select onchange="window.location.href = this.value">
  {localeUrls.map(url => {
    const locale = url.split('/')[1];
    return (
      <option value={url} selected={Astro.currentLocale === locale}>
        {locale.toUpperCase()}
      </option>
    );
  })}
</select>

Vermeidung häufiger Fallstricke wie doppelt-präfixierte Routen

Achten Sie auf diese häufigen Fehler:

1. Doppelte Präfixe: Bei der Verwendung dynamischer Routen bereinigen Sie Ihre Slugs, um URLs wie /en/blog/en/my-post zu vermeiden:

const cleanSlug = post.slug.replace(`${locale}/`, '');

2. Hardcodierte Locale-Pfade: Verwenden Sie immer Astros i18n-Hilfsfunktionen anstelle von String-Verkettung
3. Fehlende Locale in Links: Jeder interne Link benötigt ordnungsgemäße Lokalisierung

Erweiterte Astro i18n-Features

Einrichtung von Fallback-Sprachen

Konfigurieren Sie Fallbacks für nicht übersetzte Inhalte:

export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'fr'],
    fallback: {
      es: 'en',
      fr: 'en'
    },
    routing: {
      fallbackType: 'rewrite' // Zeige Fallback-Inhalt ohne Weiterleitung
    }
  }
});

Konfiguration von Domain-Mapping für die Produktion

Für Produktions-Websites mit separaten Domains pro Sprache:

export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'es', 'fr'],
    domains: {
      fr: 'https://fr.example.com',
      es: 'https://example.es'
    }
  }
});

Dies erfordert serverseitiges Rendering mit dem @astrojs/node- oder @astrojs/vercel-Adapter.

Fazit

Die Lokalisierung einer Astro-Website kombiniert zwei Ansätze: integriertes i18n-Routing für die Organisation statischer Inhalte und externe Bibliotheken wie Paraglide für dynamische UI-Strings. Beginnen Sie mit der Ordnerstruktur und Routing-Konfiguration, und fügen Sie dann das Übersetzungsmanagement hinzu. Denken Sie daran, Astros URL-Hilfsfunktionen zu verwenden, um häufige Routing-Probleme zu vermeiden, und berücksichtigen Sie Fallbacks und Domain-Mapping für Produktionsbereitstellungen.

Häufig gestellte Fragen

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.