---
createdAt: 2024-03-07
updatedAt: 2026-05-31
title: "Astro + React i18n - Vollständiger Leitfaden zur Übersetzung Ihrer App"
description: "Kein i18next mehr. Der 2026-Leitfaden zum Erstellen einer mehrsprachigen (i18n) Astro + React-App. Übersetzen Sie mit KI-Agenten und optimieren Sie Bundle-Größe, SEO und Performance."
keywords:
- Internationalisierung
- Dokumentation
- Intlayer
- Astro
- React
- i18n
- JavaScript
slugs:
- doc
- environment
- astro
- react
applicationTemplate: https://github.com/aymericzip/intlayer-astro-template
applicationShowcase: https://intlayer-astro-template.vercel.app
history:
- version: 8.9.0
date: 2026-05-04
changes: "Aktualisieren der Solid useIntlayer API-Nutzung auf direkten Eigenschaftszugriff"
- version: 7.5.9
date: 2025-12-30
changes: "init-Befehl hinzufügen"
- version: 6.2.0
date: 2025-10-03
changes: "Aktualisierung der Astro-Integration, Konfiguration und Verwendung"
---
# Übersetzen Sie Ihre Astro + React Website mit Intlayer | Internationalisierung (i18n)
## Inhaltsverzeichnis
## Warum Intlayer gegenüber Alternativen?
Im Vergleich zu Hauptlösungen wie „astro-i18n“ oder „i18next“ ist Intlayer eine Lösung, die über integrierte Optimierungen verfügt wie:
Intlayer ist für die perfekte Zusammenarbeit mit Astro optimiert, indem es **mehrsprachiges Routing**, **Sitemap** und alle Funktionen bietet, die für die Skalierung der Internationalisierung (i18n) erforderlich sind.
Anstatt riesige JSON-Dateien in Ihre Seiten zu laden, laden Sie nur den erforderlichen Inhalt. Intlayer hilft **Ihre Bundle- und Seitengröße um bis zu 50 % zu reduzieren**.
Durch die Festlegung des Inhaltsbereichs Ihrer Anwendung wird die Wartung für umfangreiche Anwendungen erleichtert. Sie können einen einzelnen Feature-Ordner duplizieren oder löschen, ohne die mentale Belastung durch die Überprüfung Ihrer gesamten Inhaltscodebasis auf sich nehmen zu müssen. Darüber hinaus ist Intlayer **vollständig typisiert (fully typed)**, um die Genauigkeit Ihrer Inhalte sicherzustellen.
Durch die gemeinsame Platzierung von Inhalten **reduziert sich der von Large Language Models (LLMs) benötigte Kontext**. Intlayer verfügt außerdem über eine Reihe von Tools, wie zum Beispiel eine **CLI** zum Testen auf fehlende Übersetzungen,**[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/lsp.md)**, **[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/mcp_server.md)** und **[agent Fähigkeiten](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/agent_skills.md)**, um die Entwicklererfahrung (DX) für KI-Agenten noch reibungsloser zu gestalten.
Nutzen Sie die Automatisierung, um Ihre CI/CD-Pipeline mit dem LLM Ihrer Wahl auf Kosten Ihres KI-Anbieters zu übersetzen. Intlayer bietet außerdem einen **Compiler** zur Automatisierung der Inhaltsextraktion sowie eine [Webplattform](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md) zur Unterstützung der **Übersetzung im Hintergrund**.
Das Verbinden großer JSON-Dateien mit Komponenten kann zu Leistungs- und Reaktivitätsproblemen führen. Intlayer optimiert das Laden Ihrer Inhalte zur Erstellungszeit.
Intlayer ist mehr als nur eine i18n-Lösung. Es bietet einen **selbstgehosteten [visuellen Editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md)** und ein **[vollständiges CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md)**, um Ihnen zu helfen Verwalten Sie Ihre mehrsprachigen Inhalte in **Echtzeit** und gestalten Sie die Zusammenarbeit mit Übersetzern, Textern und anderen Teammitgliedern reibungslos. Inhalte können lokal und/oder remote gespeichert werden.
---
## Schritt-für-Schritt-Anleitung zur Konfiguration von Intlayer in Astro + React
Sehen Sie sich das [Anwendungstemplate](https://github.com/aymericzip/intlayer-astro-template) auf GitHub an.
Installieren Sie die erforderlichen Pakete mit Ihrem bevorzugten Paketmanager:
```bash packageManager="npm"
npm install intlayer astro-intlayer react react-dom react-intlayer @astrojs/react
npx intlayer init
```
```bash packageManager="pnpm"
pnpm add intlayer astro-intlayer react react-dom react-intlayer @astrojs/react
pnpm intlayer init
```
```bash packageManager="yarn"
yarn add intlayer astro-intlayer react react-dom react-intlayer @astrojs/react
yarn intlayer init
```
```bash packageManager="bun"
bun add intlayer astro-intlayer react react-dom react-intlayer @astrojs/react
bun x intlayer init
```
- **intlayer**
Das Kernpaket, das i18n-Tools für Konfigurationsmanagement, Übersetzungen, [Inhaltsdeklaration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/dictionary/content_file.md), Transpilation und [CLI-Befehle](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/cli/index.md) bereitstellt.
- **astro-intlayer**
Enthält das Astro-Integrations-Plugin, um Intlayer mit dem [Vite-Bundler](https://vite.dev/guide/why.html#why-bundle-for-production) zu verbinden, sowie die Middleware zur Erkennung der bevorzugten Sprache des Benutzers, zur Verwaltung von Cookies und zur Handhabung von URL-Weiterleitungen.
- **react**, **react-dom**
Kern-React-Pakete, die zum Rendern von React-Komponenten im Browser erforderlich sind.
- **react-intlayer**
Paket zur Integration von Intlayer in React-Anwendungen. Es stellt den `IntlayerProvider` sowie die Hooks `useIntlayer` und `useLocale` für die Internationalisierung in React bereit.
- **@astrojs/react**
Offizielle Astro-Integration, die die Verwendung von React-Komponenten-Islands ermöglicht.
Erstellen Sie eine Konfigurationsdatei, um die Sprachen Ihrer Anwendung zu definieren:
```typescript fileName="intlayer.config.ts"
import { Locales, type IntlayerConfig } from "intlayer";
const config: IntlayerConfig = {
internationalization: {
locales: [
Locales.ENGLISH,
Locales.FRENCH,
Locales.SPANISH,
Locales.GERMAN,
// Ihre anderen Sprachen
],
defaultLocale: Locales.ENGLISH,
},
};
export default config;
```
> Über diese Konfigurationsdatei können Sie lokalisierte URLs, Middleware-Weiterleitungen, Cookie-Namen, Speicherort und Erweiterungen der Inhaltsdeklarationen konfigurieren, Intlayer-Logs in der Konsole deaktivieren und vieles mehr. Eine vollständige Liste der verfügbaren Parameter finden Sie in der [Konfigurationsdokumentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/configuration.md).
Fügen Sie das `intlayer`-Plugin und die React-Integration zu Ihrer Astro-Konfiguration hinzu.
```typescript fileName="astro.config.ts"
// @ts-check
import { intlayer } from "astro-intlayer";
import react from "@astrojs/react";
import { defineConfig } from "astro/config";
// https://astro.build/config
export default defineConfig({
integrations: [intlayer(), react()],
});
```
> Das Integrations-Plugin `intlayer()` wird verwendet, um Intlayer in Astro zu integrieren. Es sorgt für die Generierung der Inhaltsdeklarationsdateien und überwacht diese im Entwicklungsmodus. Es definiert Intlayer-Umgebungsvariablen innerhalb der Astro-Anwendung und stellt Aliase zur Optimierung der Leistung bereit.
> Die `react()`-Integration ermöglicht es Ihnen, React-Komponenten-Islands über `client:only="react"` zu verwenden.
Erstellen und verwalten Sie Ihre Inhaltsdeklarationen, um Übersetzungen zu speichern:
```tsx fileName="src/app.content.tsx"
import { t, type Dictionary } from "intlayer";
import type { ReactNode } from "react";
const appContent = {
key: "app",
content: {
title: t({
en: "Hello World",
fr: "Bonjour le monde",
es: "Hola mundo",
de: "Hallo Welt",
}),
},
} satisfies Dictionary;
export default appContent;
```
> Inhaltsdeklarationen können überall in Ihrer Anwendung definiert werden, solange sie im `contentDir` (standardmäßig `./src`) enthalten sind und der Erweiterung der Inhaltsdeklarationsdateien (standardmäßig `.content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}`) entsprechen.
> Weitere Informationen finden Sie in der [Inhaltsdeklarations-Dokumentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/dictionary/content_file.md).
Sie können die Wörterbücher direkt in Ihren `.astro`-Dateien verwenden, indem Sie die von `intlayer` exportierten Kern-Helfer nutzen. Sie sollten außerdem SEO-Metadaten (wie hreflang und Canonical-Links) zu jeder Seite hinzufügen und ein React-Island für interaktive clientseitige Inhalte einführen.
```astro fileName="src/pages/[...locale]/index.astro"
---
import {
getIntlayer,
getLocaleFromPath,
getLocalizedUrl,
getHTMLTextDir,
getPrefix,
localeMap,
defaultLocale,
type LocalesValues,
} from "intlayer";
import { ReactIsland } from "../../components/react/ReactIsland";
export const getStaticPaths = () => {
return localeMap(({ locale }) => ({
params: { locale: getPrefix(locale).localePrefix },
}));
};
const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;
const { title } = getIntlayer("app", locale);
---
{title}
{
localeMap(({ locale: mapLocale }) => (
))
}
```
> Wenn Sie Ihren Inhalt in einem `String`-Attribut wie `alt`, `title`, `href`, `aria-label` usw. verwenden möchten, können Sie den Wert der Funktion wie folgt verwenden:
> ```html
>
>
>
> ```
> **Hinweis zum Routing-Setup:**
> Die von Ihnen verwendete Verzeichnisstruktur hängt von der Einstellung `middleware.routing` in `intlayer.config.ts` ab:
>
> - **`prefix-no-default` (Standard):** behält die Standardsprache im Stammverzeichnis (kein Präfix) und stellt anderen Sprachen Präfixe voran. Verwenden Sie `[...locale]`, um alle Fälle abzudecken.
> - **`prefix-all`:** Alle URLs erhalten ein Sprachpräfix. Sie können das standardmäßige `[locale]` verwenden, wenn Sie den Stamm nicht separat behandeln müssen.
> - **`search-param` oder `no-prefix`:** Es werden keine Sprachverzeichnisse benötigt. Die Sprache wird über Abfrageparameter oder Cookies verwaltet.
Erstellen Sie eine Island-Komponente, die Ihre React-Anwendung umschließt und die vom Server erkannte Sprache empfängt:
```tsx fileName="src/components/react/ReactIsland.tsx"
/** @jsxImportSource react */
import { IntlayerProvider, useIntlayer } from "react-intlayer";
import { type LocalesValues } from "intlayer";
import { LocaleSwitcher } from "./LocaleSwitcher";
function App() {
const { title } = useIntlayer("app");
return (
{title}
);
}
export function ReactIsland({ locale }: { locale: LocalesValues }) {
return (
);
}
```
> Das Attribut `locale` wird von der Astro-Seite (Server-Erkennung) an den `IntlayerProvider` übergeben, wodurch es zur Ausgangssprache für alle React-Hooks innerhalb des Baums wird.
Erstellen Sie eine React-Komponente `LocaleSwitcher`, die die verfügbaren Sprachen liest und bei Auswahl einer neuen Sprache durch den Benutzer zur lokalisierten URL navigiert:
```tsx fileName="src/components/react/LocaleSwitcher.tsx"
/** @jsxImportSource react */
import { useLocale } from "react-intlayer";
import { getLocalizedUrl, getLocaleName, type LocalesValues } from "intlayer";
export function LocaleSwitcher() {
const { locale, availableLocales, setLocale } = useLocale({
onLocaleChange: (newLocale: LocalesValues) => {
// Bei Sprachwechsel zur lokalisierten URL navigieren
window.location.href = getLocalizedUrl(
window.location.pathname,
newLocale
);
},
});
return (
Sprache wechseln:
{availableLocales.map((localeItem) => (
))}
);
}
```
> **Hinweis zur Beständigkeit:**
> Die Verwendung von `onLocaleChange` zur Weiterleitung über `window.location.href` stellt sicher, dass die URL der neuen Sprache besucht wird, sodass die Intlayer-Middleware das Sprach-Cookie setzen kann und die Präferenz des Benutzers bei zukünftigen Besuchen erhalten bleibt.
> Der `LocaleSwitcher` muss innerhalb des `IntlayerProvider` gerendert werden - verwenden Sie ihn in Ihrer Island-Komponente (wie in Schritt 6 gezeigt).
Intlayer bietet Dienstprogramme zum dynamischen Erstellen Ihrer lokalisierten Sitemap und Robots.txt-Dateien.
#### Sitemap
Intlayer wird mit einem integrierten Sitemap-Generator geliefert, mit dem Sie ganz einfach eine Sitemap für Ihre Anwendung erstellen können. Er berücksichtigt lokalisierte Routen und fügt die erforderlichen Metadaten für Suchmaschinen hinzu.
> Die von Intlayer generierte Sitemap unterstützt den `xhtml:link`-Namespace (Hreflang XML-Erweiterungen). Im Gegensatz zu Standard-Sitemap-Generatoren, die nur rohe URLs auflisten, erstellt Intlayer automatisch die erforderlichen bidirektionalen Links zwischen allen Sprachversionen einer Seite (z. B. `/about`, `/about?lang=fr` und `/about?lang=es`). Dies stellt sicher, dass Suchmaschinen die richtige Sprachversion korrekt indexieren und der richtigen Zielgruppe bereitstellen.
Erstellen Sie `src/pages/sitemap.xml.ts`, um eine Sitemap zu generieren, die alle Ihre lokalisierten Routen enthält.
```typescript fileName="src/pages/sitemap.xml.ts"
import type { APIRoute } from "astro";
import { generateSitemap, type SitemapUrlEntry } from "intlayer";
const pathList: SitemapUrlEntry[] = [
{ path: "/", changefreq: "daily", priority: 1.0 },
{ path: "/about", changefreq: "monthly", priority: 0.7 },
];
const SITE_URL = import.meta.env.SITE ?? "http://localhost:4321";
export const GET: APIRoute = async ({ site }) => {
const xmlOutput = generateSitemap(pathList, { siteUrl: SITE_URL });
return new Response(xmlOutput, {
headers: { "Content-Type": "application/xml" },
});
};
```
#### Robots.txt
Erstellen Sie `src/pages/robots.txt.ts`, um das Crawling durch Suchmaschinen zu steuern.
```typescript fileName="src/pages/robots.txt.ts"
import type { APIRoute } from "astro";
import { getMultilingualUrls } from "intlayer";
const getAllMultilingualUrls = (urls: string[]) =>
urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);
const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);
export const GET: APIRoute = ({ site }) => {
const robotsTxt = [
"User-agent: *",
"Allow: /",
...disallowedPaths.map((path) => `Disallow: ${path}`),
"",
`Sitemap: ${new URL("/sitemap.xml", site).href}`,
].join("\n");
return new Response(robotsTxt, {
headers: { "Content-Type": "text/plain" },
});
};
```
Wenn Sie eine bestehende Codebasis haben, kann die Transformation von Tausenden von Dateien zeitaufwendig sein.
Um diesen Prozess zu erleichtern, bietet Intlayer einen [Compiler](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/compiler.md) / [Extractor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/cli/extract.md) an, um Ihre Komponenten zu transformieren und den Inhalt zu extrahieren.
Um es einzurichten, können Sie einen `compiler`-Abschnitt in Ihrer `intlayer.config.ts`-Datei hinzufügen:
```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
import { type IntlayerConfig } from "intlayer";
const config: IntlayerConfig = {
// ... Rest Ihrer Konfiguration
compiler: {
/**
* Gibt an, ob der Compiler aktiviert sein soll.
*/
enabled: true,
/**
* Definiert den Pfad der Ausgabedateien
*/
output: ({ fileName, extension }) => `./${fileName}${extension}`,
/**
* Gibt an, ob die Komponenten nach der Transformation gespeichert werden sollen. Auf diese Weise kann der Compiler nur einmal ausgeführt werden, um die App zu transformieren, und dann entfernt werden.
*/
saveComponents: false,
/**
* Präfix für Wörterbuchschlüssel
*/
dictionaryKeyPrefix: "",
},
};
export default config;
```
Führen Sie den Extractor aus, um Ihre Komponenten zu transformieren und den Inhalt zu extrahieren
```bash packageManager="npm"
npx intlayer extract
```
```bash packageManager="pnpm"
pnpm intlayer extract
```
```bash packageManager="yarn"
yarn intlayer extract
```
```bash packageManager="bun"
bun x intlayer extract
```
Aktualisieren Sie Ihre `vite.config.ts`, um das `intlayerCompiler`-Plugin aufzunehmen:
```ts fileName="vite.config.ts"
import { defineConfig } from "vite";
import { intlayer, intlayerCompiler } from "vite-intlayer";
export default defineConfig({
plugins: [
intlayer(),
intlayerCompiler(), // Fügt das Compiler-Plugin hinzu
],
});
```
```bash packageManager="npm"
npm run build # Oder npm run dev
```
```bash packageManager="pnpm"
pnpm run build # Oder pnpm run dev
```
```bash packageManager="yarn"
yarn build # Oder yarn dev
```
```bash packageManager="bun"
bun run build # Or bun run dev
```
---
### TypeScript-Konfiguration
Intlayer verwendet die Modulerweiterung (Module Augmentation), um TypeScript zu nutzen und Ihre Codebasis robuster zu machen.


Stellen Sie sicher, dass Ihre TypeScript-Konfiguration die automatisch generierten Typen enthält.
```json5 fileName="tsconfig.json"
{
// ... Ihre bestehende TypeScript-Konfiguration
"include": [
// ... Ihre bestehende TypeScript-Konfiguration
".intlayer/**/*.ts", // Automatisch generierte Typen einbeziehen
],
}
```
### Git-Konfiguration
Es wird empfohlen, von Intlayer generierte Dateien zu ignorieren. Dies verhindert, dass sie in Ihr Git-Repository eingecheckt werden.
Fügen Sie dazu die folgenden Anweisungen zu Ihrer `.gitignore`-Datei hinzu:
```bash
# Von Intlayer generierte Dateien ignorieren
.intlayer
```
### VS Code Erweiterung
Um Ihr Entwicklungserlebnis mit Intlayer zu verbessern, können Sie die **offizielle Intlayer VS Code Erweiterung** installieren.
[Installation über den VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
Diese Erweiterung bietet:
- **Autovervollständigung** für Übersetzungsschlüssel.
- **Echtzeit-Fehlererkennung** für fehlende Übersetzungen.
- **Inline-Vorschau** von übersetzten Inhalten.
- **Schnelle Aktionen** zum einfachen Erstellen und Aktualisieren von Übersetzungen.
Weitere Informationen zur Verwendung der Erweiterung finden Sie in der [Dokumentation zur VS Code Erweiterung](https://intlayer.org/doc/vs-code-extension).
---
### Vertiefen Sie Ihr Wissen
Wenn Sie mehr erfahren möchten, können Sie auch den [Visual Editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/intlayer_visual_editor.md) oder das [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/intlayer_CMS.md) verwenden, um Ihre Inhalte zu externalisieren.