Übersetzen Sie Ihre Astro + Vanilla JS Website mit Intlayer | Internationalisierung (i18n)

Inhaltsverzeichnis

Was ist Intlayer?

Intlayer ist eine innovative Open-Source-Internationalisierungsbibliothek (i18n), die entwickelt wurde, um die mehrsprachige Unterstützung in modernen Webanwendungen zu vereinfachen.

Mit Intlayer können Sie:

• Übersetzungen einfach verwalten: Deklarative Wörterbücher auf Komponentenebene verwenden.
• Metadaten, Routing und Inhalte dynamisch lokalisieren.
• TypeScript-Unterstützung sicherstellen: Mit automatisch generierten Typen für bessere Autovervollständigung und Fehlererkennung.
• Von erweiterten Funktionen profitieren: Wie dynamische Spracherkennung und Sprachwechsel.

Schritt-für-Schritt-Anleitung zur Konfiguration von Intlayer in Astro + Vanilla JS

Sehen Sie sich das Anwendungstemplate auf GitHub an.

Schritt 1: Abhängigkeiten installieren

Installieren Sie die erforderlichen Pakete mit Ihrem bevorzugten Paketmanager:

npm install intlayer astro-intlayer vanilla-intlayernpx intlayer init

• 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.

• vanilla-intlayer Ein Paket zur Integration von Intlayer in Vanilla-JavaScript / TypeScript-Anwendungen. Es bietet ein Pub/Sub-Singleton (IntlayerClient) und Call-basierte Helfer (useIntlayer, useLocale usw.), die es ermöglichen, dass jeder Teil Ihrer Astro <script>-Tags auf Sprachwechsel reagiert, ohne dass ein Framework erforderlich ist.

Schritt 2: Konfigurieren Sie Ihr Projekt

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

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.

Schritt 3: Integrieren Sie Intlayer in Ihre Astro-Konfiguration

Fügen Sie das intlayer-Plugin zu Ihrer Astro-Konfiguration hinzu. Für Vanilla JS ist keine zusätzliche UI-Framework-Integration erforderlich.

// @ts-checkimport { intlayer } from "astro-intlayer";import { defineConfig } from "astro/config";// https://astro.build/configexport 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.

Schritt 4: Deklarieren Sie Ihren Inhalt

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

import { t, type Dictionary } from "intlayer";const appContent = {  key: "app",  content: {    greeting: t({      en: "Hello World",      fr: "Bonjour le monde",      es: "Hola mundo",      de: "Hallo Welt",    }),    description: t({      en: "Welcome to my multilingual Astro site.",      fr: "Bienvenue sur mon site Astro multilingue.",      es: "Bienvenido a mi sitio Astro multilingüe.",      de: "Willkommen auf meiner mehrsprachigen Astro-Website.",    }),    switchLocale: t({      en: "Switch language:",      fr: "Changer de langue :",      es: "Cambiar idioma:",      de: "Sprache wechseln:",    }),  },} 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}) entsprechen.

Weitere Informationen finden Sie in der Inhaltsdeklarations-Dokumentation.

Schritt 5: Inhalt in Astro verwenden

Bei Vanilla JS erfolgt das gesamte serverseitige Rendering direkt in den .astro-Dateien mit getIntlayer. Anschließend initialisiert ein <script>-Block vanilla-intlayer auf dem Client, um das Umschalten der Sprache zu ermöglichen.

---import {  getIntlayer,  getLocaleFromPath,  getLocalizedUrl,  getPrefix,  getLocaleName,  localeMap,  locales,  defaultLocale,  getPathWithoutLocale,  type LocalesValues,} from "intlayer";export const getStaticPaths = () => {  return localeMap(({ locale }) => ({    params: { locale: getPrefix(locale).localePrefix },  }));};const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);const { greeting, description, switchLocale } = 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>{greeting}</title>    <!-- Canonical Link -->    <link      rel="canonical"      href={new URL(getLocalizedUrl(Astro.url.pathname, locale), Astro.site)}    />    <!-- Hreflang Links -->    {      localeMap(({ locale: mapLocale }) => (        <link          rel="alternate"          hreflang={mapLocale}          href={new URL(            getLocalizedUrl(Astro.url.pathname, mapLocale),            Astro.site          )}        />      ))    }    <link      rel="alternate"      hreflang="x-default"      href={new URL(        getLocalizedUrl(Astro.url.pathname, defaultLocale),        Astro.site      )}    />  </head>  <body>    <main>      <h1 id="greeting">{greeting}</h1>      <p id="description">{description}</p>      <div class="locale-switcher">        <span class="switcher-label">{switchLocale}</span>        <div class="locale-buttons">          {            locales.map((localeItem) => (              <a                href={localeItem === locale ? undefined : getLocalizedUrl(pathWithoutLocale, localeItem)}                class={`locale-btn ${localeItem === locale ? "active" : ""}`}                data-locale={localeItem}                aria-disabled={localeItem === locale}              >                {getLocaleName(localeItem)}              </a>            ))          }        </div>      </div>    </main>  </body></html>

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

Inhalt kopieren

Code kopieren

Kopieren Sie den Code in die Zwischenablage

<img src="{content.image.src.value}" alt="{content.image.value}" /><img src="{content.image.src.toString()}" alt="{content.image.toString()}" /><img src="{String(content.image.src)}" alt="{String(content.image)}" />

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.

Schritt 6: Sprachumschaltung hinzufügen

In Astro mit Vanilla JS wird der Sprachumschalter auf dem Server als normale Links gerendert und auf dem Client über einen <script>-Block hydriert. Wenn ein Benutzer auf einen Sprachlink klickt, setzt vanilla-intlayer das Sprach-Cookie über setLocale, bevor zur lokalisierten URL navigiert wird.

<!-- Serverseitiges Markup aus Schritt 5 oben einbeziehen --><script>  import { installIntlayer, useLocale } from "vanilla-intlayer";  import { getLocaleFromPath, getLocalizedUrl, type LocalesValues } from "intlayer";  // Intlayer auf dem Client mit der Sprache aus der aktuellen URL initialisieren  const locale = getLocaleFromPath(window.location.pathname);  installIntlayer({ locale: locale as LocalesValues });  const { setLocale } = useLocale({    onLocaleChange: (newLocale: LocalesValues) => {      window.location.href = getLocalizedUrl(window.location.pathname, newLocale);    },  });  // Klickevents an die Sprachumschaltlinks binden  const localeLinks = document.querySelectorAll("[data-locale]");  localeLinks.forEach((link) => {    link.addEventListener("click", (e) => {      const localeValue = link.getAttribute("data-locale") as LocalesValues;      if (localeValue && localeValue !== locale) {        e.preventDefault();        setLocale(localeValue);      }    });  });</script>

Hinweis zur Beständigkeit: installIntlayer initialisiert das Intlayer-Singleton mit der vom Server definierten Sprache. useLocale mit onLocaleChange stellt sicher, dass das Sprach-Cookie vor der Navigation über die Middleware gesetzt wird, damit die bevorzugte Sprache des Benutzers bei zukünftigen Besuchen erhalten bleibt.

Hinweis zur Progressive Enhancement: Die Links im Sprachumschalter funktionieren auch ohne JavaScript als standardmäßige <a>-Tags. Wenn JavaScript verfügbar ist, aktualisieren die Aufrufe von setLocale das Cookie vor der Navigation, sodass die Middleware die korrekte Weiterleitung durchführen kann.

Schritt 7: 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.

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.

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

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.

{  // ... 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:

# 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.

(Optional) Schritt 15 : Inhalt Ihrer Komponenten extrahieren

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:

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;

npx intlayer extract

import { defineConfig } from "vite";import { intlayer, intlayerCompiler } from "vite-intlayer";export default defineConfig({ plugins: [   intlayer(),   intlayerCompiler(), // Fügt das Compiler-Plugin hinzu ],});

npm run build # Oder npm run dev

Vertiefen Sie Ihr Wissen

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