Autor:
    Aymeric PINEAU
    Erstellung:2024-03-07Letzte Aktualisierung:2026-06-23

    Übersetzen Sie Ihre Astro-Website mit Intlayer | Internationalisierung (i18n)

    ide.intlayer.org
    intlayer-astro-template.vercel.app

    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, MCP und agent skills, 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 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 und ein vollständiges CMS, 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

    Sehen Sie sich das Anwendungstemplate auf GitHub an.

    1. Abhängigkeiten installieren

      Installieren Sie die erforderlichen Pakete mit Ihrem bevorzugten Paketmanager:

      bash
      npx intlayer init --interactive
      das Flag --interactive ist optional. Verwenden Sie intlayer-cli init, wenn Sie ein KI-Agent sind.
      Dieser Befehl erkennt deine Umgebung und installiert die erforderlichen Pakete. Zum Beispiel:
      bash
      npm install intlayer astro-intlayer
      bash
      npm install intlayer astro-intlayer
# Optional: Wenn Sie Unterstützung für React-Islands hinzufügen
npm install react react-dom react-intlayer @astrojs/react

      • intlayer Das Kernpaket, das i18n-Tools für Konfigurationsmanagement, Übersetzungen, Inhaltsdeklaration, Transpilation und CLI-Befehle bereitstellt.

      • astro-intlayer Enthält das Astro-Integrations-Plugin, um Intlayer mit dem Vite-Bundler zu verbinden, sowie die Middleware zur Erkennung der bevorzugten Sprache des Benutzers, zur Verwaltung von Cookies und zur Handhabung von URL-Weiterleitungen.

    2. Konfigurieren Sie Ihr Projekt

      Erstellen Sie eine Konfigurationsdatei, um die Sprachen Ihrer Anwendung zu definieren:

      intlayer.config.ts
      import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // 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.

    3. Integrieren Sie Intlayer in Ihre Astro-Konfiguration

      Fügen Sie das intlayer-Plugin zu Ihrer Astro-Konfiguration hinzu.

      astro.config.ts
      // @ts-check

import { intlayer } from "astro-intlayer";
import { defineConfig } from "astro/config";

// https://astro.build/config
export default defineConfig({
  integrations: [intlayer()],
});
      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.

    4. Deklarieren Sie Ihren Inhalt

      Erstellen und verwalten Sie Ihre Inhaltsdeklarationen, um Übersetzungen zu speichern:

      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.

    5. Inhalt in Astro verwenden

      Sie können die Wörterbücher direkt in Ihren .astro-Dateien verwenden, indem Sie die von intlayer exportierten Kern-Helfer nutzen.

      src/pages/index.astro
      ---
import {
  getIntlayer,
  getLocaleFromPath,
  getLocalizedUrl,
  defaultLocale,
  localeMap,
  getHTMLTextDir,
  type LocalesValues,
} from "intlayer";
import LocaleSwitcher from "../components/LocaleSwitcher.astro";

// Get the current locale from the URL (e.g. /es/about -> 'es')
const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;

// Get the content for the 'app' dictionary
const { title } = getIntlayer("app", locale);
---

<!doctype html>
<html lang={locale} dir={getHTMLTextDir(locale)}>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width" />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
    <title>{title}</title>

    <!-- Canonical link: Tells search engines which is the primary version of this page -->
    <link
      rel="canonical"
      href={new URL(getLocalizedUrl(Astro.url.pathname, locale), Astro.site)}
    />

    <!-- Hreflang: Tell Google about all localized versions -->
    {
      localeMap(({ locale: mapLocale }) => (
        <link
          rel="alternate"
          hreflang={mapLocale}
          href={new URL(
            getLocalizedUrl(Astro.url.pathname, mapLocale),
            Astro.site
          )}
        />
      ))
    }

    <!-- x-default: Fallback for users in unmatched languages -->
    <link
      rel="alternate"
      hreflang="x-default"
      href={new URL(
        getLocalizedUrl(Astro.url.pathname, defaultLocale),
        Astro.site
      )}
    />
  </head>
  <body>
    <header>
      <LocaleSwitcher />
    </header>
    <main>
      <h1>{title}</h1>
    </main>
  </body>
</html>

    6. Lokalisiertes Routing

      Erstellen Sie dynamische Pfadsegmente, um lokalisierte Seiten bereitzustellen (z. B. src/pages/[locale]/index.astro):

      src/pages/[locale]/index.astro
      ---
import { getIntlayer } from "intlayer";

const { title } = getIntlayer('app');
---

<h1>{title}</h1>

      Die Astro-Integration fügt eine Vite-Middleware hinzu, die beim sprachsensitiven Routing und bei den Umgebungsdefinitionen während der Entwicklung hilft. Sie können auch sprachübergreifende Links mit Ihrer eigenen Logik oder intlayer-Tools wie getLocalizedUrl erstellen.

    7. Sprachumschalter hinzufügen

      Um Benutzern den Wechsel zwischen Sprachen zu ermöglichen, können Sie eine LocaleSwitcher-Komponente erstellen. Diese Komponente sollte eine Liste aller unterstützten Sprachen anzeigen und auf dieselbe Seite in jeder Sprache verlinken.

      src/components/LocaleSwitcher.astro
      ---
import {
  locales,
  getLocaleName,
  getLocalizedUrl,
  getLocaleFromPath,
  getPathWithoutLocale,
  type LocalesValues,
} from "intlayer";

const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;
const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);
---

<nav>
  {
    locales.map((localeItem) => (
      <a
        href={getLocalizedUrl(pathWithoutLocale, localeItem)}
        data-locale={localeItem}
        aria-current={localeItem === locale ? "page" : undefined}
      >
        {getLocaleName(localeItem)}
      </a>
    ))
  }
</nav>

<script>
  import { setLocaleInStorageClient, getLocalizedUrl, type LocalesValues } from "intlayer";

  const localeLinks = document.querySelectorAll("[data-locale]");

  localeLinks.forEach((link) => {
    link.addEventListener("click", (e) => {
      const locale = link.getAttribute("data-locale") as LocalesValues;

      // Update the locale cookie
      setLocaleInStorageClient(locale);
    });
  });
</script>

<style>
  nav {
    display: flex;
    gap: 1rem;
  }
  a[aria-current="page"] {
    font-weight: bold;
    text-decoration: underline;
  }
</style>

      Hinweis zur Persistenz: Die Verwendung von setLocaleInStorageClient im clientseitigen Skript stellt sicher, dass die Sprachpräferenz des Benutzers in einem Cookie gespeichert wird. Dies ermöglicht es der Intlayer-Middleware, sich an die Auswahl zu erinnern und den Benutzer bei zukünftigen Besuchen automatisch auf seine bevorzugte Sprache umzuleiten.

    8. Sitemap und Robots.txt

      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.

      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.

      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" },
  });
};

    9. Verwenden Sie weiterhin Ihre bevorzugten Frameworks

      Bauen Sie Ihre Anwendung mit dem Framework Ihrer Wahl weiter auf.

    10. Inhalt Ihrer Komponenten extrahieren

      Optional

      Wenn Sie eine bestehende Codebasis haben, kann die Transformation von Tausenden von Dateien zeitaufwendig sein.

      Um diesen Prozess zu erleichtern, bietet Intlayer einen Compiler / Extractor 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:

      intlayer.config.ts
      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
      npx intlayer extract
      Since v9, the intlayerCompiler is included in the intlayer plugin. So you don't need to add it manually.

      Aktualisieren Sie Ihre vite.config.ts, um das intlayerCompiler-Plugin aufzunehmen:

      vite.config.ts
      import { defineConfig } from "vite";
import { intlayer, intlayerCompiler } from "vite-intlayer";

export default defineConfig({
  plugins: [
    intlayer(),
    intlayerCompiler(), // Adds the compiler plugin
  ],
});
      bash
      npm run build # Oder npm run dev

    TypeScript-Konfiguration

    Intlayer verwendet die Modulerweiterung (Module Augmentation), um TypeScript zu nutzen und Ihre Codebasis robuster zu machen.

    Autovervollständigung

    Übersetzungsfehler

    Stellen Sie sicher, dass Ihre TypeScript-Konfiguration die automatisch generierten Typen enthält.

    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

    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.

    Vertiefen Sie Ihr Wissen

    Wenn Sie mehr erfahren möchten, können Sie auch den Visual Editor implementieren oder das CMS verwenden, um Ihre Inhalte zu externalisieren.

    Tanstack Start SolidAstro und React