Zum Inhalt springen
Tutorials21. Mai 2026· Aktualisiert 17. November 2026· 8 Min. Lesezeit

Eine Astro-Site mit i18next und Locize internationalisieren

Auf dieser Seite

Astro ist das Static-First-Web-Framework für inhaltsgetriebene Sites: dateibasiertes Routing, standardmässig kein JavaScript, „Islands" für opt-in-Interaktivität, ein SSR-on-Demand-Modus für die Teile, die ihn benötigen. Seit v4.0 (Ende 2023, stabil ab v5+, aktuell in v7.x) liefert Astro eingebautes i18n-Routing: URL-Prefixing (/en/, /de/), den Astro.currentLocale-Helper, Browser-Sprach-Erkennung und URL-Helper wie getRelativeLocaleUrl.

Was Astros eingebautes i18n nicht liefert, ist eine Translation-Funktion (t()), Pluralisierung oder Message-Interpolation. Astros offizielles i18n-Rezept zeigt ein „Build it yourself"-Muster: eine JSON-Datei pro Locale importieren und einen kleinen Lookup-Helper schreiben. Das deckt einfache Strings ab und hört dort auf, wo Plurale, Interpolation und Fallbacks beginnen. i18next schliesst diese Lücke, und zwar zur Build-Zeit: Es läuft, während Astro die Seiten rendert, daher schickt ein Static Build weiterhin kein JavaScript an den Browser. Locize verwaltet die Übersetzungen: locize-cli lädt das aktuelle veröffentlichte JSON vor dem Build nach src/i18n/locales/{lng}/{ns}.json, und i18next liest diese Dateien.

Dieser Beitrag führt End-to-End durch die Integration. Der vollständige Code liegt unter github.com/locize/locize-astro-example.

Aktualisiert am 17. November 2026: Die erste Version dieses Beitrags nutzte einen handgeschriebenen t()-Helper. Inzwischen nutzt er i18next; das bringt Plurale, Interpolation im i18next-JSON-Format, das Locize standardmässig verwendet, und Fallbacks, weiterhin ohne JavaScript im Browser. Das Beispiel ist auf Astro 7 umgezogen.

Wenn Sie stattdessen auf Nuxt sind, folgen Sie dem Nuxt-4-Walkthrough. Wenn Sie auf React Router v7 (Framework-Modus) sind, lesen Sie den React-Router-v7-Walkthrough. Beide decken reichhaltigere Integrationen ab (InContext-Editor, Runtime-saveMissing), die direkt nicht in Astros Static-by-Default-Modell passen.

TL;DR

  • Konfigurieren Sie Astros eingebautes i18n-Routing in astro.config.mjs: Locale-Liste + prefixDefaultLocale: true für einheitliche URLs.
  • Nutzen Sie dynamische [lang]/-Page-Routes mit getStaticPaths, damit jede Locale statisch vorgerendert wird.
  • Synchronisieren Sie Übersetzungen zur Build-Zeit über den download-Befehl von locize-cli in die App. Kein Runtime-CDN-Hop, keine SSR-Erwägungen.
  • Laden Sie die heruntergeladenen Dateien einmal in src/i18n/index.ts in i18next; jede Page erhält mit getFixedT ein t() für ihre Sprache. In einem Static Build läuft i18next nur zur Build-Zeit, daher geht kein JavaScript an den Browser.
  • Schreiben Sie die <link rel="alternate" hreflang>-Tags in Ihr Layout: Astros Routing fügt sie nicht hinzu.
  • Bringen Sie neue Schlüssel via npm run syncLocales oder über die Locize-Web-App ein, je nachdem, was zu Ihrem Workflow passt. Ein Runtime-saveMissing aus der Static-Schicht ist nicht möglich.
  • Brauchen Sie Runtime-saveMissing, Live-CDN-Fetch oder den InContext-Editor? Mounten Sie eine React-/Vue-/Svelte-Island via @astrojs/<framework> und nutzen Sie i18next-locize-backend + das locize-Paket innerhalb der Island.
  • Vollständiges Beispiel: github.com/locize/locize-astro-example

Wie die Teile zusammenpassen

Astro ist static-by-default. Seiten werden zur Build-Zeit zu HTML vorgerendert und als statische Dateien ausgeliefert (oder im SSR-Modus on demand über einen Adapter). Astros eingebautes i18n besitzt die Routing-Schicht (URL-Prefixing, locale-bewusste Redirects, Browser-Detection-Helper), bleibt aber bewusst aus der Message-Translation-Schicht heraus. Genau deshalb endet jedes Astro-i18n-Tutorial mit „und nun schreiben Sie Ihren eigenen t()-Helper". i18next ist diese Schicht, fertig gebaut.

Locize ist die Übersetzungsmanagement-Schicht. Die Integration ist rein bundle-basiert zur Runtime:

  • Build-Zeit: locize-cli lädt das aktuelle veröffentlichte JSON vom Locize-CDN nach src/i18n/locales/{lng}/{ns}.json. src/i18n/index.ts lädt jede dort gefundene Datei in i18next.
  • t() ist i18next, aufgerufen, während Astro jede Seite rendert: Plurale, Interpolation, Fallback auf die Default-Sprache, ein Namespace pro Datei. In einem Static Build gelangt nichts davon in den Browser: Die Ausgabe ist reines HTML.
  • Updates erfordern einen Rebuild, wie jede andere Astro-Content-Änderung. Führen Sie npm run downloadLocales aus und redeployen Sie.

Dieser letzte Punkt ist der Trade-Off. Ein „Übersetzung in Locize veröffentlicht → Endnutzer sehen sie"-Round-Trip bedeutet, dass der Build erneut ausgeführt werden muss. Wenn Sie stattdessen einen Live-CDN-gestützten Fetch wünschen (veröffentlichen → nächster Seitenaufruf nimmt es auf, kein Redeployment), mounten Sie eine Framework-Island und nutzen i18next-locize-backend darin; der React-Router-v7-Walkthrough behandelt diese Form, und Sie können dasselbe Muster pro Island in Astro übernehmen. Wir kommen am Ende darauf zurück.

Legen wir los

Voraussetzungen

Node.js 22.23.4+ (Astro 7 erfordert es), npm/pnpm/yarn und grundlegende Vertrautheit mit Astro. Das Beispiel unten zielt auf Astro 7.4 und i18next 27.

Projekt-Layout

Scaffolden Sie eine frische Astro-App oder klonen Sie das Beispiel via git clone:

npm create astro@latest my-app
cd my-app

Die relevante Verzeichnisstruktur, nachdem wir i18n + Locize verdrahtet haben:

my-app/
├── astro.config.mjs            # Astro's built-in i18n config
├── package.json                # locize-cli download/sync scripts
└── src/
    ├── pages/
    │   ├── index.astro         # root /, redirects to /en/
    │   └── [lang]/
    │       ├── index.astro     # home, renders for each locale via getStaticPaths
    │       └── second.astro    # secondary page, same pattern
    ├── layouts/
    │   └── Layout.astro        # shared <html>/<head>/<body>
    ├── components/
    │   └── LanguagePicker.astro # swaps the /{lang}/ prefix
    └── i18n/
        ├── index.ts            # loads the JSON into i18next; getT + pathForLang
        └── locales/            # locize-cli download target (one JSON per ns)
            ├── en/
            │   ├── common.json
            │   ├── index.json
            │   └── second.json
            └── de/
                ├── common.json
                ├── index.json
                └── second.json

Abhängigkeiten installieren

npm install astro i18next
npm install --save-dev locize-cli

Ein Astro-Integrations-Paket ist nicht nötig: i18next selbst funktioniert direkt in .astro-Dateien. Es ist die einzige Runtime-Abhängigkeit, und in einem Static Build läuft es nur, während die Site gebaut wird.

Astros eingebautes i18n in astro.config.mjs konfigurieren

import { defineConfig } from 'astro/config'

export default defineConfig({
  site: 'https://example.com',   // your domain: the hreflang links need absolute URLs
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'de'],
    routing: {
      prefixDefaultLocale: true   // /en/, /de/ # uniform URLs
    }
  }
})

Astro übernimmt nun:

  • URL-Routing für jede Seite unter src/pages/[lang]/: /en/, /de/, /en/second, /de/second usw.
  • Astro.currentLocale steht kostenlos in jeder Page/Komponente zur Verfügung.
  • Browser-Sprach-Erkennung via Astro.preferredLocale und Astro.preferredLocaleList (nur SSR-/On-Demand-Routes).

Mit prefixDefaultLocale: true erhält jede Locale ein URL-Prefix: einheitlich, SEO-sauber und einfach mit dynamischen [lang]/-Routes + getStaticPaths zu handhaben. (Wenn Sie die Default-Locale lieber ohne Prefix unter / ausliefern möchten, setzen Sie es auf false und nutzen dateibasierte Pages statt [lang]/. Das Beispiel nutzt die geprefixte Form, weil sie besser skaliert.)

Übersetzungen zur Build-Zeit von Locize herunterladen

Zu package.json hinzufügen:

{
  "scripts": {
    "downloadLocales": "locize download --project-id=<your-id> --ver=latest --cdn-type=standard --clean=true --path=./src/i18n/locales",
    "syncLocales":     "locize sync --project-id=<your-id> --ver=latest --cdn-type=standard --api-key=<your-write-key> --path=./src/i18n/locales --dry=true"
  }
}

Führen Sie npm run downloadLocales vor npm run build aus (manuell, in CI oder als prebuild-Hook), damit das gebündelte JSON immer frisch ist.

Standard vs. Pro CDN. Locize liefert zwei CDN-Infrastrukturen (vollständiger Vergleich unter CDN-Typen: Standard vs. Pro): Standard unter api.lite.locize.app ist BunnyCDN-gestützt, kostenlos für grosszügige monatliche Download-Volumen, nur öffentlich (Default für neue Projekte); Pro unter api.locize.app ist CloudFront-gestützt, kostenpflichtig, unterstützt Private Downloads + individuelle Cache-Steuerung. Setzen Sie --cdn-type im CLI-Flag passend zu Ihrem Projekt.

i18next in src/i18n/index.ts

Locize emittiert ein JSON pro Namespace pro Sprache, und genau so organisiert i18next seine Ressourcen. Ein Modul lädt jede heruntergeladene Datei und initialisiert i18next einmal:

import i18next, { type Namespace } from 'i18next'

// Every file locize-cli downloads: ./locales/{lng}/{ns}.json
const files = import.meta.glob<{ default: Record<string, string> }>('./locales/*/*.json', { eager: true })

const resources: Record<string, Record<string, Record<string, string>>> = {}
for (const [path, mod] of Object.entries(files)) {
  const [, lng, ns] = path.match(/\.\/locales\/([^/]+)\/([^/]+)\.json$/)!
  resources[lng] ??= {}
  resources[lng][ns] = mod.default
}

export const languages = { en: 'English', de: 'Deutsch' } as const
export type Lang = keyof typeof languages
export const defaultLang: Lang = 'en'

// An instance of its own, apart from any island that uses i18next in the browser.
const i18n = i18next.createInstance()
i18n.init({
  resources, // bundled, so init finishes right away
  fallbackLng: defaultLang,
  defaultNS: 'common',
  interpolation: { escapeValue: false } // Astro escapes what {t(...)} renders
})

// A t() bound to one language (and optionally one namespace).
export const getT = <N extends Namespace>(lang: Lang, ns?: N) => i18n.getFixedT(lang, ns)

// The same page in another language: swap the /{lang}/ prefix.
// "/en/second/" → "/de/second/"
export function pathForLang (pathname: string, target: Lang): string {
  const parts = pathname.split('/')
  parts[1] = target
  return parts.join('/')
}

Was Ihnen das bringt:

  • Keine Import-Liste zu pflegen. import.meta.glob erfasst jede Datei, die locize-cli herunterlädt, daher braucht ein neuer Namespace oder eine neue Sprache aus Locize keine Code-Änderung (nur die Sprache in locales in astro.config.mjs und ein Label in languages).
  • Namespaces als Dateien. getT(lang, 'index') liefert ein t() für eine Sprache und einen Namespace; Schlüssel aus einem anderen Namespace erhalten ein Prefix: t('common:headTitle').
  • Fallbacks. Ein Schlüssel, der auf Deutsch fehlt, fällt auf Englisch zurück (fallbackLng).
  • Interpolation und Plurale in dem Format, das Locize standardmässig speichert (i18next JSON v4): {{name}} für Werte, die Suffixe _one / _other plus count für Plurale, mit den Pluralregeln jeder Sprache:
{
  "title": "Hello, {{name}}!",
  "loaves_one": "{{count}} loaf left",
  "loaves_other": "{{count}} loaves left"
}

Typisierte Schlüssel funktionieren ebenfalls: Der TypeScript-Support von i18next liest die Schlüsselnamen aus dem JSON Ihrer Default-Sprache.

t() in Pages verwenden

Dynamische [lang]/-Routes + getStaticPaths bedeuten, dass Astro zur Build-Zeit eine HTML-Datei pro Locale vorrendert:

---
// src/pages/[lang]/index.astro (excerpt)
import Layout from '../../layouts/Layout.astro'
import { getT, languages, type Lang } from '../../i18n'
import { getRelativeLocaleUrl } from 'astro:i18n'

export function getStaticPaths () {
  return Object.keys(languages).map(lang => ({ params: { lang } }))
}

const { lang } = Astro.params as { lang: Lang }
const t = getT(lang, 'index')
---

<Layout lang={lang} title={t('common:headTitle')}>
  <h1>{t('title', { name: 'Astro' })}</h1>
  <p>{t('subtitle')}</p>
  <p>{t('loaves', { count: 1 })} · {t('loaves', { count: 3 })}</p>
  <p>
    <a href={getRelativeLocaleUrl(lang, 'second/')}>
      {t('goto.second')}
    </a>
  </p>
</Layout>

Die getStaticPaths-Funktion mappt jede Locale auf einen statischen Pfad; lang kommt als Route-Param an. Reine Build-Zeit-Arbeit: keine serverseitige Runtime, keine Hydration. Der Build schreibt /en/index.html mit „Hello, Astro!" und „1 loaf left · 3 loaves left" sowie /de/index.html mit „Hallo, Astro!" und „1 Brot übrig · 3 Brote übrig", aber keine JavaScript-Datei.

Astros i18n-Rezept in den Docs zeigt einen einfachen Picker, der das Locale-Prefix in der aktuellen URL austauscht; pathForLang aus src/i18n/index.ts übernimmt den Austausch:

---
// src/components/LanguagePicker.astro (excerpt)
import { languages, pathForLang, type Lang } from '../i18n'

interface Props {
  currentLang: Lang
}
const { currentLang } = Astro.props
---

<nav>
  <ul>
    {Object.entries(languages).map(([lang, label]) => (
      <li>
        {lang === currentLang ? (
          <strong>{label}</strong>
        ) : (
          <a href={pathForLang(Astro.url.pathname, lang as Lang)}>{label}</a>
        )}
      </li>
    ))}
  </ul>
</nav>

Legen Sie ihn in src/layouts/Layout.astro ab und er ist auf jeder Seite verfügbar. Dasselbe Layout schreibt die hreflang-Links, damit Suchmaschinen wissen, welche Seite welche Sprache ist; Astros Routing fügt sie nicht hinzu:

---
// src/layouts/Layout.astro (head excerpt)
import { languages, defaultLang, pathForLang, type Lang } from '../i18n'
const { lang, title } = Astro.props
---
<html lang={lang}>
  <head>
    <title>{title}</title>
    {Object.keys(languages).map(l => (
      <link rel="alternate" hreflang={l} href={new URL(pathForLang(Astro.url.pathname, l as Lang), Astro.site)} />
    ))}
    <link rel="alternate" hreflang="x-default" href={new URL(pathForLang(Astro.url.pathname, defaultLang), Astro.site)} />
  </head>

Drei Wege, neue Schlüssel in Locize zu bekommen

Astro ist static-by-default: Seiten werden vorgerendert, daher ist ein Runtime-saveMissing-Push von Produktionsnutzern ohne einen SSR-Adapter nicht möglich, und Astro rät ohnehin von Schreibzugriffen aus der Static-Schicht ab. Stattdessen gibt es drei praktikable Pfade:

  1. npm run syncLocales (in package.json verdrahtet, das --dry=true-Flag entfernen, um tatsächlich zu pushen). locize-cli liest Ihre lokalen src/i18n/locales/{lng}/{ns}.json und lädt alle Schlüssel hoch, die noch nicht in Locize sind. Manuell oder CI-getrieben, kein Write-Key im Browser.
  2. Statische Extraktion via i18next-cli: Es findet t('…')-Aufrufe in .js-, .ts-, .jsx- und .tsx-Dateien ohne weitere Konfiguration und schreibt neue Schlüssel in das lokale JSON; danach synchronisieren Sie wie oben hoch. .astro-Dateien brauchen ein Plugin über seine Plugin-Hooks; ohne Plugin liest i18next-cli sie nicht.
  3. Die Locize-Web-App: Schlüssel direkt im Editor hinzufügen und vor dem nächsten Build mit downloadLocales herunterladen.

Wählen Sie, was zu Ihrem Workflow passt. Keiner dieser Pfade erfordert, einen Write-API-Key in Ihrem Build-Artefakt auszuliefern.

Was diese Form bewusst nicht enthält

Drei Dinge, die Sie aus den Nuxt- oder React-Router-v7-Walkthroughs erwarten könnten, fehlen hier bewusst:

  • Kein Runtime-saveMissing. Siehe oben: Astro-Static-Builds können nicht pushen, und eine SSR-Astro-App würde dies aus einer Island heraus tun, nicht aus der Static-Schicht.
  • Kein InContext-Editor auf statischen Seiten. Der locize-Editor benötigt ein DOM, das sich neu rendert, wenn der Editor einen String aktualisiert. Astros Static-Output hat diesen Hook nicht.
  • Kein Live-CDN-Fetch. Übersetzungen werden zur Build-Zeit gebündelt. Um eine frische Übersetzung auszuliefern, führen Sie npm run downloadLocales aus und redeployen. Das passt zu Astros Static-First-Modell und hält das Build-Artefakt in sich geschlossen.

Alle drei dieser Punkte funktionieren innerhalb von Framework-Islands. Mounten Sie eine React-, Vue-, Svelte-, Solid- oder Preact-Island via der passenden @astrojs/<framework>-Integration und nutzen Sie in dieser Island i18next-locize-backend + das locize-Paket direkt. Die Astro-Static-Schicht erledigt das Routing + die Page-Chrome; die Islands übernehmen die Teile, die eine Runtime benötigen. Seiten und Islands nutzen dieselbe Library und dasselbe JSON-Format.

Wann eine Framework-Island sinnvoll ist

Die rein statische Integration deckt die meisten Content-Sites ab: Blogs, Marketing-Pages, Docs, Landing-Pages. Fügen Sie eine Framework-Island hinzu, wenn Sie Folgendes benötigen:

  • Live-Übersetzungs-Updates ohne Redeployment. Nutzen Sie i18next-locize-backend innerhalb der Island, um Übersetzungen bei jedem Besuch (oder pro Route, wenn Sie cachen) vom Locize-CDN zu holen.
  • InContext-Editing für Übersetzer. Das ?incontext=true-Overlay des locize-Pakets benötigt eine Runtime, die bei String-Änderungen neu rendert, nur innerhalb einer hydrierten Island verfügbar.
  • Runtime-saveMissing. Dieselbe Einschränkung: eine hydrierte Island kann neue Schlüssel pushen; statisches HTML kann das nicht.

Das Muster sieht so aus (für eine React-Island):

---
// src/pages/[lang]/interactive.astro
import Layout from '../../layouts/Layout.astro'
import I18nIsland from '../../components/I18nIsland.tsx'
import { languages, type Lang } from '../../i18n'

export function getStaticPaths () {
  return Object.keys(languages).map(lang => ({ params: { lang } }))
}
const { lang } = Astro.params as { lang: Lang }
---

<Layout lang={lang} title="Interactive">
  <I18nIsland client:load lang={lang} />
</Layout>
// src/components/I18nIsland.tsx
import i18next from 'i18next'
import Backend from 'i18next-locize-backend'
import { initReactI18next, useTranslation } from 'react-i18next'

i18next
  .use(Backend)
  .use(initReactI18next)
  .init({
    fallbackLng: 'en',
    saveMissing: import.meta.env.DEV,
    backend: {
      projectId: import.meta.env.PUBLIC_LOCIZE_PROJECT_ID,
      apiKey: import.meta.env.DEV ? import.meta.env.PUBLIC_LOCIZE_API_KEY : undefined, // dev only; the browser sees only PUBLIC_ variables
      version: 'latest'
    }
  })

export default function I18nIsland ({ lang }: { lang: string }) {
  const { t, i18n } = useTranslation()
  if (i18n.language !== lang) i18n.changeLanguage(lang)
  return <h2>{t('island.heading')}</h2>
}

client:load weist Astro an, diese Komponente sofort beim Page-Load zu hydrieren; Sie können client:visible nutzen, um die Hydration zu verzögern, bis die Island in den Viewport gelangt. Die genaue Konfiguration von i18next-locize-backend ist im React-Router-v7-Walkthrough dokumentiert; dasselbe Backend-Wiring funktioniert in jedem React-/Vue-/Svelte-/Solid-Kontext, auch innerhalb einer Astro-Island.

🎉 Glückwunsch

Ein funktionierendes Astro 7 + i18next + Locize-Setup gibt Ihnen:

  • Static-First-i18n ohne Flash unübersetzter Inhalte und ohne Übersetzungs-JavaScript im Browser (alles wird pro Locale vorgerendert)
  • SEO-sauberes URL-Prefixing via Astros eingebautem i18n-Routing, mit hreflang-Links aus dem Layout
  • Ein vollständiges t() von i18next: Plurale, Interpolation, Fallbacks, Namespaces
  • Build-Zeit-Übersetzungs-Sync via locize-cli: serverless-freundlich, kein per-Request-CDN-Hop
  • Einen Ausstiegspfad zu dynamischen Islands, mit derselben Library und denselben Dateien, wenn Sie Runtime-Updates oder InContext-Editing benötigen

🧑‍💻 Der vollständige Code: github.com/locize/locize-astro-example.

Die Gründer von Locize sind auch die Macher von i18next. Durch die Nutzung von Locize unterstützen Sie direkt die Zukunft von i18next.

Siehe auch

Übersetzungen noch von Hand verwalten?

Locize ist das Translation-Management-Backend vom i18next-Team: CDN-Auslieferung, KI-Übersetzung, In-Context-Editing, keine Redeploys.

14 Tage kostenlos testen

Verwandte Beiträge