Übersetzen Sie Ihre Astro + Vue 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:

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

Sehen Sie sich das Anwendungstemplate auf GitHub an.

1. 1

   Abhängigkeiten installieren

   Installieren Sie die erforderlichen Pakete mit Ihrem bevorzugten Paketmanager:

   bash

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   npx intlayer init --interactive
   

   Das Flag --interactive ist optional. Verwenden Sie intlayer-cli init, wenn Sie ein KI-Agent sind.

   Dieser Befehl erkennt Ihre Umgebung und installiert die erforderlichen Pakete. Zum Beispiel:

   bash

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   npm install intlayer astro-intlayer vue vue-intlayer @astrojs/vue
   

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

   • vue Das Kern-Vue-Paket.

   • vue-intlayer Paket zur Integration von Intlayer in Vue-Anwendungen. Es stellt installIntlayer sowie die Composables useIntlayer und useLocale für die Internationalisierung in Vue bereit.

   • @astrojs/vue Offizielle Astro-Integration, die die Verwendung von Vue-Komponenten-Islands ermöglicht.

2. 2

   Konfigurieren Sie Ihr Projekt

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

   intlayer.config.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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.

3. 3

   Integrieren Sie Intlayer in Ihre Astro-Konfiguration

   Fügen Sie das intlayer-Plugin und die Vue-Integration zu Ihrer Astro-Konfiguration hinzu.

   astro.config.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   // @ts-check
   
   import { intlayer } from "astro-intlayer";
   import vue from "@astrojs/vue";
   import { defineConfig } from "astro/config";
   
   // https://astro.build/config
   export default defineConfig({
     integrations: [intlayer(), vue()],
   });
   

   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 vue()-Integration ermöglicht es Ihnen, Vue-Komponenten-Islands über client:only="vue" zu verwenden.

4. 4

   Deklarieren Sie Ihren Inhalt

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

   src/app.content.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   import { t, type Dictionary } from "intlayer";
   
   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. 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. Sie sollten außerdem SEO-Metadaten (wie hreflang und Canonical-Links) zu jeder Seite hinzufügen und ein Vue-Island für interaktive clientseitige Inhalte einführen.

   src/pages/[...locale]/index.astro

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   ---
   import {
     getIntlayer,
     getLocaleFromPath,
     getLocalizedUrl,
     getHTMLTextDir,
     getPrefix,
     localeMap,
     defaultLocale,
     type LocalesValues,
   } from "intlayer";
   import VueIsland from "../../components/vue/VueIsland.vue";
   
   export const getStaticPaths = () => {
     return localeMap(({ locale }) => ({
       params: { locale: getPrefix(locale).localePrefix },
     }));
   };
   
   const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;
   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: Informiert Suchmaschinen über die Hauptversion dieser Seite -->
       <link
         rel="canonical"
         href={new URL(getLocalizedUrl(Astro.url.pathname, locale), Astro.site)}
       />
   
       <!-- Hreflang: Informiert Google über alle lokalisierten Versionen -->
       {
         localeMap(({ locale: mapLocale }) => (
           <link
             rel="alternate"
             hreflang={mapLocale}
             href={new URL(
               getLocalizedUrl(Astro.url.pathname, mapLocale),
               Astro.site
             )}
           />
         ))
       }
   
       <!-- x-default: Fallback-Option, wenn die Sprache nicht mit der des Benutzers übereinstimmt -->
       <link
         rel="alternate"
         hreflang="x-default"
         href={new URL(
           getLocalizedUrl(Astro.url.pathname, defaultLocale),
           Astro.site
         )}
       />
     </head>
     <body>
       <!-- Das Vue-Island rendert alle interaktiven Inhalte, einschließlich des Sprachumschalters -->
       <VueIsland locale={locale} client:only="vue" />
     </body>
   </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.

6. 6

   Erstellen Sie eine Vue-Island-Komponente

   Erstellen Sie eine Island-Komponente, die Ihre Vue-Anwendung umschließt und die vom Server erkannte Sprache empfängt. Sie müssen das Intlayer-Plugin in der Vue-Instanz registrieren, indem Sie installIntlayer aufrufen, bevor Sie Composables nutzen.

   src/components/vue/VueIsland.vue

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   <script setup lang="ts">
   import { ref, getCurrentInstance } from "vue";
   import { useIntlayer, useLocale, installIntlayer } from "vue-intlayer";
   import { getLocalizedUrl, getLocaleName, type LocalesValues } from "intlayer";
   
   const props = defineProps<{ locale: LocalesValues }>();
   
   const app = getCurrentInstance()?.appContext.app;
   if (app) {
     installIntlayer(app, { locale: props.locale });
   }
   
   const {
     locale: currentLocale,
     availableLocales,
     setLocale,
   } = useLocale({
     onLocaleChange: (newLocale: LocalesValues) => {
       window.location.href = getLocalizedUrl(window.location.pathname, newLocale);
     },
   });
   
   const count = ref(0);
   const { title } = useIntlayer("app");
   </script>
   
   <template>
     <div>
       <h1>{{ title }}</h1>
       <!-- Sprachumschalter wird direkt im Island-Template gerendert -->
       <div class="locale-switcher">
         <span class="switcher-label">Sprache wechseln:</span>
         <div class="locale-buttons">
           <button
             v-for="localeItem in availableLocales"
             :key="localeItem"
             :class="['locale-btn', { active: localeItem === currentLocale }]"
             :disabled="localeItem === currentLocale"
             @click="setLocale(localeItem)"
           >
             <span class="ls-own-name">{{ getLocaleName(localeItem) }}</span>
             <span class="ls-current-name">{{
               getLocaleName(localeItem, currentLocale)
             }}</span>
             <span class="ls-code">{{ localeItem.toUpperCase() }}</span>
           </button>
         </div>
       </div>
     </div>
   </template>
   

   Das Attribut locale wird von der Astro-Seite (Server-Erkennung) übergeben und zur Initialisierung von installIntlayer verwendet, was die Ausgangssprache für alle Composables innerhalb des Baums bestimmt.

7. 7

   Fügen Sie einen Sprachumschalter hinzu

   Die Funktionalität des Sprachumschalters ist direkt im Vue-Island-Template integriert (siehe Schritt 6 oben). Sie verwendet das useLocale-Composable von vue-intlayer und navigiert bei Auswahl einer neuen Sprache durch den Benutzer zur lokalisierten URL:

   src/components/vue/VueIsland.vue

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   <script setup lang="ts">
   import { useLocale } from "vue-intlayer";
   import { getLocalizedUrl, getLocaleName, type LocalesValues } from "intlayer";
   
   // Gleiche Props/Setup-App wie in Schritt 6 gezeigt wiederverwenden...
   
   const {
     locale: currentLocale,
     availableLocales,
     setLocale,
   } = useLocale({
     onLocaleChange: (newLocale: LocalesValues) => {
       // Bei Sprachwechsel zur lokalisierten URL navigieren
       window.location.href = getLocalizedUrl(window.location.pathname, newLocale);
     },
   });
   </script>
   
   <template>
     <div class="locale-switcher">
       <span class="switcher-label">Sprache wechseln:</span>
       <div class="locale-buttons">
         <button
           v-for="localeItem in availableLocales"
           :key="localeItem"
           :class="['locale-btn', { active: localeItem === currentLocale }]"
           :disabled="localeItem === currentLocale"
           @click="setLocale(localeItem)"
         >
           <span class="ls-own-name">{{ getLocaleName(localeItem) }}</span>
           <span class="ls-current-name">{{
             getLocaleName(localeItem, currentLocale)
           }}</span>
           <span class="ls-code">{{ localeItem.toUpperCase() }}</span>
         </button>
       </div>
     </div>
   </template>
   

   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.

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

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

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

   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

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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;
   

   ExtraktionsbefehlBabel-Compiler

   Führen Sie den Extractor aus, um Ihre Komponenten zu transformieren und den Inhalt zu extrahieren

   bash

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   import { defineConfig } from "vite";
   import { intlayer, intlayerCompiler } from "vite-intlayer";
   
   export default defineConfig({
     plugins: [
       intlayer(),
       intlayerCompiler(), // Adds the compiler plugin
     ],
   });
   

   bash

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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.

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.

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.

Häufig gestellte Fragen