Übersetzen Sie Ihre Vite und Vanilla JS Website mit Intlayer | Internationalisierung (i18n)

Inhaltsverzeichnis

Warum Intlayer gegenüber Alternativen?

Im Vergleich zu Hauptlösungen wie „i18next“ oder „i18n.js“ ist Intlayer eine Lösung, die über integrierte Optimierungen verfügt wie:

Schritt-für-Schritt-Anleitung zur Einrichtung von Intlayer in einer Vite und Vanilla JS Anwendung

1. 1

   Abhängigkeiten installieren

   Installieren Sie die notwendigen Pakete mit npm:

   bash

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   npm install intlayer vanilla-intlayernpm install vite-intlayer --save-devnpx intlayer init

   • intlayer Das Kernpaket, das Internationalisierungswerkzeuge für Konfigurationsmanagement, Übersetzung, Inhaltsdeklaration, Transpilierung und CLI-Befehle bereitstellt.

   • vanilla-intlayer Das Paket, das Intlayer in einfache JavaScript / TypeScript Anwendungen integriert. Es bietet ein Pub/Sub-Singleton (IntlayerClient) und Callback-basierte Helfer (useIntlayer, useLocale usw.), sodass jeder Teil Ihrer App auf Sprachänderungen reagieren kann, ohne von einem UI-Framework abhängig zu sein.

   • vite-intlayer Enthält das Vite-Plugin zur Integration von Intlayer in den Vite-Bundler sowie Middleware zur Erkennung der bevorzugten Sprache des Benutzers, zur Verwaltung von Cookies und zur Handhabung von URL-Weiterleitungen.

2. 2

   Konfiguration Ihres Projekts

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

   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,
         // Ihre anderen Sprachen
       ],
       defaultLocale: Locales.ENGLISH,
     },
   };
   
   export default config;

   Über diese Konfigurationsdatei können Sie lokalisierte URLs, Middleware-Weiterleitungen, Cookie-Namen, den Speicherort und die Erweiterung Ihrer Inhaltsdeklarationen festlegen, Intlayer-Protokolle in der Konsole deaktivieren und vieles mehr. Eine vollständige Liste der verfügbaren Parameter finden Sie in der Konfigurationsdokumentation.

3. 3

   Intlayer in Ihre Vite-Konfiguration integrieren

   Fügen Sie das intlayer-Plugin in Ihre Konfiguration ein.

   vite.config.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   import { defineConfig } from "vite";
   import { intlayer } from "vite-intlayer";
   
   // https://vitejs.dev/config/
   export default defineConfig({
     plugins: [intlayer()],
   });

   Das Vite-Plugin intlayer() wird verwendet, um Intlayer in Vite zu integrieren. Es stellt die Erstellung von Inhaltsdeklarationsdateien sicher und überwacht diese im Entwicklungsmodus. Es definiert Intlayer-Umgebungsvariablen innerhalb der Vite-Anwendung. Zusätzlich bietet es Aliase zur Leistungsoptimierung.

4. 4

   Intlayer in Ihrem Einstiegspunkt initialisieren

   Rufen Sie installIntlayer() auf, bevor Inhalte gerendert werden, damit das globale Sprach-Singleton bereit ist.

   src/main.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   import { installIntlayer } from "vanilla-intlayer";// Muss vor dem Rendern von i18n-Inhalten aufgerufen werden.installIntlayer();// Importieren und führen Sie Ihre Anwendungsmodule aus.import "./app.js";

   Wenn Sie auch md() Inhaltsdeklarationen (Markdown) verwenden, installieren Sie auch den Markdown-Renderer:

   src/main.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   import { installIntlayer, installIntlayerMarkdown } from "vanilla-intlayer";installIntlayer();installIntlayerMarkdown();import "./app.js";

5. 5

   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 { insert, t, type Dictionary } from "intlayer";
   
   const appContent = {
     key: "app",
     content: {
       title: "Vite + Vanilla",
   
       viteLogoLabel: t({
         en: "Vite Logo",
         fr: "Logo Vite",
         es: "Logo Vite",
       }),
   
       count: insert(
         t({
           en: "count is {{count}}",
           fr: "le compte est {{count}}",
           es: "el recuento es {{count}}",
         })
       ),
   
       readTheDocs: t({
         en: "Click on the Vite logo to learn more",
         fr: "Cliquez sur le logo Vite pour en savoir plus",
         es: "Haga clic en el logotipo de Vite für weitere Informationen",
       }),
     },
   } satisfies Dictionary;
   
   export default appContent;

   Ihre Inhaltsdeklarationen können überall in Ihrer Anwendung definiert werden, solange sie im Verzeichnis contentDir (standardmäßig ./src) enthalten sind und der Dateierweiterung für Inhaltsdeklarationen (standardmäßig .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}) entsprechen.

   Für weitere Details besuchen Sie die Dokumentation zur Inhaltsdeklaration.

6. 6

   Intlayer in Ihrem JavaScript verwenden

   vanilla-intlayer spiegelt die Oberflächen-API von react-intlayer wider: useIntlayer(key, locale?) gibt den übersetzten Inhalt direkt zurück. Verketten Sie .onChange() am Ergebnis, um Sprachänderungen zu abonnieren - das explizite Äquivalent zu einem React-Re-Render.

   src/main.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   import { installIntlayer, useIntlayer } from "vanilla-intlayer";installIntlayer();// Erhalten Sie den anfänglichen Inhalt für die aktuelle Sprache.// Verketten Sie .onChange(), um benachrichtigt zu werden, wenn sich die Sprache ändert.const content = useIntlayer("app").onChange((newContent) => {  // Nur die betroffenen DOM-Knoten neu rendern oder patchen  document.querySelector<HTMLHeadingElement>("h1")!.textContent = String(    newContent.title  );  document.querySelector<HTMLParagraphElement>(".read-the-docs")!.textContent =    String(newContent.readTheDocs);});// Erstmaliges Renderndocument.querySelector<HTMLHeadingElement>("h1")!.textContent = String(  content.title);document.querySelector<HTMLParagraphElement>(".read-the-docs")!.textContent =  String(content.readTheDocs);

   Greifen Sie auf Endwerte als Zeichenfolgen zu, indem Sie sie in String() einschließen, was die toString()-Methode des Knotens aufruft und den übersetzten Text zurückgibt.

   Wenn Sie den Wert für ein natives HTML-Attribut benötigen (z. B. alt, aria-label), verwenden Sie direkt .value:

   typescript

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   img.alt = content.viteLogoLabel.value;

7. 7

   Die Sprache Ihres Inhalts ändern

   Optional

   Um die Sprache Ihres Inhalts zu ändern, verwenden Sie die Funktion setLocale, die von useLocale bereitgestellt wird.

   src/locale-switcher.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   import { getLocaleName } from "intlayer";import { useLocale } from "vanilla-intlayer";export function setupLocaleSwitcher(container: HTMLElement): () => void {  const { locale, availableLocales, setLocale, subscribe } = useLocale();  const select = document.createElement("select");  select.setAttribute("aria-label", "Language");  const render = (currentLocale: string) => {    select.innerHTML = availableLocales      .map(        (loc) =>          `<option value="${loc}"${loc === currentLocale ? " selected" : ""}>            ${getLocaleName(loc)}          </option>`      )      .join("");  };  render(locale);  container.appendChild(select);  select.addEventListener("change", () => setLocale(select.value as any));  // Dropdown synchron halten, wenn sich die Sprache von anderer Stelle aus ändert  return subscribe((newLocale) => render(newLocale));}

8. 8

   Markdown- und HTML-Inhalte rendern

   Optional

   Intlayer unterstützt md() und html() Inhaltsdeklarationen. In Vanilla JS wird die kompilierte Ausgabe als rohes HTML über innerHTML eingefügt.

   Kompilieren und injizieren Sie das HTML:

   src/main.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   import {  compileMarkdown,  installIntlayerMarkdown,  useIntlayer,} from "vanilla-intlayer";installIntlayerMarkdown();const content = useIntlayer("app").onChange((newContent) => {  const el = document.querySelector<HTMLDivElement>(".edit-note")!;  el.innerHTML = compileMarkdown(String(newContent.editNote));});document.querySelector<HTMLDivElement>(".edit-note")!.innerHTML =  compileMarkdown(String(content.editNote));

   TIP

   String(content.editNote) ruft toString() auf dem IntlayerNode auf, was den rohen Markdown-String zurückgibt. Übergeben Sie diesen an compileMarkdown, um einen HTML-String zu erhalten, und setzen Sie ihn dann über innerHTML.

   WARNING

   Verwenden Sie innerHTML nur mit vertrauenswürdigen Inhalten. Wenn der Markdown aus Benutzereingaben stammt, bereinigen Sie ihn zuerst (z. B. mit DOMPurify). Sie können einen bereinigenden Renderer dynamisch installieren:

   typescript

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   import { installIntlayerMarkdownDynamic } from "vanilla-intlayer";await installIntlayerMarkdownDynamic(async () => {  const DOMPurify = await import("dompurify");  return (markdown) => DOMPurify.sanitize(compileMarkdown(markdown));});

9. 9

   Lokalisiertes Routing zu Ihrer Anwendung hinzufügen

   Optional

   Um eindeutige Routen für jede Sprache zu erstellen (nützlich für SEO), können Sie intlayerProxy in Ihrer Vite-Konfiguration zur serverseitigen Spracherkennung verwenden.

   Fügen Sie zuerst intlayerProxy zu Ihrer Vite-Konfiguration hinzu:

   Beachten Sie, dass Sie für die Verwendung von intlayerProxy in der Produktion vite-intlayer von devDependencies zu dependencies verschieben müssen.

   vite.config.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   import { defineConfig } from "vite";
   import { intlayer, intlayerProxy } from "vite-intlayer";
   
   export default defineConfig({
     plugins: [
       intlayerProxy(), // sollte zuerst platziert werden
       intlayer(),
     ],
   });

10. 10

    Die URL ändern, wenn sich die Sprache ändert

    Optional

    Um die Browser-URL zu aktualisieren, wenn sich die Sprache ändert, rufen Sie useRewriteURL() nach der Installation von Intlayer auf:

    src/main.ts

    Inhalt kopieren

    Code kopieren

    Kopieren Sie den Code in die Zwischenablage

    import { installIntlayer, useRewriteURL } from "vanilla-intlayer";installIntlayer();// Schreibt die URL sofort und bei jeder nachfolgenden Sprachänderung um.// Gibt eine Unsubscribe-Funktion für die Bereinigung zurück.const stopRewriteURL = useRewriteURL();

11. 11

    Wechseln der HTML-Sprach- und Richtungsattribute

    Optional

    Aktualisieren Sie die Attribute lang und dir des <html>-Tags entsprechend der aktuellen Sprache für Barrierefreiheit und SEO.

    src/main.ts

    Inhalt kopieren

    Code kopieren

    Kopieren Sie den Code in die Zwischenablage

    import { getHTMLTextDir } from "intlayer";import { installIntlayer, useLocale } from "vanilla-intlayer";installIntlayer();useLocale({  onLocaleChange: (locale) => {    document.documentElement.lang = locale;    document.documentElement.dir = getHTMLTextDir(locale);  },});

12. 12

    Wörterbücher pro Sprache lazy-loaden

    Optional

    Für große Apps möchten Sie vielleicht das Wörterbuch jeder Sprache in einen eigenen Chunk aufteilen. Verwenden Sie useDictionaryDynamic zusammen mit dem dynamischen import() von Vite:

    src/app.ts

    Inhalt kopieren

    Code kopieren

    Kopieren Sie den Code in die Zwischenablage

    import { installIntlayer, useDictionaryDynamic } from "vanilla-intlayer";installIntlayer();const unsubscribe = useDictionaryDynamic(  {    en: () => import("../.intlayer/dictionaries/en/app.mjs"),    fr: () => import("../.intlayer/dictionaries/fr/app.mjs"),    es: () => import("../.intlayer/dictionaries/es/app.mjs"),  },  "app").onChange((content) => {  document.querySelector("h1")!.textContent = String(content.title);});

    Das Bundle jeder Sprache wird nur abgerufen, wenn diese Sprache aktiv wird, und das Ergebnis wird zwischengespeichert - nachfolgende Wechsel zur gleichen Sprache erfolgen sofort.

13. 13

    Den 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, schlägt Intlayer einen Compiler / Extractor vor, um Ihre Komponenten zu transformieren und den Inhalt zu extrahieren.

    Um dies 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 kann dann entfernt werden.     */    saveComponents: false,    /**     * Wörterbuchschlüssel-Präfix     */    dictionaryKeyPrefix: "",  },};export default config;

    Extraktions-BefehlBabel-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

    Aktualisieren Sie Ihre vite.config.ts, um das Plugin intlayerCompiler 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(), // Fügt das Compiler-Plugin hinzu ],});

    bash

    Inhalt kopieren

    Code kopieren

    Kopieren Sie den Code in die Zwischenablage

    npm run build # Oder npm run dev

(Optional) Sitemap und robots.txt (Build-Zeit)

Intlayer stellt Hilfsfunktionen bereit - generateSitemap und getMultilingualUrls -, mit denen Sie mehrsprachige sitemap.xml- und robots.txt-Inhalte für Crawler formatieren und automatisch nach public/ schreiben können. Üblich ist ein kleines Node-Skript vor Vite (z. B. npm-predev-/prebuild-Hooks), damit die Dateien beim Build bzw. Dev-Server vorliegen.

Sitemap

Der Sitemap-Generator von Intlayer berücksichtigt Ihre Locales und die üblichen Metadaten für Crawler.

Die erzeugte Sitemap unterstützt den xhtml:link-Namensraum (Hreflang). Statt nur flacher URLs verknüpft Intlayer alle Sprachversionen einer Seite bidirektional (z. B. /about, /fr/about oder /about?lang=fr je nach Routing), was Suchmaschinen hilft.

Robots.txt

Mit getMultilingualUrls gelten Disallow-Regeln für alle lokalisierten Varianten sensibler Pfade.

1. generate-seo.mjs im Projektroot anlegen

import fs from "fs";import path from "path";import { fileURLToPath } from "url";import { generateSitemap, getMultilingualUrls } from "intlayer";const __dirname = path.dirname(fileURLToPath(import.meta.url));const SITE_URL = (process.env.SITE_URL || "http://localhost:5173").replace(  /\/$/,  "");const pathList = [  { path: "/", changefreq: "daily", priority: 1.0 },  { path: "/about", changefreq: "monthly", priority: 0.7 },];const sitemapXml = generateSitemap(pathList, { siteUrl: SITE_URL });fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);const getAllMultilingualUrls = (urls) =>  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);const robotsTxt = [  "User-agent: *",  "Allow: /",  ...disallowedPaths.map((path) => `Disallow: ${path}`),  "",  `Sitemap: ${SITE_URL}/sitemap.xml`,].join("\n");fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);console.log("SEO files generated successfully.");

intlayer muss installiert sein. Setzen Sie SITE_URL in der Produktion über die Umgebung (z. B. in der CI).

Nutzen Sie möglichst generate-seo.mjs für Node-ESM. Bei generate-seo.js "type": "module" in der package.json setzen oder Node mit ESM starten.

2. Skript vor Vite ausführen

{  "scripts": {    "dev": "vite",    "prebuild": "node generate-seo.mjs",    "build": "vite build",    "preview": "vite preview"  }}

Bei pnpm oder yarn die Befehle anpassen. Aufruf aus der CI ist ebenfalls möglich.

TypeScript konfigurieren

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

{  "compilerOptions": {    // ...  },  "include": ["src", ".intlayer/**/*.ts"],}

Git-Konfiguration

Es wird empfohlen, die von Intlayer generierten Dateien zu ignorieren. Dies ermöglicht es Ihnen, zu vermeiden, dass sie in Ihr Git-Repository committet werden.

Um dies zu tun, können Sie die folgenden Anweisungen in Ihre .gitignore-Datei einfügen:

# Ignorieren Sie die von Intlayer generierten Dateien.intlayer

VS Code Erweiterung

Um Ihre Entwicklungserfahrung mit Intlayer zu verbessern, können Sie die offizielle Intlayer VS Code Erweiterung installieren.

Vom VS Code Marketplace installieren

Diese Erweiterung bietet:

• Autovervollständigung für Übersetzungsschlüssel.
• Echtzeit-Fehlererkennung für fehlende Übersetzungen.
• Inline-Vorschauen des übersetzten Inhalts.
• Schnellaktionen, um Übersetzungen einfach zu erstellen und zu aktualisieren.

Weitere Details zur Verwendung der Erweiterung finden Sie in der Dokumentation zur Intlayer VS Code Erweiterung.

Weiter gehen

Um weiter zu gehen, können Sie den visuellen Editor implementieren oder Ihre Inhalte mit dem CMS extern verwalten.