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: truefür einheitliche URLs. - Nutzen Sie dynamische
[lang]/-Page-Routes mitgetStaticPaths, damit jede Locale statisch vorgerendert wird. - Synchronisieren Sie Übersetzungen zur Build-Zeit über den
download-Befehl vonlocize-cliin die App. Kein Runtime-CDN-Hop, keine SSR-Erwägungen. - Laden Sie die heruntergeladenen Dateien einmal in
src/i18n/index.tsin i18next; jede Page erhält mitgetFixedTeint()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 syncLocalesoder über die Locize-Web-App ein, je nachdem, was zu Ihrem Workflow passt. Ein Runtime-saveMissingaus 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 Siei18next-locize-backend+ daslocize-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-clilädt das aktuelle veröffentlichte JSON vom Locize-CDN nachsrc/i18n/locales/{lng}/{ns}.json.src/i18n/index.tslä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 downloadLocalesaus 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-appDie 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.jsonAbhängigkeiten installieren
npm install astro i18next
npm install --save-dev locize-cliEin 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/secondusw. Astro.currentLocalesteht kostenlos in jeder Page/Komponente zur Verfügung.- Browser-Sprach-Erkennung via
Astro.preferredLocaleundAstro.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.appist BunnyCDN-gestützt, kostenlos für grosszügige monatliche Download-Volumen, nur öffentlich (Default für neue Projekte); Pro unterapi.locize.appist CloudFront-gestützt, kostenpflichtig, unterstützt Private Downloads + individuelle Cache-Steuerung. Setzen Sie--cdn-typeim 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.globerfasst jede Datei, dielocize-cliherunterlädt, daher braucht ein neuer Namespace oder eine neue Sprache aus Locize keine Code-Änderung (nur die Sprache inlocalesinastro.config.mjsund ein Label inlanguages). - Namespaces als Dateien.
getT(lang, 'index')liefert eint()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/_otherpluscountfü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.
Der Language Picker und hreflang-Links
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:
npm run syncLocales(inpackage.jsonverdrahtet, das--dry=true-Flag entfernen, um tatsächlich zu pushen).locize-cliliest Ihre lokalensrc/i18n/locales/{lng}/{ns}.jsonund lädt alle Schlüssel hoch, die noch nicht in Locize sind. Manuell oder CI-getrieben, kein Write-Key im Browser.- Statische Extraktion via
i18next-cli: Es findett('…')-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. - Die Locize-Web-App: Schlüssel direkt im Editor hinzufügen und vor dem nächsten Build mit
downloadLocalesherunterladen.
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 downloadLocalesaus 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-backendinnerhalb 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 deslocize-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
- Wie man eine Nuxt-4-App mit @nuxtjs/i18n und Locize internationalisiert: Vue-seitiges Gegenstück mit reichhaltigerer Integration (vue-i18n, InContext-Editor, Runtime-saveMissing)
- Wie man eine React-Router-v7-App mit remix-i18next internationalisiert: React-seitiges Gegenstück mit Live-CDN-Fetch via
i18next-locize-backend - Astros eingebautes i18n-Routing: die Routing-Primitive, auf der dieser Walkthrough aufbaut
- Astro-i18n-Rezept: das Build-it-yourself-Muster, das i18next hier ersetzt
- i18next-Dokumentation:
t(), Plurale, Interpolation, TypeScript locize-cli: das Build-Zeit-Sync-Tool
Ü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
